com.lightstreamer.ls_client
Class LSClient

java.lang.Object
  com.lightstreamer.ls_client.LSClient

public class LSClient
extends java.lang.Object

Encapsulates a single connector to Lightstreamer Server.

Constructor Summary

LSClient()
Empty constructor.

Method Summary

void	batchRequests(int batchSize) Signals that the next subscription and unsubscription requests can be accumulated and sent to Lightstreamer Server with a single connection.
void	changeConstraints(ConnectionConstraints constraints) Requests new constraints to be applied on the overall data flow from the current connection.
void	changeSubscription(SubscribedTableKey tableKey, SubscriptionConstraints constraints) Dynamically changes subscription parameters on a table previously subscribed to the Server.
void	changeSubscriptions(SubscribedTableKey[] tableKeys, SubscriptionConstraints constraints) Dynamically changes subscription parameters on a set of tables previously subscribed to the Server.
void	closeBatch() Closes a pending batch.
void	closeConnection() Closes the connection to the Server, if one is open.
void	forceUnsubscribeTable(SubscribedTableKey tableKey) Tries to unsubscribe from a table for which a previous unsubscribe has been called but an exception has been received.
void	openConnection(ConnectionInfo info, ConnectionListener listener) Opens a connection to the Server with the supplied parameters.
int	sendMessage(MessageInfo message, SendMessageListener listener) Send a message to Lightstreamer Server.
void	sendMessage(java.lang.String message) Sends a message to Lightstreamer Server.
SubscribedTableKey[]	subscribeItems(ExtendedTableInfo items, HandyTableListener listener) Subscribes to a set of items, which share the same schema and other subscription parameters.
SubscribedTableKey	subscribeTable(ExtendedTableInfo table, HandyTableListener listener, boolean commandLogic) Subscribes to a table through the Server.
SubscribedTableKey	subscribeTable(SimpleTableInfo table, HandyTableListener listener, boolean commandLogic) Subscribes to a table through the Server.
void	unbatchRequest() Signals that one of the requests previously scheduled for batching is no longer going to be issued.
void	unsubscribeTable(SubscribedTableKey tableKey) Unsubscribes from a table previously subscribed to the Server.
void	unsubscribeTables(SubscribedTableKey[] tableKeys) Unsubscribes from a set of tables previously subscribed to the Server.

Methods inherited from class java.lang.Object

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

Constructor Detail

LSClient

public LSClient()

Empty constructor.

Method Detail

openConnection

public void openConnection(ConnectionInfo info,
                           ConnectionListener listener)
                    throws PushConnException,
                           PushServerException,
                           PushUserException

Opens a connection to the Server with the supplied parameters. 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 a connection is already open, it is closed first.
If streaming (as opposed to polling) is specified in the connection parameters and the environment does not allow HTTP streaming, then the "Stream-sense" feature, if enabled, is activated; hence, if the streaming connection has not yielded any data after a few seconds, a polling connection is tried instead.
The method is blocking; it returns only after a connection to the Server has been established or the attempt has failed.

Parameters:

info - Contains the Server address and the connection parameters. A copy of the object is stored internally.

listener - Receives notification for connection events.

Throws:

PushConnException - Thrown in case of connection problems.

PushServerException - Thrown in case of errors in the supplied parameters or in Server answer. In normal operation, this should not happen.

PushUserException - Thrown in case the Server has refused the connection request because of the constraints imposed by the Metadata Adapter or by Server configuration.

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.

closeConnection

public void closeConnection()

Closes the connection to the Server, if one is open.
The method can be blocking; in case a connection attempt is currently in place, that attempt is completed first.

sendMessage

public void sendMessage(java.lang.String message)
                 throws PushConnException,
                        PushServerException,
                        PushUserException

Sends a message to Lightstreamer Server. The message is associated to the current session and is interpreted and managed by the Metadata Adapter related to the session.
The method is blocking; it returns only after receiving the Server answer upon the request submission.
Messages sent through this method are never batched, use sendMessage(MessageInfo, SendMessageListener) to send a batch of messages

Parameters:

message - Any text string, to be interpreted by the Metadata Adapter. It should not be null.

Throws:

PushConnException - Thrown in case of connection problems.

PushServerException - Thrown in case of errors in the supplied parameters or in Server answer. In normal conditions, this exception should never happen.

PushUserException - Thrown in case the Server has refused the message because of the constraints imposed by the Metadata Adapter or by Server configuration.

sendMessage

public int sendMessage(MessageInfo message,
                       SendMessageListener listener)
                throws PushConnException,
                       PushServerException,
                       PushUserException

