com.lightstreamer.ls_proxy
Class LSProxy

java.lang.Object
  com.lightstreamer.ls_proxy.LSProxy

public final class LSProxy
extends java.lang.Object

Offers an extended interface to Lightstreamer Server, which leans upon the LSClient interface layer and hides Server interactions, in order to offer a more abstract view of the subscription to pushing informations.
It manages the subscriptions and Update receptions for a number of Items, by sharing subscriptions among similar requests in order to minimize subscriptions to Lightstreamer Server. It works both in connected and in disconnected state; the push activity can be stopped and restarted at any moment without affecting the subscriptions state. Also, connection problems can be managed by retrying or by switching to disconnected state without affecting the subscriptions state.
All methods feature a nonblocking behavior, except for startPushConnection, which, however, can be immediately interrupted by a subsequent call to stopPushConnection.
Here are some more details about this interface layer:

• The access to the Library features is similar to that in LSClient. A single instance of the class LSProxy has to be created and used. The subscription and unsubscription operations are similar to the LSClient case, but no "table" abstraction is supplied.
• A LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription requests. This interface cannot be used to access to the Server through a Metadata Adapter which doesn't meet this requirement.
• A transparent management of unexpected connection close is provided, that keeps all subscriptions open and re-performs all requests to Lightstreamer Server after the next reconnection. For items subscribed in MERGE or DISTINCT mode with filtered dispatching allowed, in case of reconnection, the updates flow can continue seamlessly, with just some possible temporary data loss (which is allowed, however). For items subscribed in RAW or unfiltered MERGE, DISTINCT or COMMAND mode, in case of reconnection, the possible data loss will be notified to the proper listener. For items subscribed in COMMAND mode with filtering allowed, in case of reconnection, a notification of possible data loss will be sent to the proper listener, but the full Snapshot will also be sent, so that it could be managed by the Library User to resume the Item state. This support is to be extended furtherly. This management of subscriptions also applies to explicit connection closes. As a matter of fact, subscription state and connection state are totally independent from one another: all subscriptions remain active across subsequent connections and disconnections to Lightstreamer Server, until the related unsubscriptions are issued. A function, clearConnection, that closes the connection and deactivates all subscriptions, is also provided.
• In case of an unexpected connection close, the automatic reconnection policy can be configured. A connection listener is notified of all related events.
• The hiding of Server access in order to minimize Server requests is effective by default. A single request to the Server is kept active in order to manage all subscriptions related to the same Item. This behavior can be controlled, though, by forcing Item objects (used to represent Items) to be different, despite the fact that they represent the same Item.
• An interface to make possible "transactions of subscriptions" is provided, Requests in the same transaction are collected and also, as much as possible, batched in the same connection to Lightstreamer Server. The user of the Library, in case of a burst of subscription and unsubscription requests, can cooperate in saving Server accesses by notifying to the Library the starting and the completion of the burst. In this way, at most one request to the Server will be made for each item involved in the burst and most of the request could be sent in a single Connection.
• The same listener can be used to subscribe sets of independent Items. Such Items need not be unsubscribed alltogether. It is also possible to use a different listener for each Item; in this case, each Item must be subscribed through a different subscribe call. This should not compromise efficiency, as long as transactions are used.
• A simple listener for the connection state can be used. It will receive samplings for connection openness and current bandwidth usage.

See Also:

LSClient

Constructor Summary

LSProxy(ProxyInfo info, PushErrorListener errorListener, PushStatusListener statusListener)
Creates an LSProxy, by specifying some connection policy preferences and a listener to receive asynchronous errors notifications.

Method Summary

