com.lightstreamer.interfaces.data
Interface DataProvider

All Known Subinterfaces:

SmartDataProvider

public interface DataProvider

Provides an interface to be implemented by a Data Adapter in order to attach a Data Provider to Lightstreamer Kernel. The configuration of an Adapter instance requires the following items:

• a unique identification for the instance;
• the Adapter class name;
• optional configuration parameters.

This is accomplished through the "adapters.xml" configuration files.
A single instance of each configured Adapter is created by Lightstreamer Kernel at startup. For this purpose, any Data Adapter must provide a void constructor. After creation, the init method is called, providing the Data Adapter with the configuration information; then, the Kernel sets itself as the Data Adapter listener, by calling the setListener method.
Data Providers are used by Lightstreamer Kernel to obtain all data to be pushed to the Clients. Any Item requested by a Client must refer to one supplied by the configured Data Adapters.
A Data Provider supplies data in a publish/subscribe way. Lightstreamer Kernel asks for data by calling the subscribe and unsubscribe methods for various Items and the Data Adapter sends ItemEvents to its listener in an asynchronous way.
A Data Adapter can also support Snapshot management. Upon subscription to an item, the current state of the Item data can be sent to the Kernel before the updates. This allows the Kernel to maintain the Item state, by integrating the new ItemEvents into the state (in a way that depends on the Item type) and to make this state available to the Clients.
Note that the interaction between the Kernel and the Data Adapter and the interaction between the Kernel and any Client are independent activities. As a consequence, the very first ItemEvents sent by the Data Adapter to the Kernel for an Item just subscribed to might be processed before the Kernel starts feeding any client, even the client that caused the subscription to the Item to be invoked; then, such events would not be forwarded to any client. If it is desirable that a client receives all the ItemEvents that have been produced for an Item by the Data Adapter since subscription time, then the support for the Item Snapshot can be leveraged.
Lightstreamer Kernel ensures that calls to subscribe and unsubscribe for the same Item will be interleaved, without redundant calls; whenever subscribe throws an exception, the corresponding unsubscribe call is not issued.

Field Summary

static java.lang.String	ADD_COMMAND Constant that can be used as the "ADD" value for the "command" fields of Items to be processed in COMMAND mode.
static java.lang.String	COMMAND_FIELD Constant that can be used as field name for the "command" field in Items to be processed in COMMAND mode.
static java.lang.String	DELETE_COMMAND Constant that can be used as the "DELETE" value for the "command" fields of Items to be processed in COMMAND mode.
static java.lang.String	KEY_FIELD Constant that can be used as field name for the "key" field in Items to be processed in COMMAND mode.
static java.lang.String	UPDATE_COMMAND Constant that can be used as the "UPDATE" value for the "command" fields of Items to be processed in COMMAND mode.

Method Summary

void	init(java.util.Map params, java.io.File configDir) Called by Lightstreamer Kernel to provide initialization information to the Data Adapter.
boolean	isSnapshotAvailable(java.lang.String itemName) Called by Lightstreamer Kernel to know whether the Data Adapter, after a subscription for an Item, will send some Snapshot ItemEvents before sending the updates.
void	setListener(ItemEventListener listener) Called by Lightstreamer Kernel to provide a listener to receive the ItemEvents carrying data and asynchronous error notifications.
void	subscribe(java.lang.String itemName, boolean needsIterator) Called by Lightstreamer Kernel to request data for an Item.
void	unsubscribe(java.lang.String itemName) Called by Lightstreamer Kernel to end a previous request of data for an Item.

Field Detail

KEY_FIELD

static final java.lang.String KEY_FIELD

Constant that can be used as field name for the "key" field in Items to be processed in COMMAND mode.

See Also:

Constant Field Values

COMMAND_FIELD

static final java.lang.String COMMAND_FIELD

Constant that can be used as field name for the "command" field in Items to be processed in COMMAND mode.

See Also:

Constant Field Values

ADD_COMMAND

static final java.lang.String ADD_COMMAND

Constant that can be used as the "ADD" value for the "command" fields of Items to be processed in COMMAND mode.

See Also:

Constant Field Values

UPDATE_COMMAND

static final java.lang.String UPDATE_COMMAND

Constant that can be used as the "UPDATE" value for the "command" fields of Items to be processed in COMMAND mode.

See Also:

Constant Field Values

DELETE_COMMAND

static final java.lang.String DELETE_COMMAND

Constant that can be used as the "DELETE" value for the "command" fields of Items to be processed in COMMAND mode.

See Also:

Constant Field Values

Method Detail

init

void init(java.util.Map params,
          java.io.File configDir)
          throws DataProviderException

Called by Lightstreamer Kernel to provide initialization information to the Data Adapter. The call must not be blocking; any polling cycle or similar must be started in a different thread. If an exception occurs in this method, Lightstreamer Kernel can't complete the startup and must exit.

