Namespace com.lightstreamer.client

Classes

ConnectionDetails

Used by LightstreamerClient to provide a basic connection properties data object. Data object that contains the configuration settings needed to connect to a Lightstreamer Server.
An instance of this class is attached to every LightstreamerClient as connectionDetails

ConnectionOptions

Used by LightstreamerClient to provide an extra connection properties data object.

Data object that contains the policy settings used to connect to a Lightstreamer Server.
An instance of this class is attached to every LightstreamerClient as connectionOptions

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.
An instance of LightstreamerClient handles the communication with Lightstreamer Server on a specified endpoint. Hence, it hosts one "Session"; or, more precisely, a sequence of Sessions, since any Session may fail and be recovered, or it can be interrupted on purpose. So, normally, a single instance of LightstreamerClient is needed.
However, multiple instances of LightstreamerClient can be used, toward the same or multiple endpoints.

You can listen to the events generated by a session by registering an event listener, such as ClientListener or SubscriptionListener. These listeners allow you to handle various events, such as session creation, connection status, subscription updates, and server messages. However, you should be aware that the event notifications are dispatched by a single thread, the so-called event thread. This means that if the operations of a listener are slow or blocking, they will delay the processing of the other listeners and affect the performance of your application. Therefore, you should delegate any slow or blocking operations to a dedicated thread, and keep the listener methods as fast and simple as possible. Note that even if you create multiple instances of LightstreamerClient, they will all use a single event thread, that is shared among them.

Proxy

Simple class representing a Proxy configuration.

An instance of this class can be used through Proxy to instruct a LightstreamerClient to connect to the Lightstreamer Server passing through a proxy.

Subscription

Class representing a Subscription to be submitted to a Lightstreamer Server. It contains subscription details and the listeners needed to process the real-time data.
After the creation, a Subscription object is in the "inactive" state. When a Subscription object is subscribed to on a LightstreamerClient object, through the subscribe(Subscription) method, its state becomes "active". This means that the client activates a subscription to the required items through Lightstreamer Server and the Subscription object begins to receive real-time events.
A Subscription can be configured to use either an Item Group or an Item List to specify the items to be subscribed to and using either a Field Schema or Field List to specify the fields.
"Item Group" and "Item List" are defined as follows:

  • "Item Group": an Item Group is a String identifier representing a list of items. Such Item Group has to be expanded into a list of items by the getItems method of the MetadataProvider of the associated Adapter Set. When using an Item Group, items in the subscription are identified by their 1-based index within the group.
    It is possible to configure the Subscription to use an "Item Group" leveraging the ItemGroup property.
  • "Item List": an Item List is an array of Strings each one representing an item. For the Item List to be correctly interpreted a LiteralBasedProvider or a MetadataProvider with a compatible implementation of getItems has to be configured in the associated Adapter Set.
    Note that no item in the list can be empty, can contain spaces or can be a number.
    When using an Item List, items in the subscription are identified by their name or by their 1-based index within the list.
    It is possible to configure the Subscription to use an "Item List" leveraging the Items property or by specifying it in the constructor.
"Field Schema" and "Field List" are defined as follows:
  • "Field Schema": a Field Schema is a String identifier representing a list of fields. Such Field Schema has to be expanded into a list of fields by the getFields method of the MetadataProvider of the associated Adapter Set. When using a Field Schema, fields in the subscription are identified by their 1-based index within the schema.
    It is possible to configure the Subscription to use a "Field Schema" leveraging the FieldSchema property.
  • "Field List": a Field List is an array of Strings each one representing a field. For the Field List to be correctly interpreted a LiteralBasedProvider or a MetadataProvider with a compatible implementation of getFields has to be configured in the associated Adapter Set.
    Note that no field in the list can be empty or can contain spaces.
    When using a Field List, fields in the subscription are identified by their name or by their 1-based index within the list.
    It is possible to configure the Subscription to use a "Field List" leveraging the Fields property or by specifying it in the constructor.

Interfaces

ClientListener

Interface to be implemented to listen to LightstreamerClient events comprehending notifications of connection activity and errors.
Events for these listeners are dispatched by a different thread than the one that generates them. This means that, upon reception of an event, it is possible that the internal state of the client has changed. On the other hand, all the notifications for a single LightstreamerClient, including notifications to ClientListeners, SubscriptionListeners and ClientMessageListeners will be dispatched by the same thread.

ClientMessageListener

Interface to be implemented to listen to LightstreamerClient.sendMessage(string) events reporting a message processing outcome. Events for these listeners are dispatched by a different thread than the one that generates them. All the notifications for a single LightstreamerClient, including notifications to ClientListeners, SubscriptionListeners and ClientMessageListeners will be dispatched by the same thread. Only one event per message is fired on this listener.

ItemUpdate

Contains all the information related to an update of the field values for an item. It reports all the new values of the fields.

COMMAND Subscription
If the involved Subscription is a COMMAND Subscription, then the values for the current update are meant as relative to the same key.
Moreover, if the involved Subscription has a two-level behavior enabled, then each update may be associated with either a first-level or a second-level item. In this case, the reported fields are always the union of the first-level and second-level fields and each single update can only change either the first-level or the second-level fields (but for the "command" field, which is first-level and is always set to "UPDATE" upon a second-level update); note that the second-level field values are always null until the first second-level update occurs). When the two-level behavior is enabled, in all methods where a field name has to be supplied, the following convention should be followed:

  • The field name can always be used, both for the first-level and the second-level fields. In case of name conflict, the first-level field is meant.
  • The field position can always be used; however, the field positions for the second-level fields start at the highest position of the first-level field list + 1. If a field schema had been specified for either first-level or second-level Subscriptions, then client-side knowledge of the first-level schema length would be required.

SubscriptionListener

Interface to be implemented to listen to Subscription events comprehending notifications of subscription/unsubscription, updates, errors and others.
Events for this listeners are executed asynchronously with respect to the code that generates them. This means that, upon reception of an event, it is possible that the internal state of the client has changed. On the other hand, all the notifications for a single LightstreamerClient, including notifications to ClientListeners, SubscriptionListeners and ClientMessageListeners will be dispatched by the same thread.