it.list.jft
Interface JFT

All Superinterfaces:
LifeCycle

public interface JFT
extends LifeCycle

Main basic library interface to use within JFT/API.
Use this interface to initialize, configure and start to use the library.

A singleton of this interface is available in the THIS constant.
Using this constant it's possible to access any functionality exposed by this library.

To start use this library read the JFT/Api Introduction or watch the data models ( Package it.list.jft Data Model and Package it.list.jft.event Data Model) or just watch a few Java example programs.

JFT Exceptions

Almost all the methods of this library does not throw any exceptions of any sort: they instead return appropriate values to indicate any error condition found. There are very few exceptions to this policy: Even in this case the totality of thrown exceptions are unchecked (subclasses of RuntimeException), so they do not need to be catched or declared in the throws clause of method signature.

The JFT library does not throws any checked exception.

JFT Other Details

See JFT Implementation Threads and JFT Synchronization for details on implementation threads and synchronization.

JFT lifecycle

See Also:
JFT/Api Introduction, JFT Application Examples, LifeCycle, JFT Implementation Threads, JFT Synchronization

Field Summary
static int MODE_MULTI_THREAD
          Threading mode: multi-thread.
static int MODE_NO_ENTITY_CLONING
          Disable entity cloning in the library.
static int STATUS_CONFIGURING
          Lifecycle status: JFT initialized: ready to be configured and then started.
static int STATUS_RUNNING
          Lifecycle status: JFT started: ready to be used and then released.
static JFT THIS
          Reference to the JFT singleton.
static int TRACE_LEVEL_DEBUG
          Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.
static int TRACE_LEVEL_ERROR
          Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.
static int TRACE_LEVEL_FATAL
          Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.
static int TRACE_LEVEL_INFO
          Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.
static int TRACE_LEVEL_TEST
          Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.
static int TRACE_LEVEL_WARN
          Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.
 
Fields inherited from interface LifeCycle
RESULT_GENERIC_ERROR, RESULT_INVALID_STATUS, RESULT_OK, STATUS_INIT, STATUS_RELEASED
 
Method Summary
 EntityClass getEntityClass(int EntityClassID)
          Returns the registered EntityClass corresponding to the given EntityClassID.
 EntityClass getEntityClass(String EntityClassName)
          Returns the registered EntityClass corresponding to the given EntityClass Name.
 String getLibraryVersion()
          Returns the version of this library.
 int init(int mode)
          Initialize the library (with a specific threading model) and start the configuration phase.
 boolean isRegistered(int EntityClassID)
          Returns the indication that a given EntityClass (identified by an EntityClassID) has been registered.
 Context makeContext()
          Create and returns a new context.
 Mask makeEmptyMask(int entityClassID)
          Create and returns a new empty mask for a given Entity Class.
 TimeStamp makeTimeStamp(int dateTime, int prog)
          Create and returns a new TimeStamp.
 TransactionID makeTransactionID(int clientID, int clientServiceID, int businessServiceID, TimeStamp timeStamp)
          Create and returns a new TransactionID.
 int register(EntityClass entityClass)
          Register another EntityClass augmenting the number of the classes that can be manipulated by the library.
 void setExitOnListenerException(boolean enable)
          Enable/Disable the automatically termination of the JVM when an exception is thrown and not catch inside a Listener method.
 void setTrace(boolean enable)
          Enable/Disable the library trace.
 int setTraceLevel(int traceLevel)
          Set the mimun displayable level of the library trace.
 int setTraceMode(boolean autoFlush, File file)
          Set a file tracer.
 int setTraceMode(boolean autoFlush, PrintWriter writer)
          Set a printwriter (file, standard output/error, socketd, etc...) tracer.
 int setTraceMode(Tracer tracer)
          Set a customer tracer.
 int start()
          End the configuration phase and start to use the library.
 void trace(String module, int traceLevel, String message)
          Trace a given message.
 
Methods inherited from interface LifeCycle
enumChilds, getStatus, release
 

Field Detail

THIS

static final JFT THIS
Reference to the JFT singleton.


STATUS_CONFIGURING

static final int STATUS_CONFIGURING
Lifecycle status: JFT initialized: ready to be configured and then started.
This value may be returned by LifeCycle.getStatus().

Status Entry:
LifeCycle.STATUS_INITinit() ok → STATUS_CONFIGURING.
Status Activities:
the JFT libray may be configured via the register() method.
Status Exit:
STATUS_CONFIGURINGstart() ok → STATUS_RUNNING.

See Also:
JFT lifecycle, Constant Field Values

STATUS_RUNNING

static final int STATUS_RUNNING
Lifecycle status: JFT started: ready to be used and then released.
This value may be returned by LifeCycle.getStatus().

Status Entry:
STATUS_CONFIGURINGstart() ok → STATUS_RUNNING.
Status Activities:
the JFT libray may be used via the makeContext() or makeTimeStamp() or makeTransactionID() or makeEmptyMask() methods.
Status Exit:
STATUS_RUNNINGLifeCycle.release()LifeCycle.STATUS_RELEASED.