Send a message to Lightstreamer Server. The message is associated to the current session and is interpreted and managed by the Metadata Adapter related to the session.
Upon subsequent calls to the method, the sequential management of the messages is guaranteed. However, any message that, for any reason, doesn't reach the Server can be discarded by the Server if this causes the subsequent message to be kept waiting for longer than a configurable timeout. A shorter timeout can be associated with the subsequent message itself. A sequence identifier must also be associated with the messages; the sequential management is restricted to all subsets of messages with the same sequence identifier associated. In case the sequential management is undesired the special UNORDERED_MESSAGES sequence identifier can be used.
Note that messages are sent to the Server asynchronously with respect to the Client thread and that the real outcome of the request should be obtained by listening for calls on the associated SendMessageListener instance. Unless the return value is 0, one of those events will be eventually sent. Calls associated with the same sequence are guaranteed to be issued in sequence.

Parameters:

message - An instance containing the message string to be interpreted by the Metadata Adapter, the sequence this message has to be associated with and a delay timeout to be waited by the server for missing previous messages to be received before being declared lost.

listener - A listener instance to receive a call representing the outcome of the message request.

Returns:

0 if no session is open; in the other case a number representing the progressive number of the message within its sequence is returned (starting from 1). Note that each time a new session is established the progressive number is reset. Note that if no session is open, no attempt of sending the message will be performed; however, as messages outcomes are received from the Server asynchronously, if a session is open but ends before the message outcome is received, than a call to SendMessageListener.onAbort(com.lightstreamer.ls_client.MessageInfo, int, java.lang.Exception) will be made.

Throws:

PushConnException - Thrown in case of connection problems.

PushServerException - Thrown in case of errors in the supplied parameters or in Server answer. In normal conditions, this exception should never happen.

PushUserException - Thrown in case the Server has refused the message because of the constraints imposed by the Metadata Adapter or by Server configuration.

changeConstraints

public void changeConstraints(ConnectionConstraints constraints)
                       throws PushConnException,
                              PushServerException

Requests new constraints to be applied on the overall data flow from the current connection. The new limits override the limits requested with the connection operation or the last call to this method (a constraint not set means an unlimited constraint and may override a previous limiting constraint). They can only be used in order to restrict the constraints set by Lightstreamer Server Metadata Adapter. If the connection is not active, the call has no effect.
The method is blocking; it returns only after receiving the Server answer upon the request submission.

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.

Throws:

PushConnException - Thrown in case of connection problems.

PushServerException - Thrown in case of errors in the supplied parameters or in Server answer. In normal conditions, this exception should never happen.

subscribeTable

public SubscribedTableKey subscribeTable(SimpleTableInfo table,
                                         HandyTableListener listener,
                                         boolean commandLogic)
                                  throws SubscrException,
                                         PushServerException,
                                         PushUserException,
                                         PushConnException

Subscribes to a table through the Server.
The table is specified by group name and schema name. Specific item and field names have to be determined by the Metadata Adapter.
A fully-featured listener interface is provided. However, specific items and fields are identified to the listener only by positional information, as item and field names are not known.
A distinct listener must be used for any distinct call.
The method is blocking; it returns only after receiving the Server answer upon the request submission. In case a batch is open, this will happen only upon the execution of the batch.

Parameters:

table - Contains the specification and request parameters of the table to subscribe to.

listener - Receives notification of data updates and subscription termination.

commandLogic - if true, enables the management of item values in "COMMAND logic", as specified in HandyTableListener. This requires that the items are subscribed to in COMMAND mode or behave equivalently. This also requires that the special "key" and "command" fields are the first and second field in the schema, respectively.

Returns:

A handle to the subscribed table, to be used for unsubscription.

Throws:

SubscrException - Thrown if the connection is closed.

PushConnException - Thrown in case of connection problems.

PushServerException - Thrown in case of errors in the supplied parameters or in Server answer. In normal conditions, this exception should never happen.

PushUserException - Thrown in case the subscription was refused after the checks in Lightstreamer Server Metadata Adapter.

subscribeTable

public SubscribedTableKey subscribeTable(ExtendedTableInfo table,
                                         HandyTableListener listener,
                                         boolean commandLogic)
                                  throws SubscrException,
                                         PushServerException,
                                         PushUserException,
                                         PushConnException

Subscribes to a table through the Server.
The table is specified by providing item and field names. This requires that a LiteralBasedProvider or equivalent Metadata Adapter is configured on the Server, in order to understand the request.
A fully-featured listener interface is provided.
A distinct listener must be used for any distinct call.
The method is blocking; it returns only after receiving the Server answer upon the request submission. In case a batch is open, this will happen only upon the execution of the batch.

Parameters:

table - Contains the specification and request parameters of the table to subscribe to. A copy of the object is stored internally.

listener - Receives notification of data updates and subscription termination.