void	clearConnection() Requests the stopping of push activity and the cancellation of all current subscriptions.
void	endTran() Completes a subscription requests transaction.
ConnectionConstraints	getConnectionConstraints() Returns the constraints currently requested on the overall data flow from the Connection.
boolean	isPushing() Returns the current connection state.
void	setConnectionConstraints(ConnectionConstraints constraints) Changes the constraints to be applied on the overall data flow from the Connection.
void	startPushConnection(ConnectionInfo info) Requests the starting of push activity.
void	startTran() Starts a subscription requests transaction.
void	stopPushConnection() Requests the stopping of push activity.
void	subscribeBandwidth(BandwidthListener bwListener) Adds a listener to samplings about connection activity.
void	subscribeItem(UpdateListener itemListener, Item item, java.lang.String[] schema) Requests the subscription of some Fields for an Item and supplies a listener to receive value Updates and an initial Snapshot, if it is available.
void	subscribeItems(UpdateListener itemListener, Item[] items, java.lang.String[] schema) Requests the subscription of some Fields for a set of Items and supplies a listener to receive information for all the Items.
void	unsubscribeBandwidth(BandwidthListener bwListener) Removes a listener to samplings about connection activity.
void	unsubscribeItem(UpdateListener itemListener, Item item, java.lang.String[] schema) Removes a subscription previously requested.
void	unsubscribeItems(UpdateListener itemListener, Item[] items, java.lang.String[] schema) Removes a subscription previously requested for a set of items.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LSProxy

public LSProxy(ProxyInfo info,
               PushErrorListener errorListener,
               PushStatusListener statusListener)

Creates an LSProxy, by specifying some connection policy preferences and a listener to receive asynchronous errors notifications.

Parameters:

info - supplies connection policy preferences. It must not be null. A copy of the object is stored internally.

errorListener - receives asynchronous errors notifications. It must not be null.

statusListener - receives asynchronous notifications on the connection state. It must not be null.

Method Detail

startPushConnection

public void startPushConnection(ConnectionInfo info)
                         throws PushException

Requests the starting of push activity. Attempts a new connection to Lightstreamer Server and requests to the Server all currently subscribed Items. More precisely, the Server will initiate a push session for this client, which will be accessed through a streaming connection or through a train of polling connections, depending on the configuration parameters. If push is already active at the time of this call, it may still close and reopen the connection in order to guarantee that the supplied connection preferences are satisfied.
This call blocks until the connection has completed; until that time, the connection state doesn't change. A blocked call can be interrupted by calling, in another thread, stopPushConnection or startPushConnection with a different info.

Parameters:

info - supplies connection informations and preferences. It must not be null. A copy of the object is stored internally.

Throws:

PushException - thrown if the connection attempt has failed.

Edition Note:

Connections from the Java Client Library are not supported by the Server, if it runs in Allegro edition.

Edition Note:

Connections from the Java Client Library are not supported by the Server, if it runs in Moderato edition.

stopPushConnection

public void stopPushConnection()

Requests the stopping of push activity. Tries to interrupt a connection to Lightstreamer Server. This call is always successful; if an error occurred while disconnecting from the Server, some resources may be wasted.

clearConnection

public void clearConnection()

Requests the stopping of push activity and the cancellation of all current subscriptions.

See Also:

stopPushConnection()

isPushing

public boolean isPushing()

Returns the current connection state.

Returns:

true if push is currently active.

setConnectionConstraints

public void setConnectionConstraints(ConnectionConstraints constraints)

Changes the constraints to be applied on the overall data flow from the Connection. The constraints set can only restrict the constraints posed by Lightstreamer Server Metadata Adapter. A constraint not set means an unlimited constraint and may override a previous limiting constraint.

Parameters:

constraints - collects available constraints. It should not be null; to unset all constraints, use an empty structure, instead. A copy of the object is stored internally.

getConnectionConstraints

public ConnectionConstraints getConnectionConstraints()

Returns the constraints currently requested on the overall data flow from the Connection. The real constraints applied by Lightstreamer Server can be stronger.

Returns:

a ConnectionConstraints object, which collects available constraints. A copy of the internally stored object is returned. Returns null if the connection has never been initialized.

subscribeBandwidth

public void subscribeBandwidth(BandwidthListener bwListener)

Adds a listener to samplings about connection activity. When the connection is not active, the listener may not be called.

Parameters:

bwListener - receives samplings about connection activity. It must not be null.

unsubscribeBandwidth