See Also:
JFT lifecycle, Constant Field Values

TRACE_LEVEL_DEBUG

static final int TRACE_LEVEL_DEBUG
Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.

This value may be used as argument of setTraceLevel(int).

See Also:
Constant Field Values

TRACE_LEVEL_TEST

static final int TRACE_LEVEL_TEST
Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.

This value may be used as argument of setTraceLevel(int).

See Also:
Constant Field Values

TRACE_LEVEL_INFO

static final int TRACE_LEVEL_INFO
Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.

This value may be used as argument of setTraceLevel(int).

See Also:
Constant Field Values

TRACE_LEVEL_WARN

static final int TRACE_LEVEL_WARN
Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.

This value may be used as argument of setTraceLevel(int).

See Also:
Constant Field Values

TRACE_LEVEL_ERROR

static final int TRACE_LEVEL_ERROR
Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.

This value may be used as argument of setTraceLevel(int).

See Also:
Constant Field Values

TRACE_LEVEL_FATAL

static final int TRACE_LEVEL_FATAL
Trace level: messages in bold are traced: DEBUG, TEST, INFO, WARN, ERROR, FATAL.

This value may be used as argument of setTraceLevel(int).

See Also:
Constant Field Values

MODE_MULTI_THREAD

static final int MODE_MULTI_THREAD
Threading mode: multi-thread.

Details on threads and synchronization are available in JFT Implementation Threads

This value may be used as argument of init(int).

See Also:
JFT Implementation Threads, Constant Field Values

MODE_NO_ENTITY_CLONING

static final int MODE_NO_ENTITY_CLONING
Disable entity cloning in the library.

Usually library functions return a safe copy of an entity in its method (especially in the callback events). For this reason users can without any problems safely modify them or store their reference if needed. In case of heavy subscription load, it is possibile to improve the library performance using this flag; in this case entities coming from callback events are valid inside the callback event context, whereas out of that context their value can be changed using library calls (however you can clone them in the event if you want to save their value)

This value may be used as argument of init(int).

See Also:
Constant Field Values
Method Detail

getLibraryVersion

String getLibraryVersion()
Returns the version of this library.

Returns:
the version of this library.
null is never returned.

setExitOnListenerException

void setExitOnListenerException(boolean enable)
Enable/Disable the automatically termination of the JVM when an exception is thrown and not catch inside a Listener method.

By default (if this method is never invoked) the automatically invocation of System.exit(0) is enabled.

Parameters:
enable - true or false to enable or disable this switch.

setTrace

void setTrace(boolean enable)
Enable/Disable the library trace.

By default (if this method is never invoked) the trace is disabled.

Parameters:
enable - true or false to enable or disable the trace.

setTraceLevel

int setTraceLevel(int traceLevel)
Set the mimun displayable level of the library trace.

Available trace level are: TRACE_LEVEL_DEBUG, TRACE_LEVEL_TEST, TRACE_LEVEL_INFO, TRACE_LEVEL_WARN, TRACE_LEVEL_ERROR and TRACE_LEVEL_FATAL.

By default (if this method is never invoked) the trace level is TRACE_LEVEL_WARN.

Parameters:
traceLevel - one of the TRACE_LEVEL_ constants.
Returns:

setTraceMode

int setTraceMode(Tracer tracer)
Set a customer tracer.

The current customer tracer (the last set by this method or none if this method was never invoked) is replaced with the given customer tracer.

A customer tracer is described by the Tracer interface in which the Tracer.onTrace() method is automatically invoked whenever the trace is enabled and the current trace-message has a level greater or equal than the current trace level.

Parameters:
tracer - customer tracer (it may be null)
Returns:

setTraceMode

int setTraceMode(boolean autoFlush,
                 File file)
Set a file tracer.

The current file tracer (the last set by this method or none if this method was never invoked) is replaced with the given file tracer.

If the trace is enabled a file tracer allow to trace in a file all trace-messages that have a level greater or equal than the current trace level.

Parameters:
autoFlush - true/false to enable/disable flush after every trace message.
file - file (it may be null) on which the trace messages are appended.
Returns:

setTraceMode

int setTraceMode(boolean autoFlush,
                 PrintWriter writer)
Set a printwriter (file, standard output/error, socketd, etc...) tracer.

The current printwriter tracer (the last set by this method or none if this method was never invoked) is replaced with the given printwriter tracer.

If the trace is enabled a printwriter tracer allow to trace in a PrintWriter all trace-messages that have a level greater or equal than the current trace level.

Parameters:
autoFlush - true/false to enable/disable flush after every trace message.
writer - PrintWriter (it may be null) on which the trace messages are appended.
Returns:

trace

void trace(String module,
           int traceLevel,
           String message)
Trace a given message.

The message will appear on the requested trace, depending on setting controlled by setTrace(boolean), setTraceLevel() and the required setTraceMode().

Parameters:
module - caller module name.
traceLevel - one of the TRACE_LEVEL_ constants.
message - not newline-terminated message to be traced.