commandLogic - if true, enables the notification of item updates with "COMMAND logic", as specified in HandyTableListener. This requires that the items are subscribed to in COMMAND mode or behave equivalently; in particular, that the special "key" and "command" fields are included in the schema.

Returns:

A handle to the subscribed table, to be used for unsubscription.

Throws:

SubscrException - Thrown if the connection is closed.

PushConnException - Thrown in case of connection problems.

PushServerException - Thrown in case of errors in the supplied parameters or in Server answer. In normal conditions, this exception should never happen.

PushUserException - Thrown in case the subscription was refused after the checks in Lightstreamer Server Metadata Adapter.

subscribeItems

public SubscribedTableKey[] subscribeItems(ExtendedTableInfo items,
                                           HandyTableListener listener)
                                    throws SubscrException,
                                           PushServerException,
                                           PushUserException,
                                           PushConnException

Subscribes to a set of items, which share the same schema and other subscription parameters. All item and field names are provided. This requires that a LiteralBasedProvider or equivalent Metadata Adapter is configured on the Server, in order to understand the request.
The items are not collected as one table, but they are subscribed each in a different table. However, the items are subscribed alltogether with a single connection to the Server. The items unsubscription can be made either in a single operation (through unsubscribeTables) or through independent unsubscribe operations.
A fully-featured listener interface is provided.
Subscribed items are identified to the listener both by position and by by name. If name information is used, then the same listener instance can be used across multiple calls to this method, as long as the involved items are always different. The method onUnsubscrAll will not be called on the listener.
If the request fails, no subscriptions have been performed.
The method is blocking; it returns only after receiving the Server answer upon the request submission. In case a batch is open, this will happen only upon the execution of the batch.

Parameters:

items - Contains the specification and request parameters of the items to subscribe to. The structure is the same as that used in subscribeTable, but the items will not be subscribed to as a table. A copy of the object is stored internally.

listener - Receives notification of data updates and subscription termination.

Returns:

An array of handles to the subscribed tables, one for each item. The order of the handles reflects the order of the items in the item set description. The handles are needed for unsubscription.

Throws:

SubscrException - Thrown if the connection is closed.

PushConnException - Thrown in case of connection problems.

PushServerException - Thrown in case of errors in the supplied parameters or in Server answer. In this case, some zombie subscriptions may remain in the Server. In normal conditions, this exception should never happen.

PushUserException - Thrown in case the subscription was refused after the checks in Lightstreamer Server Metadata Adapter.

changeSubscription

public void changeSubscription(SubscribedTableKey tableKey,
                               SubscriptionConstraints constraints)
                        throws SubscrException,
                               PushServerException,
                               PushConnException

Dynamically changes subscription parameters on a table previously subscribed to the Server. The new parameters override the ones requested with the subscription operation or the last call to this method. No notification to the table listener is available for this operation.
The server may refuse to apply certain constraints under specific conditions, for example when changing the max frequency of an unfiltered subscription. In these cases a PushServerException will be raised.
The method is blocking; it returns only after receiving the Server answer upon the request submission. This kind of request is not included in a batch.

Parameters:

tableKey - Handle to a table as returned by a subscribe* call.

constraints - Collects available constraints. It should not be null.

Throws:

SubscrException - Thrown if the supplied table is not currently subscribed. This occurs also if the table has already been unsubscribed or the connection has already been closed; this may not be a problem from the client's point of view.

PushConnException - Thrown in case of connection problems. In this case, the request may or may not have been fulfilled by the Server.

PushServerException - Thrown in case the Server refuses the request.

changeSubscriptions

public void changeSubscriptions(SubscribedTableKey[] tableKeys,
                                SubscriptionConstraints constraints)
                         throws SubscrException,
                                PushServerException,
                                PushConnException

Dynamically changes subscription parameters on a set of tables previously subscribed to the Server. The request is sent to the Server in a single connection. For each table, the new parameters override the ones requested with the subscription operation or the last call to this method. No notification to the table listeners is available for this operation.
The server may refuse to apply certain constraints under specific conditions, for example when changing the max frequency of an unfiltered subscription. In these cases a PushServerException will be raised.
The method is blocking; it returns only after receiving the Server answer upon the request submission. This kind of request is not included in a batch.

Parameters:

tableKey - Array of handles to tables as returned by one or more subscribe* calls.

constraints - Collects available constraints. It should not be null.

Throws:

SubscrException - Thrown if the connection has already been closed; this may not be a problem from the client's point of view.

PushConnException - Thrown in case of connection problems. In this case, the request may or may not have been fulfilled by the Server.

PushServerException - Thrown in case the Server refuses the request. Note that if changing the max frequency and any of the involved tables has been subscribed to as unfiltered, the whole request will be refused. Including any tables already unsubscribed from the Server may also cause this exception; in this case, the request may have been partially fulfilled.

unsubscribeTable