Parameters:

params - A Map-type value object that contains name-value pairs corresponding to the "param" elements supplied in the Data Adapter configuration file under the "data_provider" element. Both names and values are represented as String objects.

configDir - The path of the directory on the local disk where the Data Adapter configuration file resides.

Throws:

DataProviderException - if an error occurs that prevents the correct behavior of the Data Adapter. This causes the Server not to complete the startup and to exit.

setListener

void setListener(ItemEventListener listener)

Called by Lightstreamer Kernel to provide a listener to receive the ItemEvents carrying data and asynchronous error notifications. The listener is set before any subscribe is called and is never changed.

Parameters:

listener - a listener.

subscribe

void subscribe(java.lang.String itemName,
               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 of the Item value. Before sending the updates, the Data Adapter may optionally send one or more ItemEvents to supply the current Snapshot.
The general rule to be followed for event dispatching is:

      if isSnapshotAvailable(itemName) == true
           SNAP* [EOS] UPD*
      else
           UPD*

where:

• SNAP represents an update call with the isSnapshot flag set to true
• EOS represents an endOfSnapshot call
• UPD represents an update call with the isSnapshot flag set to false

The composition of the snapshot depends on the Mode in which the item is to be processed. In particular, for MERGE mode, the snapshot consists of one event and the first part of the rule becomes:

           [SNAP] [EOS] UPD*

where a missing snapshot is considered as an empty snapshot.
If an item can be requested only in RAW mode, then isSnapshotAvailable should always return false; anyway, when an item is requested in RAW mode, any snapshot is discarded.
Note that calling endOfSnapshot is not mandatory; however, not calling it in DISTINCT or COMMAND mode may cause the server to keep the snapshot and forward it to the clients only after the first non-shapshot event has been received. The same happens for MERGE mode if neither the snapshot nor the endOfSnapshot call are supplied.
Unexpected snapshot events are converted to non-snapshot events (but for RAW mode, where they are ignored); unexpected endOfSnapshot calls are ignored.

The method should be nonblocking. If slow subscription activation operations are needed, they should be performed asynchronously, after subscription acceptance. Implementing subscribe asynchronously should always be possible, because:

• returning an error code is not requested;
• sending a snapshot before returning is not needed: the snapshot can always be sent asynchronously;
• throwing a SubscriptionException just prevents "unsubscribe" from being called for the item, but, with respect to the data flow, it is equivalent to returning without exception and just supplying no data for the item (in this case, if a snapshot is required, then sending an empty snapshot is still possible and may be even better from the client point of view).
• throwing a FailureException can be replaced by invoking "failure" asynchronously on the listener.

Note, however, that, when implementing subscribe asynchronously, some effort should be spent in checking that the processing of subsequent subscribe-unsubscribe-subscribe-unsubscribe requests for the same item don't overlap.

Parameters:

itemName - Name of an 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 Adapter. This causes the whole Server to exit, so that an external recovery mechanism may come into action.

See Also:

ItemEventListener, ItemEvent

unsubscribe

void unsubscribe(java.lang.String itemName)
                 throws SubscriptionException,
                        FailureException

Called by Lightstreamer Kernel to end a previous request of data for an Item. After the call has returned, no more ItemEvents for the item should be sent to the listener until requested by a new subscription for the same item.
The method should be nonblocking. If slow housekeeping operations are needed, they should be performed asynchronously. Note, however, that, when implementing unsubscribe asynchronously, some effort should be spent in checking that the processing of subsequent subscribe-unsubscribe-subscribe-unsubscribe requests for the same item don't overlap.

Parameters:

itemName - Name of an Item.

Throws:

SubscriptionException - if the request cannot be satisfied. This does not prevent Lightstreamer Kernel from calling "subscribe" again for the same item, if needed.

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.

isSnapshotAvailable

boolean isSnapshotAvailable(java.lang.String itemName)
                            throws SubscriptionException

Called by Lightstreamer Kernel to know whether the Data Adapter, after a subscription for an Item, will send some Snapshot ItemEvents before sending the updates. An item Snapshot can be represented by zero, one or more ItemEvents, also depending on the item type. The decision whether to supply or not to supply Snapshot information is entirely up to the Data Adapter.
The method should be nonblocking. The availability of the snapshot for an item should be a known architectural property. When the snapshot, though expected, cannot be obtained at subscription time, then it can only be considered as empty.

Parameters:

itemName - Name of an Item.

Returns:

true if Snapshot information will be sent for this Item before before the updates.

Throws:

SubscriptionException - if the Data Adapter is unable to answer to the request. This causes the subscription to fail and the proper "subscribe" call not to be issued..A failed subscription is not notified to the clients; it just causes the clients not to receive data.