init

int init(int mode)
Initialize the library (with a specific threading model) and start the configuration phase.

This method must be called only when current status is LifeCycle.STATUS_INIT, i.e. this method must be called before any other methods invocations (except for getLibraryVersion() and all trace methods that can be called at every time).

If this method invocation completed successfully, the current status changed to STATUS_CONFIGURING, otherwise it remains unchanged.

Parameters:
mode - threading mode (only MODE_MULTI_THREAD currently allowed).
Returns:

register

int register(EntityClass entityClass)
Register another EntityClass augmenting the number of the classes that can be manipulated by the library.

This method must be called only when current status is STATUS_CONFIGURING, i.e. in the configuration phase between the init(int) and start() invocations.

This method must be called for each market or service EntityClass which is referenced or used in the rest of the application. To facilitate this the FastTrack libraries are equipped with several market/service libraries each containing the Java EntityClasses of the market/service structures.

Parameters:
entityClass - EntityClass to be registered.
Returns:

isRegistered

boolean isRegistered(int EntityClassID)
Returns the indication that a given EntityClass (identified by an EntityClassID) has been registered.

Parameters:
EntityClassID - ID of the EntityClass to be checked.
Returns:
the indication that a given EntityClass (identified by an EntityClassID) has been registered.
false is returned when the current status is LifeCycle.STATUS_INIT.

getEntityClass

EntityClass getEntityClass(int EntityClassID)
Returns the registered EntityClass corresponding to the given EntityClassID.

Parameters:
EntityClassID - ID of the EntityClass to be retrieved.
Returns:
the registered EntityClass corresponding to the given EntityClassID.
null is returned when the current status is LifeCycle.STATUS_INIT,
or when the given EntityClassID is not registered.

getEntityClass

EntityClass getEntityClass(String EntityClassName)
Returns the registered EntityClass corresponding to the given EntityClass Name.

Parameters:
EntityClassName - The name of the EntityClass to be retrieved.
Returns:
the registered EntityClass corresponding to the given EntityClass Name.
null is returned when the current status is LifeCycle.STATUS_INIT,
or when the given EntityClassID is not registered.

start

int start()
End the configuration phase and start to use the library.

This method must be called only when current status is STATUS_CONFIGURING after all the register(it.list.jft.EntityClass) invocations.

If this method invocation completed successfully, the current status changed to STATUS_RUNNING. otherwise it remains unchanged.

Returns:

makeEmptyMask

Mask makeEmptyMask(int entityClassID)
Create and returns a new empty mask for a given Entity Class.

A mask may be used in subscriptions (SubscriptionParam.setMask()) or transactions (TransactionParam.setMask()).

This method must be called only when current status is STATUS_RUNNING, i.e. after the start() invocation.

Parameters:
entityClassID - Entity Class ID of the market class.
Returns:
the new empty mask.
null is returned when the current status is not STATUS_RUNNING,
or when the parameter entityClassID is wrong.

makeContext

Context makeContext()
Create and returns a new context.

A context is used to interact with one or more FastTrack servers.

This method must be called only when current status is STATUS_RUNNING, i.e. after the start() invocation.

Returns:
the new context.
null is returned when the current status is not STATUS_RUNNING.

makeTimeStamp

TimeStamp makeTimeStamp(int dateTime,
                        int prog)
Create and returns a new TimeStamp.

This convenience method may be used to re-create a timestamp previously saved as 2 ints returned by invocation of TimeStamp.getDateTime() and TimeStamp.getProg().

This method must be called only when current status is STATUS_RUNNING, i.e. after the start() invocation.

Parameters:
dateTime - saved value returned by a TimeStamp.getDateTime() invocation.
prog - saved value returned by a TimeStamp.getProg() invocation.
Returns:
the new TimeStamp.
null is returned when the current status is not STATUS_RUNNING,
or when some parameter is < 0.

makeTransactionID

TransactionID makeTransactionID(int clientID,
                                int clientServiceID,
                                int businessServiceID,
                                TimeStamp timeStamp)
Create and returns a new TransactionID.

This convenience method may be used to re-create a TransactionID previously saved as 5 ints returned by invocations of TransactionID.getClientID(), TransactionID.getClientServiceID(), TransactionID.getBusinessServiceID() and TransactionID.getTimeStamp().

This method must be called only when current status is STATUS_RUNNING, i.e. after the start() invocation.

Parameters:
clientID - saved value returned by a TransactionID.getClientID() invocation.
clientServiceID - saved value returned by a TransactionID.getClientServiceID() invocation.
businessServiceID - saved value returned by a TransactionID.getBusinessServiceID() invocation.
timeStamp - saved value returned by a TransactionID.getTimeStamp() invocation.
Returns:
the new TransactionID.
null is returned when the current status is not STATUS_RUNNING,
or when the timeStamp parameter is null.
See Also:
makeTimeStamp(int, int)


Submit a bug or feature to FT\API Programming Support<\font>