Class 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.
Inherited Members
Namespace: com.lightstreamer.client
Assembly: Lightstreamer.DotNetStandard.Client.dll
Syntax
public class LightstreamerClient
Constructors
LightstreamerClient(string, string)
Creates an object to be configured to connect to a Lightstreamer server and to handle all the communications with it. Each LightstreamerClient is the entry point to connect to a Lightstreamer server, subscribe to as many items as needed and to send messages.
Declaration
public LightstreamerClient(string serverAddress, string adapterSet)
Parameters
Type | Name | Description |
---|---|---|
string | serverAddress | the address of the Lightstreamer Server to which this LightstreamerClient will connect to. It is possible to specify it later by using null here. See ServerAddress for details. |
string | adapterSet | 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 by using null here. See AdapterSet for details. |
Fields
LIB_NAME
A constant string representing the name of the library.
Declaration
public static readonly string LIB_NAME
Field Value
Type | Description |
---|---|
string |
LIB_VERSION
A constant string representing the version of the library.
Declaration
public static readonly string LIB_VERSION
Field Value
Type | Description |
---|---|
string |
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.
Declaration
public readonly ConnectionDetails connectionDetails
Field Value
Type | Description |
---|---|
ConnectionDetails |
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.
Declaration
public readonly ConnectionOptions connectionOptions
Field Value
Type | Description |
---|---|
ConnectionOptions |
Properties
Listeners
Returns a list containing the ClientListener instances that were added to this client.
Declaration
public virtual IList<ClientListener> Listeners { get; }
Property Value
Type | Description |
---|---|
IList<ClientListener> | a list containing the listeners that were added to this client. |
See Also
Status
Inquiry method that gets the current client status and transport (when applicable).
Declaration
public virtual string Status { get; }
Property Value
Type | Description |
---|---|
string | The current client status. It can be one of the following values:
|
See Also
Subscriptions
Inquiry method that returns a list containing all the Subscription instances that are
currently "active" on this LightstreamerClient.
Internal second-level Subscription are not included.
Declaration
public virtual IList<Subscription> Subscriptions { get; }
Property Value
Type | Description |
---|---|
IList<Subscription> | A list, containing all the Subscription currently "active" on this LightstreamerClient. |
See Also
TrustManagerFactory
Provides a mean to control the way TLS certificates are evaluated, with the possibility to accept untrusted ones.
Lifecycle: May be called only once before creating any LightstreamerClient instance.
Declaration
public static RemoteCertificateValidationCallback TrustManagerFactory { set; }
Property Value
Type | Description |
---|---|
RemoteCertificateValidationCallback |
Methods
DisconnectFuture()
Works just like disconnect(), but also returns a Task which will be completed when all involved threads started by all LightstreamerClient instances have been terminated, because no more activities need to be managed and hence event dispatching is no longer necessary. Such a method is especially useful in those environments which require appropriate resource management. The method should be used in replacement of disconnect() in all those circumstances where it is indispensable to guarantee a complete shutdown of all user tasks, in order to avoid potential memory leaks and waste resources.
Declaration
public Task DisconnectFuture()
Returns
Type | Description |
---|---|
Task | A Task that will be completed when all the activities launched by all LightstreamerClient instances are terminated. |
See Also
addCookies(Uri, CookieCollection)
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 should be invoked before calling the connect() method. However it can be invoked at any time; it will affect the internal cookie set immediately and the sending of cookies on the next HTTP request or WebSocket establishment.
Declaration
public static void addCookies(Uri uri, CookieCollection cookies)
Parameters
Type | Name | Description |
---|---|---|
Uri | uri | the URI from which the supplied cookies were received. It cannot be null. |
CookieCollection | cookies | a collection of cookies. |
See Also
addListener(ClientListener)
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. A call to add a listener already present will be ignored.
Declaration
public virtual void addListener(ClientListener listener)
Parameters
Type | Name | Description |
---|---|---|
ClientListener | listener | An object that will receive the events as documented in the ClientListener interface. |
See Also
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
ForcedTransport, 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.
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 appending the request to
the internal scheduler queue; this means that an invocation to Status right after
connect() might not reflect the change yet.
When the request to connect is finally being executed, if the current status of the client is
CONNECTING, CONNECTED:* or STALLED, then nothing will be done.
Declaration
public virtual void connect()
See Also
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.
@lifecycle Note that the request to disconnect is accomplished by the client in a separate thread; this
means that an invocation to Status right after disconnect() might not reflect the change yet.
When the request to disconnect is finally being executed, if the status of the client is "DISCONNECTED",
then nothing will be done.
Declaration
public virtual void disconnect()
See Also
getCookies(Uri)
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.
See addCookies(Uri, CookieCollection) for clarifications on when cookies are directly stored
by the library and when not.
Declaration
public static CookieCollection getCookies(Uri uri)
Parameters
Type | Name | Description |
---|---|---|
Uri | uri | the URI to which the cookies should be sent, or null. |
Returns
Type | Description |
---|---|
CookieCollection | a collection with the various cookies that can be sent in a HTTP request for the specified URI. If a null URI was supplied, all available non-expired cookies will be returned. |
removeListener(ClientListener)
Removes a listener from the LightstreamerClient instance so that it will not receive events anymore.
Lifecycle: a listener can be removed at any time.
Declaration
public virtual void removeListener(ClientListener listener)
Parameters
Type | Name | Description |
---|---|---|
ClientListener | listener | The listener to be removed. |
See Also
sendMessage(string)
A simplified version of the sendMessage(string, string, int, ClientMessageListener, bool). The internal implementation will call
sendMessage(message,null,-1,null,false);
Note that this invocation involves no sequence and no listener, hence an optimized fire-and-forget behavior will be applied.
Declaration
public virtual void sendMessage(string message)
Parameters
Type | Name | Description |
---|---|---|
string | message | a text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection. |
sendMessage(string, string, int, ClientMessageListener, bool)
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.
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 onAbort(string, bool) 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 appending the request to
the internal scheduler queue; 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.
Declaration
public virtual void sendMessage(string message, string sequence, int delayTimeout, ClientMessageListener listener, bool enqueueWhileDisconnected)
Parameters
Type | Name | Description |
---|---|---|
string | message | a text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection. |
string | sequence | 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 set to null, "UNORDERED_MESSAGES" is used as the sequence name. |
int | delayTimeout | a timeout, expressed in milliseconds. If higher than the Server default timeout, the
latter will be used instead. |
ClientMessageListener | listener | an object suitable for receiving notifications about the processing outcome. The parameter is optional; if not supplied, no notification will be available. |
bool | enqueueWhileDisconnected | 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. |
setLoggerProvider(ILoggerProvider)
Static method that permits to configure the logging system used by the library. The logging system
must respect the
ILoggerProvider
interface. A custom class can be used to wrap any third-party
.NET logging tools.
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 INFO level, socket operations are logged;
at DEBUG level, read/write data exchange is logged. - lightstreamer.protocol:
logs requests to Lightstreamer Server and Server answers;
at INFO level, requests are logged;
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.subscriptions:
logs subscription requests received by the clients and the related updates;
at WARN level, alert events from the Server are logged;
at INFO level, subscriptions and unsubscriptions are logged;
at DEBUG level, requests batching and update details are logged. - lightstreamer.actions:
logs settings / API calls.
Declaration
public static void setLoggerProvider(ILoggerProvider provider)
Parameters
Type | Name | Description |
---|---|---|
ILoggerProvider | provider | A ILoggerProvider instance that will be used to generate log messages by the library classes. |
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 unsubscribe(Subscription).
Also note that forwarding of the subscription to the server is made appending the request to the internal scheduler.
A successful subscription to the server will be notified through a onSubscription()
event.
Declaration
public virtual void subscribe(Subscription subscription)
Parameters
Type | Name | Description |
---|---|---|
Subscription | subscription | A Subscription object, carrying all the information needed to process real-time values. |
See Also
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 appending the request to the internal scheduler.
The unsubscription will be notified through a onUnsubscription() event.
Declaration
public virtual void unsubscribe(Subscription subscription)
Parameters
Type | Name | Description |
---|---|---|
Subscription | subscription | An "active" Subscription object that was activated by this LightstreamerClient instance. |