LightstreamerClient

A constant string representing the name of the library.

A constant string representing the version of the library.

Data object that contains the details needed to open a connection to a Lightstreamer Server. This instance is set up by the LightstreamerClient object at its own creation.
Properties of this object can be overwritten by values received from a Lightstreamer Server. Such changes will be notified through a ClientListener#onPropertyChange event on listeners of this instance.

Data object that contains options and policies for the connection to the server. This instance is set up by the LightstreamerClient object at its own creation.
Properties of this object can be overwritten by values received from a Lightstreamer Server. Such changes will be notified through a ClientListener#onPropertyChange event on listeners of this instance.

Static method that can be used to share cookies between connections to the Server (performed by this library) and connections to other sites that are performed by the application. With this method, cookies received by the application can be added (or replaced if already present) to the cookie set used by the library to access the Server. Obviously, only cookies whose domain is compatible with the Server domain will be used internally.

Lifecycle:This method can be called at any time; it will affect the internal cookie set immediately and the sending of cookies on future requests.

Static inquiry method that can be used to share cookies between connections to the Server (performed by this library) and connections to other sites that are performed by the application. With this method, cookies received from the Server can be extracted for sending through other connections, according with the URI to be accessed.

Static method that permits to configure the logging system used by the library. The logging system must respect the LoggerProvider interface. A custom class can be used to wrap any third-party JavaScript logging system.
A ready-made LoggerProvider implementation is available within the library in the form of the SimpleLoggerProvider class.
If no logging system is specified, all the generated log is discarded.
The following categories are available to be consumed:

• lightstreamer.stream:
  logs socket activity on Lightstreamer Server connections;
  at DEBUG level, read data is logged, write preparations are logged.
• lightstreamer.protocol:
  logs requests to Lightstreamer Server and Server answers;
  at DEBUG level, request details and events from the Server are logged.
• lightstreamer.session:
  logs Server Session lifecycle events;
  at INFO level, lifecycle events are logged;
  at DEBUG level, lifecycle event details are logged.
• lightstreamer.requests:
  logs submission of control requests to the Server;
  at WARN level, alert events from the Server are logged;
  at INFO level, submission of control requests is logged;
  at DEBUG level, requests batching and handling details are logged.
• lightstreamer.subscriptions:
  logs subscription requests and the related updates;
  at INFO level, subscriptions and unsubscriptions are logged;
  at DEBUG level, requests handling details are logged.
• lightstreamer.messages:
  logs sendMessage requests and the related updates;
  at INFO level, sendMessage operations are logged;
  at DEBUG level, request handling details are logged.
• lightstreamer.actions:
  logs settings / API calls.

Adds a listener that will receive events from the LightstreamerClient instance.
The same listener can be added to several different LightstreamerClient instances.

Lifecycle: a listener can be added at any time.

Operation method that requests to open a Session against the configured Lightstreamer Server.
When connect() is called, unless a single transport was forced through ConnectionOptions#setForcedTransport, the so called "Stream-Sense" mechanism is started: a connection via WebSocket is tried first; if unsuccessful, then http streaming is tried; but if the client does not receive any answer for some seconds from the streaming connection, then it will automatically open a polling connection.
A polling connection may also be opened if the environment is not suitable for a streaming connection.
Note that as "polling connection" we mean a loop of polling requests, each of which requires opening a synchronous (i.e. not streaming) connection to Lightstreamer Server.

Lifecycle: Note that the request to connect is accomplished by the client asynchronously; this means that an invocation to LightstreamerClient#getStatus right after connect() might not reflect the change yet. Also if a CPU consuming task is performed right after the call the connection will be delayed.
When the request to connect is finally being executed, if the current status of the client is not DISCONNECTED, then nothing will be done.

Operation method that requests to close the Session opened against the configured Lightstreamer Server (if any).
When disconnect() is called, the "Stream-Sense" mechanism is stopped.
Note that active Subscription instances, associated with this LightstreamerClient instance, are preserved to be re-subscribed to on future Sessions.

Lifecycle: Note that the request to disconnect is accomplished by the client asynchronously; this means that an invocation to LightstreamerClient#getStatus right after disconnect() might not reflect the change yet. Also if a CPU consuming task is performed right after the call the disconnection will be delayed.
When the request to disconnect is finally being executed, if the status of the client is "DISCONNECTED", then nothing will be done.

Returns an array containing the ClientListener instances that were added to this client.

Inquiry method that gets the current client status and transport (when applicable).

