com.lightstreamer.interfaces.data
Interface SmartDataProvider

All Superinterfaces:

DataProvider

public interface SmartDataProvider
extends DataProvider

Provides an extended interface to be implemented by a Data Adapter in order to attach a Data Provider to Lightstreamer Kernel. Data Adapters that implement this interface can relieve the Kernel from finding item data by item name at every update call.
By implementing this interface, a Data Adapter will receive item subscription requests by an extended subscribe call, which supplies handles to item data in the Kernel. These handles can be used, instead of item names, to identify items in update calls, through the various smartUpdate and the smartEndOfSnapshot methods.
Using this extended interface is natural in many situations, where an internal lookup for item data by item name is already performed in the Data Adapter. In these cases, a second lookup in the Kernel can be saved. This also saves a global synchronization, allowing different update calls issued in different threads to be managed concurrently, provided that calls for the same item are issued in the same thread.
Lightstreamer Kernel always uses different handles across subsequent subscriptions of the same item. This gives an additional benefit: if spurious trailing updates are sent, through smartUpdate, after an item has been unsubscribed and then immediately subscribed again, these trailing updates cannot conflict with the new updates sent against the new subscription and are just ignored by Lightstreamer Kernel.

See Also:

DataProvider, ItemEventListener

Field Summary

Fields inherited from interface com.lightstreamer.interfaces.data.DataProvider

ADD_COMMAND, COMMAND_FIELD, DELETE_COMMAND, KEY_FIELD, UPDATE_COMMAND

Method Summary

void	subscribe(java.lang.String itemName, boolean needsIterator) Inherited by the base interface DataProvider but never called in this case, because the extended version will always be called in its place.
void	subscribe(java.lang.String itemName, java.lang.Object itemHandle, boolean needsIterator) Called by Lightstreamer Kernel to request data for an Item.

Methods inherited from interface com.lightstreamer.interfaces.data.DataProvider

init, isSnapshotAvailable, setListener, unsubscribe

Method Detail

subscribe

void subscribe(java.lang.String itemName,
               java.lang.Object itemHandle,
               boolean needsIterator)
               throws SubscriptionException,
                      FailureException

Called by Lightstreamer Kernel to request data for an Item. If the request succeeds, the Data Adapter can start sending an ItemEvent to the listener for any update in the Item value. Before sending the updates, the Data Adapter may optionally send one or more ItemEvents to supply the current Snapshot.
Both item name and item handle can be used to identify the item, but using the latter is far more efficient.
The method should be nonblocking. See the notes for the subscribe method in the DataProvider interface.

Parameters:

itemName - Name of an Item.

itemHandle - Object to be used to identify the item in update calls. Lightstreamer Kernel always uses different handles across subsequent subscriptions of the same item.

needsIterator - Signals that the getNames method will be called on the ItemEvents received for this Item. If this flag is set to false, the ItemEvent objects sent for this Item need not implement the method.

Throws:

SubscriptionException - if the request cannot be satisfied. A failed subscription is not notified to the clients; it just causes the clients not to receive data. Upon a failed subscription, the related "unsubscribe" call will not be issued.

FailureException - if the method execution has caused a severe problem that can compromise future operation of the Data Provider. This causes the whole Server to exit, so that an external recovery mechanism may come into action.

See Also:

ItemEventListener, ItemEvent, DataProvider.subscribe(java.lang.String, boolean)

subscribe

void subscribe(java.lang.String itemName,
               boolean needsIterator)
               throws SubscriptionException,
                      FailureException

Inherited by the base interface DataProvider but never called in this case, because the extended version will always be called in its place. The method can be safely left blank or return an exception.

Specified by:

subscribe in interface DataProvider

Parameters:

itemName - Not to be used in this context.

needsIterator - Not to be used in this context.

Throws:

SubscriptionException - Can always be thrown in this context.

FailureException - Not to be thrown in this context.

See Also:

ItemEventListener, ItemEvent