pub struct LightstreamerClient {
pub connection_details: ConnectionDetails,
pub connection_options: ConnectionOptions,
pub subscription_sender: Sender<SubscriptionRequest>,
/* private fields */
}
Expand description
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.
§Parameters
server_address
: the address of the Lightstreamer Server to which thisLightstreamerClient
will connect to. It is possible to specify it later by usingNone
here. SeeConnectionDetails.setServerAddress()
for details.adapter_set
: the name of the Adapter Set mounted on Lightstreamer Server to be used to handle all requests in the Session associated with thisLightstreamerClient
. It is possible not to specify it at all or to specify it later by usingNone
here. SeeConnectionDetails.setAdapterSet()
for details.
§Raises
IllegalArgumentException
: if a not valid address is passed. SeeConnectionDetails.setServerAddress()
for details.
Fields§
§connection_details: 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.
connection_options: 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.
subscription_sender: Sender<SubscriptionRequest>
The sender that can be used to subscribe/unsubscribe
Implementations§
Source§impl LightstreamerClient
impl LightstreamerClient
Sourcepub const LIB_NAME: &'static str = "rust_client"
pub const LIB_NAME: &'static str = "rust_client"
A constant string representing the name of the library.
Sourcepub const LIB_VERSION: &'static str = "0.1.0"
pub const LIB_VERSION: &'static str = "0.1.0"
A constant string representing the version of the library.
Sourcepub const SEC_WEBSOCKET_KEY: &'static str = "PNDUibe9ex7PnsrLbt0N4w=="
pub const SEC_WEBSOCKET_KEY: &'static str = "PNDUibe9ex7PnsrLbt0N4w=="
WebSocket key used in the WebSocket handshake process. This is a base64-encoded value that is used to establish the WebSocket connection.
Sourcepub const SEC_WEBSOCKET_PROTOCOL: &'static str = "TLCP-2.4.0.lightstreamer.com"
pub const SEC_WEBSOCKET_PROTOCOL: &'static str = "TLCP-2.4.0.lightstreamer.com"
WebSocket protocol identifier for the TLCP protocol used by Lightstreamer. This identifies the specific subprotocol used over the WebSocket connection.
Sourcepub const SEC_WEBSOCKET_VERSION: &'static str = "13"
pub const SEC_WEBSOCKET_VERSION: &'static str = "13"
WebSocket version used for the connection. Version 13 is the standard version used in modern WebSocket implementations.
Sourcepub const SEC_WEBSOCKET_UPGRADE: &'static str = "websocket"
pub const SEC_WEBSOCKET_UPGRADE: &'static str = "websocket"
WebSocket upgrade header value. Used to indicate that the client wishes to upgrade from HTTP to WebSocket protocol.
Sourcepub const TLCP_VERSION: &'static str = "TLCP-2.4.0"
pub const TLCP_VERSION: &'static str = "TLCP-2.4.0"
A constant string representing the version of the TLCP protocol used by the library.
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.
This method should be invoked before calling the LightstreamerClient.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.
§Parameters
uri
: the URI from which the supplied cookies were received. It cannot beNone
.cookies
: an instance ofhttp.cookies.SimpleCookie
.
See also getCookies()
Sourcepub fn add_listener(&mut self, listener: Box<dyn ClientListener>)
pub fn add_listener(&mut self, listener: Box<dyn ClientListener>)
Adds a listener that will receive events from the LightstreamerClient
instance.
The same listener can be added to several different LightstreamerClient
instances.
A listener can be added at any time. A call to add a listener already present will be ignored.
§Parameters
listener
: An object that will receive the events as documented in theClientListener
interface.
See also removeListener()
Sourcepub async fn connect(
&mut self,
shutdown_signal: Arc<Notify>,
) -> Result<(), Box<dyn Error + Send + Sync>>
pub async fn connect( &mut self, shutdown_signal: Arc<Notify>, ) -> Result<(), Box<dyn Error + Send + Sync>>
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.
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.
Note that the request to connect is accomplished by the client in a separate thread; this
means that an invocation to getStatus()
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 not DISCONNECTED
, then nothing will be done.
§Raises
IllegalStateException
: if no server address was configured.
See also getStatus()
See also disconnect()
See also ClientListener.onStatusChange()
See also ConnectionDetails.setServerAddress()
Sourcepub async fn disconnect(&mut self)
pub async fn disconnect(&mut self)
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.
Note that the request to disconnect is accomplished by the client in a separate thread; this
means that an invocation to getStatus()
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.
See also connect()
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()
for clarifications on when cookies are directly stored by the library and
when not.
§Parameters
uri
: the URI to which the cookies should be sent, orNone
.
§Returns
A list with the various cookies that can be sent in a HTTP request for the specified URI.
If a None
URI was supplied, all available non-expired cookies will be returned.
Sourcepub fn get_listeners(&self) -> &Vec<Box<dyn ClientListener>>
pub fn get_listeners(&self) -> &Vec<Box<dyn ClientListener>>
Returns a list containing the ClientListener
instances that were added to this client.
§Returns
A list containing the listeners that were added to this client.
See also addListener()
Sourcepub fn get_status(&self) -> &ClientStatus
pub fn get_status(&self) -> &ClientStatus
Inquiry method that gets the current client status and transport (when applicable).
§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 (possibly 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.
See also ClientListener.onStatusChange()
Sourcepub fn get_subscriptions(&self) -> &Vec<Subscription>
pub fn get_subscriptions(&self) -> &Vec<Subscription>
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.
§Returns
A list, containing all the Subscription
currently “active” on this LightstreamerClient
.
The list can be empty.
See also subscribe()
Sourcepub fn new(
server_address: Option<&str>,
adapter_set: Option<&str>,
username: Option<&str>,
password: Option<&str>,
) -> Result<LightstreamerClient, Box<dyn Error>>
pub fn new( server_address: Option<&str>, adapter_set: Option<&str>, username: Option<&str>, password: Option<&str>, ) -> Result<LightstreamerClient, Box<dyn Error>>
Creates a new instance of LightstreamerClient
.
The constructor initializes the client with the server address and adapter set, if provided.
It sets up the connection details and options for the client. If no server address or
adapter set is specified, those properties on the client will be None
. This allows
for late configuration of these details before connecting to the Lightstreamer server.
§Arguments
server_address
- An optional reference to a string slice that represents the server address to connect to. IfNone
, the server address must be set later.adapter_set
- An optional reference to a string slice that specifies the adapter set name. IfNone
, the adapter set must be set later.
§Returns
A result containing the new LightstreamerClient
instance if successful, or an
IllegalStateException
if the initialization fails due to invalid state conditions.
§Panics
Does not panic under normal circumstances. However, unexpected internal errors during the creation of internal components could cause panics, which should be considered when using this function in production code.
Sourcepub fn remove_listener(&mut self, _listener: Box<dyn ClientListener>)
pub fn remove_listener(&mut self, _listener: Box<dyn ClientListener>)
Removes a listener from the LightstreamerClient
instance so that it will not receive
events anymore.
A listener can be removed at any time.
§Parameters
listener
: The listener to be removed.
See also addListener()
Sourcepub fn send_message(
&mut self,
message: &str,
sequence: Option<&str>,
_delay_timeout: Option<u64>,
listener: Option<Box<dyn ClientMessageListener>>,
enqueue_while_disconnected: bool,
)
pub fn send_message( &mut self, message: &str, sequence: Option<&str>, _delay_timeout: Option<u64>, listener: Option<Box<dyn ClientMessageListener>>, enqueue_while_disconnected: 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.
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.
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 in a separate thread, 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
message
: a text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection.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 toNone
, “UNORDERED_MESSAGES” is used as the sequence name.delay_timeout
: a timeout, expressed in milliseconds. If higher than the Server configured timeout on missing messages, the latter will be used instead. The parameter is optional; if a negative value is supplied, the Server configured timeout on missing messages will be applied. This timeout is ignored for the special “UNORDERED_MESSAGES” sequence, although a server-side timeout on missing messages still applies.listener
: an object suitable for receiving notifications about the processing outcome. The parameter is optional; if not supplied, no notification will be available.enqueue_while_disconnected
: if this flag is set totrue
, 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.
Sourcepub fn set_logger_provider()
pub fn set_logger_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 logging system.
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.
§Parameters
provider
: ALoggerProvider
instance that will be used to generate log messages by the library classes.
Sourcepub fn set_trust_manager_factory()
pub fn set_trust_manager_factory()
Provides a mean to control the way TLS certificates are evaluated, with the possibility to accept untrusted ones.
May be called only once before creating any LightstreamerClient
instance.
§Parameters
factory
: an instance ofssl.SSLContext
§Raises
IllegalArgumentException
: if the factory isNone
IllegalStateException
: if a factory is already installed
Sourcepub async fn subscribe(
subscription_sender: Sender<SubscriptionRequest>,
subscription: Subscription,
)
pub async fn subscribe( subscription_sender: Sender<SubscriptionRequest>, subscription: Subscription, )
Adds a subscription to the LightstreamerClient
instance.
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.
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()
.
Also note that forwarding of the subscription to the server is made in a separate thread.
A successful subscription to the server will be notified through a SubscriptionListener.onSubscription()
event.
§Parameters
subsrciption_sender
: ASender
object that sends aSubscriptionRequest
to theLightstreamerClient
subscription
: ASubscription
object, carrying all the information needed to process real-time values.
See also unsubscribe()
Sourcepub async fn subscribe_get_id(
subscription_sender: Sender<SubscriptionRequest>,
subscription: Subscription,
) -> Result<usize, Box<dyn Error + Send + Sync>>
pub async fn subscribe_get_id( subscription_sender: Sender<SubscriptionRequest>, subscription: Subscription, ) -> Result<usize, Box<dyn Error + Send + Sync>>
If you want to be able to unsubscribe from a subscription, you need to keep track of the id of the subscription. This blocking method allows you to wait for the id of the subscription to be returned.
§Parameters
subscription_sender
: ASender
object that sends aSubscriptionRequest
to theLightstreamerClient
subscription
: ASubscription
object, carrying all the information needed to process real-time
Sourcepub async fn unsubscribe(
subscription_sender: Sender<SubscriptionRequest>,
subscription_id: usize,
)
pub async fn unsubscribe( subscription_sender: Sender<SubscriptionRequest>, subscription_id: usize, )
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.
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 in a separate thread.
The unsubscription will be notified through a SubscriptionListener.onUnsubscription()
event.
§Parameters
subsrciption_sender
: ASender
object that sends aSubscriptionRequest
to theLightstreamerClient
subscription_id
: The id of the subscription to be unsubscribed from. instance.
Sourcepub fn set_logging_type(&mut self, logging: LogType)
pub fn set_logging_type(&mut self, logging: LogType)
Method setting enum for the logging of this instance.
Default logging type is StdLogs, corresponding to stdout
LightstreamerClient
has methods for logging that are compatible with the Tracing
crate.
Enabling logging for the Tracing
crate requires implementation of a tracing subscriber
and its configuration and formatting.
§Parameters
logging
: An enum declaring the logging type of thisLightstreamerClient
instance.