public void unsubscribeBandwidth(BandwidthListener bwListener)

Removes a listener to samplings about connection activity.

Parameters:

bwListener - samplings listener to remove. It must not be null.

startTran

public void startTran()

Starts a subscription requests transaction. All subsequent subscribe and unsubscribe calls will be accepted, but any request to Lightstreamer Server will be postponed until the next endTran() call. In this way, similar requests can share the same subscribe and unsubscribe requests in the transaction.

endTran

public void endTran()

Completes a subscription requests transaction. All requests to Lightstreamer Server needed to fulfill subscription requests in the transaction are performed here. Transaction requests are cumulative, so if n startTran() calls are pending, the requests to Lightstreamer Server are performed only after n endTran() calls.

subscribeItem

public void subscribeItem(UpdateListener itemListener,
                          Item item,
                          java.lang.String[] schema)

Requests the subscription of some Fields for an Item and supplies a listener to receive value Updates and an initial Snapshot, if it is available. The sent Updates will carry information about all Fields currently subscribed to Lightstreamer Server, which may be more than requested. The Snapshot and the very first Updates may also report less Fields than requested, but only in case of MERGE Items. The same listener can be used across multiple subscribe calls and can discriminate Updates based on their related Item. This Item object may be a different but equal instance with respect to the object supplied to the subscribe call. Errors occurred in the subscription phase are notified to the listener. Such notifications may occur as callbacks, before the completion of the call. A listener can be used to subscribe the same Item more than once and with different schemas; in this case, it would receive each Update and error notification for that Item exactly once, whether it pertains to all subscriptions for the Item or just to the current subscription attempt (as is the case for Snapshots or subscription sharing errors).

Parameters:

itemListener - receives value Updates and error notifications about the Item. It must not be null.

item - Specification of an Item to subscribe, together with its subscription preferences. It must not be null. The object may be stored internally, thus it should not be modified anymore. Different Item objects can refer to the same information Item and can specify either the same or different subscription preferences.

schema - Array with the names of the Fields to be subscribed. The order of the names is unimportant. None of these can be null.

unsubscribeItem

public void unsubscribeItem(UpdateListener itemListener,
                            Item item,
                            java.lang.String[] schema)

Removes a subscription previously requested. The supplied item, schema and listener must be equal to that used in a previous successful subscribe call. Errors occurred in the subscription phase are notified to the listener. Such notifications may occur as callbacks, before the completion of the call.

Parameters:

itemListener - listener for the subscription to remove. It must not be null.

item - Item whose subscription is to be removed. It must not be null.

schema - Array with the names of the Fields whose subscription is to be removed. The order of the names is unimportant. None of these can be null.

subscribeItems

public void subscribeItems(UpdateListener itemListener,
                           Item[] items,
                           java.lang.String[] schema)

Requests the subscription of some Fields for a set of Items and supplies a listener to receive information for all the Items.

Parameters:

itemListener - receives value Updates and error notifications about the Item. It must not be null.

items - Array with the specifications of the Items to subscribe, together with their subscription preferences. None of these can be null. The Item objects may be stored internally, thus they should not be modified anymore.

schema - Array with the names of the Fields to be subscribed. The order of the names is unimportant. None of these can be null.

See Also:

subscribeItem(com.lightstreamer.ls_proxy.UpdateListener, com.lightstreamer.ls_proxy.Item, java.lang.String[])

unsubscribeItems

public void unsubscribeItems(UpdateListener itemListener,
                             Item[] items,
                             java.lang.String[] schema)

Removes a subscription previously requested for a set of items. The supplied items, schema and listener must be equal to that used in one or more previous successful subscribe calls.

Parameters:

itemListener - listener for all the subscriptions to remove. It must not be null.

items - Array with the Items whose subscription is to be removed. None of these can be null.

schema - Array with the names of the Fields whose subscription is to be removed. The order of the names is unimportant. None of these can be null.

See Also:

unsubscribeItem(com.lightstreamer.ls_proxy.UpdateListener, com.lightstreamer.ls_proxy.Item, java.lang.String[])