public void unsubscribeTable(SubscribedTableKey tableKey)
                      throws SubscrException,
                             PushServerException,
                             PushConnException

Unsubscribes from a table previously subscribed to the Server. If the request fails, the table has been unsubscribed anyway.
The method is blocking; it returns only after receiving the Server answer upon the request submission. In case a batch is open, this will happen only upon the execution of the batch.

Parameters:

tableKey - Handle to a table as returned by a subscribe* call.

Throws:

SubscrException - Thrown if the supplied table is not currently subscribed. This occurs also if the table has already been unsubscribed or the connection has already been closed; this may not be a problem from the client's point of view.

PushConnException - Thrown in case of connection problems. In this case, a zombie subscription will probably remain in the Server.

PushServerException - Thrown in case of errors in the supplied parameters or in Server answer. In this case, a zombie subscription may remain in the Server. In normal conditions, this exception should never happen.

unsubscribeTables

public void unsubscribeTables(SubscribedTableKey[] tableKeys)
                       throws SubscrException,
                              PushServerException,
                              PushConnException

Unsubscribes from a set of tables previously subscribed to the Server. The unsubscription requests are sent to the Server in a single connection. If some of the supplied tables are not currently subscribed or have already been unsubscribed, no notification is sent. If the request fails, all the tables have been unsubscribed anyway.
The method is blocking; it returns only after receiving the Server answer upon the request submission. In case a batch is open, this will happen only upon the execution of the batch.

Parameters:

tableKeys - Array of handles to tables as returned by one or more subscribe* calls.

Throws:

SubscrException - Thrown if the connection has already been closed; this may not be a problem from the client's point of view.

PushConnException - Thrown in case of connection problems. In this case, zombie subscriptions will probably remain in the Server.

PushServerException - Thrown in case of errors in the supplied parameters or in Server answer. In this case, some zombie subscriptions may remain in the Server. In normal conditions, this exception should never happen.

forceUnsubscribeTable

public void forceUnsubscribeTable(SubscribedTableKey tableKey)
                           throws SubscrException,
                                  PushServerException,
                                  PushConnException

Tries to unsubscribe from a table for which a previous unsubscribe has been called but an exception has been received. In this case, a zombie subscription may have remained in the Server. This call does not affect client behavior, but the client can try it in order to force a new server side unsubscription attempt. If the call succeeds, a zombie subscription has been indeed eliminated.
The method is blocking; it returns only after receiving the Server answer upon the request submission. This kind of request is not included in a batch.

Parameters:

tableKey - Handle to a table as returned by a subscribe* call.

Throws:

SubscrException - Thrown if the connection has already been closed or the supplied table is currently subscribed. In this case, there wasn't a zombie subscription in the Server for the supplied table.

PushConnException - Thrown in case of connection problems. In this case, nothing has changed in the Server.

PushServerException - Thrown in case of errors in the supplied parameters or in Server answer. In this case there wasn't a zombie subscription in the Server for the supplied table.

batchRequests

public void batchRequests(int batchSize)
                   throws SubscrException

Signals that the next subscription and unsubscription requests can be accumulated and sent to Lightstreamer Server with a single connection. All the subsequent requests will be stopped until the declared number of requests has been accumulated. For this reason, subscription requests can be included in a batch only if they belong to separate threads; sequential requests cannot be processed in the same batch. Any subscribe* and unsubscribe* can be batched. Calls to forceUnsubscribeTable are not batched. Batches are cumulative; if a call to batchRequests is performed while a previous batch is still accumulating, the previous batch is extended. At connection closure, a pending batch is always aborted.

Parameters:

batchSize - number of incoming subscription and unsubscription requests that can be batched. A zero value means an unlimited number of requests (the batch must be closed by calling closeBatch).

Throws:

SubscrException - Thrown if the connection is currently closed.

unbatchRequest

public void unbatchRequest()

Signals that one of the requests previously scheduled for batching is no longer going to be issued. Should be called after batchRequests, if something happened that prevented one of the scheduled requests from being issued. In such a case, not calling unbatchRequest would keep the batch blocked until a further request is performed. Calling unbatchRequest is always safe.

closeBatch

public void closeBatch()

Closes a pending batch. If a batch size was declared and the current batch is still accumulating requests, the current set of requests is sent the same to Lightstreamer Server, while further requests will not be batched. The client can call this in order to overcome a possible error in sending a batch of requests, since, if less than the declared requests were performed, all requests would be blocked until the declared number of requests has been reached. Calling closeBatch is always safe; however, since batched requests are blocked until completion of the batch, there is no guarantee that all previously performed requests have already been added to the batch at the time closeBatch is issued.
The method is not blocking; all batched requests are performed asynchronously. Note that the threads that have issued the batched subscription requests are currently waiting for them to be completed.