public interface Subscription
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 Entity
s 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.
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.
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 can be formulated in two manners:
SubscriptionParam.getQueryType()
to the
value SubscriptionParam.QUERY_TYPE_SET
and setting the parameter
SubscriptionParam.getEntityKey()
to an appropriate EntityKey (an
Entitykey where the
number of set segments is <=
number of segments of the given KeyID),
SubscriptionParam.getFilter()
to a
non-null
value representing an appropriate Filter in
Filter.STATUS_CREATED
status.
In the latter case the server will send only Entities that satisfy the given filter.
Both manners cannot coexist.
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 |
---|
static final int STATUS_STARTING
start()
server-answer. LifeCycle.getStatus()
.
STATUS_INIT
→ start()
ok →
STATUS_STARTING
.
onSubscriptionStart()
call.
STATUS_STARTING
→
onSubscriptionStart()
ok → STATUS_STARTED
. STATUS_STARTING
→
onSubscriptionStart()
bad → STATUS_STOPPED
.
static final int STATUS_STARTED
LifeCycle.getStatus()
.
STATUS_STARTING
→
onSubscriptionStart()
ok → STATUS_STARTED
.
SubscriptionListener.onSubscriptionNotify()
to get all interesting entities,
refreshEntity()
may be eventually used.
STATUS_STARTED
→ stop()
ok →
STATUS_STOPPING
.
static final int STATUS_STOPPING
stop()
server-answer. LifeCycle.getStatus()
.
STATUS_STARTED
→ stop()
ok →
STATUS_STOPPING
.
onSubscriptionStop()
call.
STATUS_STOPPING
→
onSubscriptionStop()
→ STATUS_STOPPED
.
static final int STATUS_STOPPED
LifeCycle.getStatus()
.
It's always a good practice to release a Subscription in this status.
STATUS_STOPPING
→
onSubscriptionStop()
→ STATUS_STOPPED
.
LifeCycle.release()
.
STATUS_STOPPED
→ LifeCycle.release()
→
STATUS_RELEASED
.
Method Detail |
---|
int start()
This method must be called only when
STATUS_INIT
,
Connection.STATUS_CONNECTED
.
If this method invocation completed successfully,
then
STATUS_STARTING
,
SunscriptionListener.onSubscriptionStart()
will be automatically called to handle it.
otherwise
SubscriptionListener.onSubscriptionStart()
will not be made,
In the latter case it is a good practice to release this Subscription.
RESULT_OK
if the operation completed
successfully,
RESULT_INVALID_STATUS
if the
current status is not
STATUS_INIT
,
RESULT_INVALID_CONNECTION_STATUS
if the associated Connection
current status is not
Connection.STATUS_CONNECTED
,
RESULT_GENERIC_ERROR
otherwise.
int refreshEntity(EntityKey entityKey)
This method is useful with masked subscriptions to retrieve all fields of an interesting entity.
This method must be called only when
STATUS_STARTED
,
Connection.STATUS_CONNECTED
.
If this method invocation completed successfully,
then
SubscriptionListener.onSubscriptionNotify()
will be automatically called to handle it and in this case all fields of
SubscriptionNotifyEvent.getEntity()
will be
available, even if this subscription is masked: the
SubscriptionNotifyEvent.isMasked()
method may be
used to discriminate between maske and not-masked entities.
otherwise
SubscriptionListener.onSubscriptionNotify()
will not be made.
In any case the current status remains unchanged.
entityKey
- the entitykey that identifies the requested entity.
RESULT_OK
if the operation completed
successfully,
RESULT_INVALID_STATUS
if
the current status is not
STATUS_STARTED
,
RESULT_INVALID_CONNECTION_STATUS
if the associated Connection
current status is not
Connection.STATUS_CONNECTED
,
RESULT_GENERIC_ERROR
otherwise (e.g. the entityKey
parameter is
null
or it refers an EntityClass different from
the
subscribed class).
int stop()
This method must be called only when
STATUS_STARTED
,
Connection.STATUS_CONNECTED
.
If this method invocation completed successfully,
then
STATUS_STOPPING
,
SubscriptionListener.onSubscriptionStop()
will be automatically called to handle it.
otherwise
SubscriptionListener.onSubscriptionStop()
will not be made,
It's not a bad practice to unconditionally release this Subscription immediately after this method invocation without handling the returned value.
RESULT_OK
if the operation completed
successfully,
RESULT_INVALID_STATUS
if the
current status is not STATUS_STARTED
,
RESULT_INVALID_CONNECTION_STATUS
if the associated Connection
current status is not
Connection.STATUS_CONNECTED
,
RESULT_GENERIC_ERROR
otherwise.