JFT/Api Introduction

This manual describes version 4.0.0 of JFT/API, the Java Application Program Interface developed by LIST within FastTrack to access electronic markets and other services handled by FastTrack.

Data structure and functions of JFT/API interface are described, along with the main concepts regarding access to the FastTrack server: connections, data subscriptions, transactions, queries, etc...

The first chapter FastTrack Overview introduces the main basic concepts of FastTrack with a short overview of system architecture.

The second chapter Data Distribution explains how data are distributed, searched and retrieved inside FastTrack.

Chapter three JFT/Api Details describes the main peculiarities of the Java Access Point to FastTrack: lifecycle, communication model, exception handling, threads synchronization, etc...

Following chapters contain the effective and detailed descriptions of the Api subdivided in two different packages: it.list.jft and it.list.jft.event,

Finally, after all details on specific JFT/Api functions, a few examples of Java application are given in order to exploit almost all major capabilities offered by JFT/Api and to be possibly fruitfully studied and used as starting point for effectives Java programs that links to a true FastTrack server.

FastTrack Overview

This chapter explains the basic concepts of FastTrack that are fundamental in developing Java applications that access FastTrack services using this JFT/Api.

System Architecture Overview

FastTrack's architecture is modular and distributed.

There are three different architectural levels for the various components, depending on the service they implement:

The core level is the heart of the system, the foundation of FastTrack's modular architecture.

The set of FastTrack modules managing communication with the external world makes up the basic level. These are organized into two categories: Adapters, through which FastTrack can access other systems or electronic markets, and Access points, which give access to FastTrack from the outside. Finally, the enterprise level hosts the functional applications in FastTrack (Engine level).

FastTrack's components interact both in a synchronous and asynchronous way - the latter uses a publish-subscribe paradigm.

FastTrack is a distributed system. The computing process is subdivided into several steps. It is not performed by one individual component, but by a series of elements (Application Servers or Services) each designed to carry out its particular part of the process.

Access points

The Access Point Level is the only interface FastTrack offers to use its services from the outside.

Queries made to the FastTrack platform and answers to these queries both go through the Access Point Level.

The Access Point Level:

JFT/Api Access Point

This JFT/Api library is just a FastTrack Access Point that offers a Java interface to be used in order to connect FastTrack servers via TCP/IP connections.

Using this library it is possibile to construct Java applications and/or applets that may communicate with one or more FastTrack servers and/or services.

Obviously the effective access to these services is managed/controlled/verified in relation to various credentials (user names, passwords, authorization keys, etc...) that an external application must presents in order to be properly authorized to enter in the system.

Data Distribution

Data are distributed through a publish/subscribe protocol, in which producers and consumers exchange messages to access the data. There are many data structure exchanged within FastTrack. Each data structure is called EntityClass and it is structured in many fields of many different types (numbers, strings, etc...). Each set of values that corresponds to these fields is an instance of the EntityClass. This instance id called Entity. Applications may modify or access an entire Entity (all the fields of an instance of an EntityClass) or a subset of these fields defined using a mask.

From now on we call:

As we will see below, normally a client is a subscriber, and the server is a producer, of a set of data which are exchanged between them.

Publish

The producer (tipically a fastTrack service) notifies the availability of new data with a publish message. These messages are sent to all connected components (other Faststrack services and/or JFT applications) that expressed interest on these type of data.

Example:
a FastTrack order-manager publishes all records that describes new received or changed orders.

Only certain EntityClasses of a FastTrack server may be published and then subscribed. The documentation of each FastTrack server clearly says which EntityClasses can be published/subscribed.

Subscribe

A request for data by consumers is done by a subscribe message. This message typically says in which EntityClass the consumer is interested.

Example:
a customer subscribes to the orders handled by FastTrack.

Subscriptions in JFT/Api are modelled by Subscription. Among other things within subscriptions it's possible to have:

See Subscription Usage to see all specific subscription-related modalities.

Queries

In addition to the publish/subscribe mechanism a client has the possibility to obtain from the server a specific set of entities. This is done with the Query metaphor that mimics the homonymous facility of DBMS. Normally each type of query (identified by a specific number) has an argument that specify the particular request.

Example:
A client queries for all orders sent by a specific operator.

Only certain queries (each identified by a unique number) are permitted with a FastTrack server. The documentation of each FastTrack server clearly lists which queries (i.e. numbers) are permitted and with which arguments.

Transactions

The client may request a server to make some actions that may result in the update of one or more entities. The server evaluates the request and accepts or refuses it. Accepting the modification often implies application specific check actions by the server with the aim of controlling the access rights and action consistency while interpreting the semantics of the request arrived from the client. This is modeled in JFT/Api with the Transaction metaphor.

Example:
the client asks the server to issue an order on a specific product.

This operation may take a long period to be completed by the server and so the client have to monitor it until a good or bad (commited vs aborted) final result. This monitoring must be always done by the client, even after a client-restart on previous initiated (past) transactions. Only when the client see the final commited result it may assume that the transaction was succesfully.

See Transaction Usage to see all specific attributes of a transaction and how to monitor past transactions.

Connections and Contexts

All the above described capabilities are communicated between the client Java application (that use these JFT/Api) and the FastTrack server (a specific service of a FastTrack server) using a TCP/IP channel modelled with a Connection. The main attributes of such Connections are the TCP/IP host and port on which a named service reside.

Example:
an order-manager service may reside on port 1234 of host myFTserver.myDomain.com (or something like 194.91.195.33) and beeing named OrderManager

See Connection Usage to see all specific attributes that define a connection.

In addition the Context. metaphor has been introduced in order to group together connections (and corresponding subscriptions, transactions, queries, etc..) that refer to the same set of related FastTrack services.

JFT/Api Details

The JFT/Api library may be used starting with Sun JDK 1.7.

Asynchronous Communication Model

The implementation of JFT/API functionalities is based on an asynchronous communication model. A functionality (such as connection opening or a subscription for a set of data) is requested to the library via a method invocation. This request specifies (among other parameters) some notification methods, defined by the user in some Listener, which will be called by the library when data arrive or when other events occur.

See Listener interface for specific details.

LifeCycle

Many objects exposed by the JFT/Api library share the life cycle metaphor: once they are created, their life goes through well defined steps depending on their internal status.

See the LifeCycle interface and its related sub-interfaces to understand how this behaviour is controlled and regulated.

Data Model

The UML data models of the two packages of this JFT/Api library are available.

See it.list.jft Data Model and it.list.jft.event Data Model to familiarize with the hierarchy and relationship of the various interfaces.

Other Peculiarities

Some other details of the JFT/Api implementation are referenced here in order to use at the best the library:

JFT/Api Entry Point

Last but not least:
Where is the first initial entry point to use this library?
It's available in the singleton that implements the JFT interface. Using that singleton, referenced by the THIS constant, every programmer may starts to use the library accessing all its functionalities.