com.lightstreamer.ls_proxy
Interface UpdateListener

public interface UpdateListener

Receives Snapshots and Updates about Item values and subscription errors. All notifications are received while holding the lock to the overall subscription state, so that the notified informations are always up to date during the listener methods execution. For this same reason, however, the listener methods execution must be fast and must not be blocking. Moreover, as a general rule, reentrant calls to LSProxy during the listener methods execution are not allowed, but for subscription and unsubscription requests that don't involve the Item that is being notified (this simplifies implementation of a two level push mechanism, in which some Fields of one Item carry the names of related Items to subscribe).

Method Summary

void	onException(Item item, PushException e) Notifies an error in the subscription of an Item to Lightstreamer Server or in data reception from the Server.
void	onException(Item item, RequestException e) Notifies an error in a subscription or unsubscription request for an Item.
void	onLostUpdates(Item item, int lostUpdates) Notifies that some Updates for a RAW or COMMAND Item (or MERGE or DISTINCT Item with unfiltered dispatching requested) have been lost (for COMMAND mode with filtering allowed, this applies to ADD and DELETE events only).
void	onSnapshotEnd(Item item) Signals the completion of the Snapshot for an Item that has been previously subscribed with DISTINCT (provided that a snapshot length has been specified) or COMMAND (with filtering allowed) subscription mode.
void	update(UpdateEvent event) Brings Snapshots or notifies Updates for a previously subscribed Item.

Method Detail

update

void update(UpdateEvent event)

Brings Snapshots or notifies Updates for a previously subscribed Item. Upon reception of an Update from the Server, this method is called once for each listener that is involved in some of the current Item subscriptions. For MERGE, DISTINCT and COMMAND (with filtering allowed) subscription modes, it can also be called as a callback during subscribe request processing, to the supplied listener, in order to bring cached Snapshot informations.

Parameters:

event - carries values update information.

onSnapshotEnd

void onSnapshotEnd(Item item)

Signals the completion of the Snapshot for an Item that has been previously subscribed with DISTINCT (provided that a snapshot length has been specified) or COMMAND (with filtering allowed) subscription mode. Upon reception of the notification from the Server, this method is called once for each listener that is involved in some of the current Item subscriptions. Alternatively, it can be called as a callback during subscribe request processing, to the supplied listener, after the cached Snapshot informations have been sent.

Parameters:

item - the involved Item. The instance returned may not be the same instance that was used in the subscription, but it will be equal to it. The object is currently stored internally, thus it should not be modified.

onLostUpdates

void onLostUpdates(Item item,
                   int lostUpdates)

Notifies that some Updates for a RAW or COMMAND Item (or MERGE or DISTINCT Item with unfiltered dispatching requested) have been lost (for COMMAND mode with filtering allowed, this applies to ADD and DELETE events only). This may lead to an inconsistent state for these kind of Items, so the client may choose to restart the subscription. Also, notifies a restart in the Updates flow for a DISTINCT Item, such that some Updates may be missing or duplicated. This method is called once for each listener that is involved in some of the current Item subscriptions.

Parameters:

item - the involved Item. The instance returned may not be the same instance that was used in the subscription, but it will be equal to it. The object is currently stored internally, thus it should not be modified.

lostUpdates - the number of lost updates. A 0 value means that the real number could not be determined (and may as well be 0), as in the case of a forced reconnection to the Server. A -1 value extends the 0 case and means that the real number may be negative as well (possible for DISTINCT items, when a new snapshot may bring events that have been already received).

onException

void onException(Item item,
                 RequestException e)

Notifies an error in a subscription or unsubscription request for an Item. It is called as a callback during the request processing, to the supplied listener.

Parameters:

item - the involved Item. The instance returned may not be the same instance that was used in the subscription, but it will be equal to it. The object is currently stored internally, thus it should not be modified.

e - the specification of the error that has occurred.

onException

void onException(Item item,
                 PushException e)

Notifies an error in the subscription of an Item to Lightstreamer Server or in data reception from the Server. Both kinds of notifications are asynchronous with respect to the subscription requests. This method is called once for each listener that is involved in some of the current Item subscriptions.

Parameters:

item - the involved Item. The instance returned may not be the same instance that was used in the subscription, but it will be equal to it. The object is currently stored internally, thus it should not be modified.

e - the specification of the error that has occurred.