Package 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 may be natural, depending on the Data Adapter implementation. In fact, when an update is available, a reference to the related subscription information may be already in the context; or an internal lookup for the related subscription information by item name is already needed. In these cases, a second global lookup in the Kernel can be saved. As a consequence, different smartUpdate/smartEndOfSnapshot calls issued on different threads can be fully decoupled, 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:

  • Method Details

    • subscribe

      void subscribe(@Nonnull String itemName, @Nonnull 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 perform as fast as possible. See the notes for DataProvider.subscribe(String, boolean).
      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 DataProvider.unsubscribe(String) call will not be issued.
      FailureException - if the method execution has caused a severe problem that can compromise future operation of the Data Adapter. This causes the whole Server to exit, so that an external recovery mechanism may come into action.
      See Also:

    • subscribe

      void subscribe(@Nonnull 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: