Class: LightstreamerClient

LightstreamerClient

Facade class for the management of the communication to Lightstreamer Server. Used to provide configuration settings, event handlers, operations for the control of the connection lifecycle, Subscription handling and to send messages.
It can be configured to share its connection with other LightstreamerClient instances (even if on different html pages) through LightstreamerClient#enableSharing calls.

new LightstreamerClient(serverAddressopt, adapterSetopt)

Creates an object to be configured to connect to a Lightstreamer server and to handle all the communications with it. It is possible to instantiate as many LightstreamerClient as needed. Each LightstreamerClient is the entry point to connect to a Lightstreamer server, subscribe to as many items as needed and to send messages. Multiple LightstreamerClient instances may share the same connection if configured to behave that way through LightstreamerClient#enableSharing.
Parameters:
Name Type Argument Description
serverAddress String <optional>
the address of the Lightstreamer Server to which this LightstreamerClient will connect to. It is possible not to specify it at all or to specify it later. See ConnectionDetails#setServerAddress for details.
adapterSet String <optional>
the name of the Adapter Set mounted on Lightstreamer Server to be used to handle all requests in the Session associated with this LightstreamerClient. It is possible not to specify it at all or to specify it later. See ConnectionDetails#setAdapterSet for details.
Throws:
if a not valid address is passed. See ConnectionDetails#setServerAddress for details.
Type
IllegalArgumentException

Members

(static) LIB_NAME :String

A constant string representing the name of the library.
Type:
  • String

(static) LIB_VERSION :String

A constant string representing the version of the library.
Type:
  • String

connectionDetails :ConnectionDetails

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.
In case of a shared connection the involved LightstreamerClient instances will keep this data object synchronized so that a change on a property of an object of one of the instances will be reflected on all the others. Any change will be notified through a ClientListener#onPropertyChange event on listeners of this instance.
Type:
See:

connectionOptions :ConnectionOptions

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.
In case of a shared connection the involved LightstreamerClient instances will keep this data object synchronized so that a change on a property of an object of one of the instances will be reflected on all the others. Any change will be notified through a ClientListener#onPropertyChange event on listeners of this instance.
Type:
See:

Method Summary

setLoggerProvider
Static method that permits to configure the logging system used by the library.
addListener
Adds a listener that will receive events from the LightstreamerClient instance.
connect
Operation method that requests to open a Session against the configured Lightstreamer Server.
disconnect
Operation method that requests to close the Session opened against the configured Lightstreamer Server (if any).
enableSharing
Configures the client to share its connection and/or attach to a shared connection.
getListeners
Returns an array containing the ClientListener instances that were added to this client.
getStatus
Inquiry method that gets the current client status and transport (when applicable).
getSubscriptions
Inquiry method that returns an array containing all the Subscription instances that are currently "active" on this LightstreamerClient.
isMaster
Inquiry method that checks if the LightstreamerClient has its own connection or if it is using a connection shared by another LightstreamerClient.
removeListener
Removes a listener from the LightstreamerClient instance so that it will not receive events anymore.
sendMessage
Operation method that sends a message to the Server.
Operation method that adds a Subscription to the list of "active" Subscriptions.
unsubscribe
Operation method that removes a Subscription that is currently in the "active" state.

Method Detail

(static) setLoggerProvider(provider)

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.
  • lightstreamer.grids:
    logs grid-related code.
  • lightstreamer.flash:
    logs FlashBridge-related code.
  • lightstreamer.sharing:
    logs creation / sharing / election of the Master and Slave LightstreamerClient;
    at WARN level, problems getting a connection up and ready are logged;
    at INFO level, found/lost events are logged;
    at DEBUG level, connection management details and regular checks on the current connection are logged.
Parameters:
Name Type Description
provider LoggerProvider A LoggerProvider instance that will be used to generate log messages by the library classes.

addListener(listener)

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.

Parameters:
Name Type Description
listener ClientListener An object that will receive the events as shown in the ClientListener interface.
Note that the given instance does not have to implement all of the methods of the ClientListener interface. In fact it may also implement none of the interface methods and still be considered a valid listener. In the latter case it will obviously receive no events.

connect()

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: 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.
When connect() is used to activate the Lightstreamer Session on page start up, it is suggested to make this call as the latest action of the scripts in the page. Otherwise, if the stream connection is opened but third-party scripts are consuming most of the CPU for page initialization (initial rendering, etc.), the parsing of the streaming response could be delayed to the point that the Client switches to polling mode. This is usually not the case nowadays but may still happen if the client is used on old machines.
In case of a shared connection the connect call will apply to such shared connection regardless of which LightstreamerClient is calling it.
If LightstreamerClient#enableSharing has not been called before the first call to connect, then a default call will be performed with the following parameter:
new ConnectionSharing("randomstring","IGNORE", "CREATE", true, null);
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.

See:
Throws:

disconnect()

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.
In case of a shared connection, the disconnect() call will apply to such shared connection regardless of which LightstreamerClient is calling it.

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.

