it.list.jft
Interface Subscription

All Superinterfaces:
ActivityLifeCycle, CommunicationLifeCycle, LifeCycle

public interface Subscription
extends ActivityLifeCycle

An arrangement with the server for receiving a continuing set of interesting entities of the same EntityClass.

Opening a subscription on a EntityClass of a Server entails both the initial acquisition of the Entitys of the EntityClass of the Server and the subsequent notification of any additions or cancellations executed by the Server on that EntityClass.

Special subscription modalities enable the acquisition of just a subset of the Entities of a EntityClass of the Server: see the section below.

Subscription Usage

A subscription is described by:
In brief:
Subscriptions are created by Context.makeSubscription() in which the subscription parameters are described by SubscriptionParam and the event listeners are described by SubscriptionListener.

Once created a subscription must be started with the server, used (eventually via refreshEntity) and then stopped from the server.

Subscription Lifecycle

Incremental Subscriptions

This section outlines how to manage incremental subscriptions, in which the server is only required to send updated contents of an EntityClass, rather than sending all its records.

A client application can consequently keep a local data base aligned with the market server's, or more generally avoid processing data twice, by minimizing, at the same time, the volume of data to transfer and the needed time.

In particular, the subscription allows you to specify the pair of values (EntityClass Version, EntityClass TimeStamp) i.e., respectively, the last version index of the EntityClass and the time-stamp of the last Entity (record) received of that class during the previous subscription.

Thus, if the version of the EntityClass maintained in the server coincides with the one supplied, only those entities with a time stamp that is later than the one supplied will be sent.

On the other hand if the version of the class is earlier than the server's current one, then SubscriptionStartEvent.isEntityClassReset() will be true . This indicates a general invalidation of any entities from that EntityClass that have been archived until that moment. In the latter case it will not be possible to proceed to an incremental acquisition, but all the entities in the EntityClass will have to be received.

In order to be able to make this data available, the client application has to maintain for each EntityCass the following information:

The current time stamp can be maintained by updating local TimeStamp data whenever ACTION_ENTITY_ADD, ACTION_ENTITY_RWT or ACTION_ENTITY_DEL operations are made, on the basis of the SubscriptionNotifyEvent.getTimeStamp() returned value.

The current version can be maintained by acquiring the value of the version at the opening of the subscription by SubscriptionStartEvent.getEntityClassVersionOnServer(), and updating it on every version variation of the server class, this basically means at each notification of an ACTION_ENTITY_KIL operation, by setting it to the SubscriptionNotifyEvent.getTimeStamp().getDateTime() value.

Remarks

ACTION_ENTITY_DEL and ACTION_ENTITY_KIL operations with SubscriptionNotifyEvent.getKeyID() > 0, should be intended as notifications of (logical or physical} cancellation of an individual entity at a server level. In this case the Entity returned by SubscriptionNotifyEvent.getEntity() is generally undefined on any fields apart from those associated with SubscriptionNotifyEvent.getKeyID().

Operations of ACTION_ENTITY_KIL with SubscriptionNotifyEvent.getKeyID() <= 0 should be intended as the physical cancellation of every entity in the specified EntityClass that has been acquired beforehand. In this case: SubscriptionNotifyEvent.getEntity() == null.

Partial Subscriptions

This section outlines how to manage partial subscriptions, in which the server is requested to send only those entities in a EntityClass that satisfy certain constraints.

Partial subscriptions can be formulated in two manners:

In the first case the server will send only Entities whose complete EntityKey match the given partial EntityKey.

In the latter case the server will send only Entities that satisfy the given filter.

Both manners cannot coexist.

See Also:
Context.makeSubscription(), SubscriptionParam, SubscriptionListener

Field Summary
static int STATUS_STARTED
          Lifecycle status: Subscription started and ready to be used.
static int STATUS_STARTING
          Lifecycle status: Subscription waiting the start() server-answer.
static int STATUS_STOPPED
          Lifecycle status: Subscription stopped with the server and ready to be released.
static int STATUS_STOPPING
          Lifecycle status: Subscription waiting the stop() server-answer.
 
Fields inherited from interface ActivityLifeCycle
RESULT_INVALID_CONNECTION_STATUS
 
Fields inherited from interface LifeCycle
RESULT_GENERIC_ERROR, RESULT_INVALID_STATUS, RESULT_OK, STATUS_INIT, STATUS_RELEASED
 
Method Summary
 int refreshEntity(EntityKey entityKey)
          Request the server to re-publish a single complete (not masked) Entity.
 int start()
          Try to start this subscription with the server.
 int stop()
          Try to stop this subscription with the server.
 
Methods inherited from interface ActivityLifeCycle
getConnection
 
Methods inherited from interface CommunicationLifeCycle
getContext, getListener, getParam
 
Methods inherited from interface LifeCycle
enumChilds, getStatus, release
 

Field Detail

STATUS_STARTING

static final int STATUS_STARTING
Lifecycle status: Subscription waiting the start() server-answer.
This value may be returned by LifeCycle.getStatus().

Status Entry:
STATUS_INITstart() ok → STATUS_STARTING.
Status Activities:
none: waiting an automatic onSubscriptionStart() call.
Status Exit:
STATUS_STARTINGonSubscriptionStart() ok → STATUS_STARTED.
STATUS_STARTINGonSubscriptionStart() bad → STATUS_STOPPED.

See Also:
Subscription lifecycle, Constant Field Values

STATUS_STARTED

static final int STATUS_STARTED
Lifecycle status: Subscription started and ready to be used.
This value may be returned by LifeCycle.getStatus().

Status Entry:
STATUS_STARTINGonSubscriptionStart() ok → STATUS_STARTED.
Status Activities:
Status Exit:
STATUS_STARTEDstop() ok → STATUS_STOPPING.

See Also:
Subscription lifecycle, Constant Field Values

STATUS_STOPPING

static final int STATUS_STOPPING
Lifecycle status: Subscription waiting the stop() server-answer.
This value may be returned by LifeCycle.getStatus().

Status Entry:
STATUS_STARTEDstop() ok → STATUS_STOPPING.
Status Activities:
none: waiting an automatic onSubscriptionStop() call.
Status Exit:
STATUS_STOPPINGonSubscriptionStop()STATUS_STOPPED.

See Also:
Subscription lifecycle, Constant Field Values

STATUS_STOPPED

static final int STATUS_STOPPED
Lifecycle status: Subscription stopped with the server and ready to be released.
This value may be returned by LifeCycle.getStatus().

It's always a good practice to release a Subscription in this status.

Status Entry:
STATUS_STOPPINGonSubscriptionStop()STATUS_STOPPED.
Status Activities:
LifeCycle.release().
Status Exit:
STATUS_STOPPEDLifeCycle.release()STATUS_RELEASED.

See Also:
Subscription lifecycle, Constant Field Values
Method Detail

start

int start()
Try to start this subscription with the server.

This method must be called only when

If this method invocation completed successfully,
then

otherwise

In the latter case it is a good practice to release this Subscription.

Returns:

refreshEntity

int refreshEntity(EntityKey entityKey)
Request the server to re-publish a single complete (not masked) Entity.

This method is useful with masked subscriptions to retrieve all fields of an interesting entity.

This method must be called only when

If this method invocation completed successfully,
then

otherwise

In any case the current status remains unchanged.

Parameters:
entityKey - the entitykey that identifies the requested entity.
Returns:

stop

int stop()
Try to stop this subscription with the server.

This method must be called only when

If this method invocation completed successfully,
then

otherwise

It's not a bad practice to unconditionally release this Subscription immediately after this method invocation without handling the returned value.

Returns:


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