Inquiry method that returns an array containing all the Subscription instances that are currently "active" on this LightstreamerClient.
Internal second-level Subscription are not included.

Removes a listener from the LightstreamerClient instance so that it will not receive events anymore.

Lifecycle: a listener can be removed at any time.

Operation method that sends a message to the Server. The message is interpreted and handled by the Metadata Adapter associated to the current Session. This operation supports in-order guaranteed message delivery with automatic batching. In other words, messages are guaranteed to arrive exactly once and respecting the original order, whatever is the underlying transport (HTTP or WebSockets). Furthermore, high frequency messages are automatically batched, if necessary, to reduce network round trips.
Upon subsequent calls to the method, the sequential management of the involved messages is guaranteed. The ordering is determined by the order in which the calls to sendMessage are issued .
If a message, for any reason, doesn't reach the Server (this is possible with the HTTP transport), it will be resent; however, this may cause the subsequent messages to be delayed. For this reason, each message can specify a "delayTimeout", which is the longest time the message, after reaching the Server, can be kept waiting if one of more preceding messages haven't been received yet. If the "delayTimeout" expires, these preceding messages will be discarded; any discarded message will be notified to the listener through ClientMessageListener#onDiscarded. Note that, because of the parallel transport of the messages, if a zero or very low timeout is set for a message and the previous message was sent immediately before, it is possible that the latter gets discarded even if no communication issues occur. The Server may also enforce its own timeout on missing messages, to prevent keeping the subsequent messages for long time.
Sequence identifiers can also be associated with the messages. In this case, the sequential management is restricted to all subsets of messages with the same sequence identifier associated.
Notifications of the operation outcome can be received by supplying a suitable listener. The supplied listener is guaranteed to be eventually invoked; listeners associated with a sequence are guaranteed to be invoked sequentially.
The "UNORDERED_MESSAGES" sequence name has a special meaning. For such a sequence, immediate processing is guaranteed, while strict ordering and even sequentialization of the processing is not enforced. Likewise, strict ordering of the notifications is not enforced. However, messages that, for any reason, should fail to reach the Server whereas subsequent messages had succeeded, might still be discarded after a server-side timeout, in order to ensure that the listener eventually gets a notification.
Moreover, if "UNORDERED_MESSAGES" is used and no listener is supplied, a "fire and forget" scenario is assumed. In this case, no checks on missing, duplicated or overtaken messages are performed at all, so as to optimize the processing and allow the highest possible throughput.

Lifecycle: Since a message is handled by the Metadata Adapter associated to the current connection, a message can be sent only if a connection is currently active. If the special enqueueWhileDisconnected flag is specified it is possible to call the method at any time and the client will take care of sending the message as soon as a connection is available, otherwise, if the current status is "DISCONNECTED*", the message will be abandoned and the ClientMessageListener#onAbort event will be fired.
Note that, in any case, as soon as the status switches again to "DISCONNECTED*", any message still pending is aborted, including messages that were queued with the enqueueWhileDisconnected flag set to true.
Also note that forwarding of the message to the server is made asynchronously; this means that if a CPU consuming task is performed right after the call, the message will be delayed. Hence, if a message is sent while the connection is active, it could be aborted because of a subsequent disconnection. In the same way a message sent while the connection is not active might be sent because of a subsequent connection.

Operation method that adds a Subscription to the list of "active" Subscriptions. The Subscription cannot already be in the "active" state.
Active subscriptions are subscribed to through the server as soon as possible (i.e. as soon as there is a session available). Active Subscription are automatically persisted across different sessions as long as a related unsubscribe call is not issued.

Lifecycle: Subscriptions can be given to the LightstreamerClient at any time. Once done the Subscription immediately enters the "active" state.
Once "active", a Subscription instance cannot be provided again to a LightstreamerClient unless it is first removed from the "active" state through a call to LightstreamerClient#unsubscribe.
Also note that forwarding of the subscription to the server is made asynchronously; this means that if a CPU consuming task is performed right after the call the subscription will be delayed.
A successful subscription to the server will be notified through a SubscriptionListener#onSubscription event.

Operation method that removes a Subscription that is currently in the "active" state.
By bringing back a Subscription to the "inactive" state, the unsubscription from all its items is requested to Lightstreamer Server.

Lifecycle: Subscription can be unsubscribed from at any time. Once done the Subscription immediately exits the "active" state.
Note that forwarding of the unsubscription to the server is made asynchronously; this means that if a CPU consuming task is performed right after the call the unsubscription will be delayed.
The unsubscription will be notified through a SubscriptionListener#onUnsubscription event.