com.lightstreamer.ls_client
Class LSClient

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

public class LSClient
extends java.lang.Object

Incapsulates 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 bandwidth and frequency constraints for the current connection.
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 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.
void	sendMessage(java.lang.String message) Sends a message to Lightstreamer Server.
SubscribedTableKey[]	subscribeItems(ExtendedTableInfo items, ExtendedTableListener listener) Subscribes a set of items, which share the same schema and other subscription parameters.
SubscribedTableKey[]	subscribeItems(ExtendedTableInfo items, FastItemsListener listener) Same as the other overload, but notifies events to a different listener.
SubscribedTableKey	subscribeTable(ExtendedTableInfo table, ExtendedTableListener listener) Subscribes a table to the Server.
SubscribedTableKey	subscribeTable(SimpleTableInfo table, SimpleTableListener listener) Subscribes a table to 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 a table previously subscribed to the Server.
void	unsubscribeTables(SubscribedTableKey[] tableKeys) Unsubscribes 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

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.

changeConstraints

public void changeConstraints(ConnectionConstraints constraints)
                       throws PushConnException,
                              PushServerException

Requests new bandwidth and frequency constraints for 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 Provider. If the connection is not active, the call has no effect.

Parameters:

constraints - Collects bandwidth and frequency constraints for data flow from the Connection. It should not be null; to unset all constraints, use an empty structure, instead.

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.

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.

closeConnection

public void closeConnection()

Closes the connection to the Server, if one is open.

forceUnsubscribeTable

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

Tries to unsubscribe 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.

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.

openConnection

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

Opens a connection to the Server with the supplied parameters. If a connection is already open, it is closed first.

Parameters:

info - Contains the Server address and the connection parameters.

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 connection was refused after the checks in Lightstreamer Server Metadata Provider.

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.

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.

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 message was refused after the checks in Lightstreamer Server Metadata Provider.

subscribeItems

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

Subscribes a set of items, which share the same schema and other subscription parameters. All item and field names are provided. 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 has to be made through independent unsubscribeTable calls. A LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the request. If the request fails, no subscriptions have been performed.

Parameters:

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

listener - Receives notification of data updates and subscription termination. Subscribed items are identified to the listener by name. The same listener can be used across multiple subscribedItems calls, provided that the involved items are different. The method onUnsubscrAll will not be called on this listener.

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 items parameter. 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 Provider.

subscribeItems

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

Same as the other overload, but notifies events to a different listener. This saves some mapping work and demands it to the caller.

Parameters:

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

listener - Receives notification of data updates and subscription termination.

Returns:

An array of handles to the subscribed tables, one for each item.

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.

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

See Also:

subscribeItems(ExtendedTableInfo, ExtendedTableListener)

subscribeTable

public SubscribedTableKey subscribeTable(ExtendedTableInfo table,
                                         ExtendedTableListener listener)
                                  throws SubscrException,
                                         PushServerException,
                                         PushUserException,
                                         PushConnException

Subscribes a table to the Server. The table is specified by providing item and field names. A LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the request.

Parameters:

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

listener - Receives notification of data updates and subscription termination.

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 Provider.

subscribeTable

public SubscribedTableKey subscribeTable(SimpleTableInfo table,
                                         SimpleTableListener listener)
                                  throws SubscrException,
                                         PushServerException,
                                         PushUserException,
                                         PushConnException

Subscribes a table to the Server. The table is specified by group name and schema name.

Parameters:

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

listener - Receives notification of data updates and subscription termination.

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 Provider.

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.

unsubscribeTable

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

Unsubscribes a table previously subscribed to the Server. If the request fails, the table has been unsubscribed anyway.

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 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.

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.