enableSharing(sharing)

Configures the client to share its connection and/or attach to a shared connection. Different windows trying to share the connection to Lightstreamer Server must share the exact same origin. Depending on the browser in use, connection sharing might not work. Specify null to prevent any kind of sharing (this is also the default). In case a connection is not currently required (i.e. the client is in DISCONNECTED status) specifying null will also have the effect to dismiss resources currently held by the client: failing to do that when a LightstreamerClient instance is not needed anymore might prevent the VM from collecting all the allocated resources. Note that in this case required resources will be prepared again once a call to LightstreamerClient#connect is performed.

Default value: by default no sharing is configured.

Lifecycle: this method can be called at any time.
Note that if multiple calls to this method are performed, the last one will override the previous ones. Also if a call to enableSharing is made on a Master client, the current connection (if any) will be dropped and the remaining clients will enter the election algorithm.

Parameters:
Name Type Description
sharing ConnectionSharing The sharing parameters or null to prevent any sharing

getListeners() → {Array}

Returns an array containing the ClientListener instances that were added to this client.
Returns:
an array containing the listeners that were added to this client. Listeners added multiple times are included multiple times in the array.
Type
Array

getStatus() → {String}

Inquiry method that gets the current client status and transport (when applicable).
See:
Returns:
The current client status. It can be one of the following values:
  • "CONNECTING" the client is waiting for a Server's response in order to establish a connection;
  • "CONNECTED:STREAM-SENSING" the client has received a preliminary response from the server and is currently verifying if a streaming connection is possible;
  • "CONNECTED:WS-STREAMING" a streaming connection over WebSocket is active;
  • "CONNECTED:HTTP-STREAMING" a streaming connection over HTTP is active;
  • "CONNECTED:WS-POLLING" a polling connection over WebSocket is in progress;
  • "CONNECTED:HTTP-POLLING" a polling connection over HTTP is in progress;
  • "STALLED" the Server has not been sending data on an active streaming connection for longer than a configured time;
  • "DISCONNECTED:WILL-RETRY" no connection is currently active but one will be opened after a timeout.
  • "DISCONNECTED:TRYING-RECOVERY" no connection is currently active, but one will be opened as soon as possible, as an attempt to recover the current session after a connection issue;
  • "DISCONNECTED" no connection is currently active;
Type
String

getSubscriptions() → {Array}

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.
Returns:
An array, containing all the Subscription currently "active" on this LightstreamerClient.
The array can be empty.
Type
Array

isMaster() → {boolean}

Inquiry method that checks if the LightstreamerClient has its own connection or if it is using a connection shared by another LightstreamerClient. This LightstreamerClient is not a Master if:
See:
Returns:
Whenever the LightstreamerClient owning this instance is a Master or not.
Type
boolean

removeListener(listener)

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

Lifecycle: a listener can be removed at any time.

Parameters:
Name Type Description
listener ClientListener The listener to be removed.

sendMessage(msg, sequenceopt, delayTimeoutopt, listeneropt, enqueueWhileDisconnectedopt)

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 ; in case of calls issued from different LightstreamerClient instances on different html pages sharing the same connection, the relative order is determined by the client owning the shared connection. Anyway two messages sent through the same LightstreamerClient instance will never surpass each other .
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. Note that, because of the asynchronous transport of the requests, if a zero or very low timeout is set for a message, it is not guaranteed that the previous message can be processed, even if no communication issues occur.
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.
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.

Parameters:
Name Type Argument Default Description
msg String a text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection.
sequence String <optional>
"UNORDERED_MESSAGES" an alphanumeric identifier, used to identify a subset of messages to be managed in sequence; underscore characters are also allowed. If the "UNORDERED_MESSAGES" identifier is supplied, the message will be processed in the special way described above.
The parameter is optional; if not supplied, "UNORDERED_MESSAGES" is used as the sequence name.
delayTimeout Number <optional>
a timeout, expressed in milliseconds. If higher than the Server default timeout, the latter will be used instead.
The parameter is optional; if not supplied, the Server default timeout will be applied.
This timeout is ignored for the special "UNORDERED_MESSAGES" sequence.
listener ClientMessageListener <optional>
an object suitable for receiving notifications about the processing outcome.
The parameter is optional; if not supplied, no notification will be available.
enqueueWhileDisconnected boolean <optional>
false if this flag is set to true, and the client is in a disconnected status when the provided message is handled, then the message is not aborted right away but is queued waiting for a new session. Note that the message can still be aborted later when a new session is established.

subscribe(subscription)

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.

Parameters:
Name Type Description
subscription Subscription A Subscription object, carrying all the information needed to process its pushed values.
See:
Throws:

unsubscribe(subscription)

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.

Parameters:
Name Type Description
subscription Subscription An "active" Subscription object that was activated by this LightstreamerClient instance.
See:
Throws:
if the given Subscription is not currently "active".
Type
IllegalStateException