Lightstreamer iOS Client  2.1.2
Native iOS Client library for Lightstreamer
Instance Methods | Class Methods | Properties | List of all members
LSLightstreamerClient Class Reference

Façade class for the management of the communication to Lightstreamer Server. More...

#import <LSLightstreamerClient.h>

Inheritance diagram for LSLightstreamerClient:

Instance Methods

(nonnull instancetype) - initWithServerAddress:adapterSet:
 Creates an object to be configured to connect to a Lightstreamer server and to handle all the communications with it. More...
 
(void) - addDelegate:
 Adds a delegate that will receive events from the LSLightstreamerClient instance. More...
 
(void) - connect
 Operation method that requests to open a Session against the configured Lightstreamer Server. More...
 
(void) - disconnect
 Operation method that requests to close the Session opened against the configured Lightstreamer Server (if any). More...
 
(void) - removeDelegate:
 Removes a delegate from the LSLightstreamerClient instance so that it will not receive events anymore. More...
 
(void) - sendMessage:
 A simplified version of the #sendMessage:withSequence:timeout:delegate:enqueWhileDisconnected:. More...
 
(void) - sendMessage:withSequence:timeout:delegate:enqueueWhileDisconnected:
 Operation method that sends a message to the Server. More...
 
(void) - subscribe:
 Operation method that adds a LSSubscription to the list of "active" subscriptions. More...
 
(void) - unsubscribe:
 Operation method that removes a LSSubscription that is currently in the "active" state. More...
 

Class Methods

(void) + setLoggerProvider:
 Static method that permits to configure the logging system used by the library. More...
 

Properties

NSString * LIB_NAME
 A constant string representing the name of the library. More...
 
NSString * LIB_VERSION
 A constant string representing the version of the library. More...
 
BOOL limitExceptionsUse
 Reduces the use of exceptions for error reporting. More...
 
LSConnectionOptionsconnectionOptions
 Bean object that contains options and policies for the connection to the server. More...
 
LSConnectionDetailsconnectionDetails
 Bean object that contains the details needed to open a connection to a Lightstreamer Server. More...
 
NSArray * delegates
 List containing the LSClientDelegate instances that were added to this client. More...
 
NSString * status
 Current client status and transport (when applicable). More...
 
NSArray * subscriptions
 List containing all the LSSubscription instances that are currently "active" on this LightstreamerClient. More...
 

Detailed Description

Façade 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.

Method Documentation

◆ addDelegate:()

- (void) addDelegate: (nonnull id< LSClientDelegate >)  delegate

Adds a delegate that will receive events from the LSLightstreamerClient instance.


The same delegate can be added to several different LSLightstreamerClient instances. A delegate can be added at any time. A call to add a delegate already present will be ignored.

Parameters
delegateAn object that will receive the events as documented in the LSClientDelegate interface.
Note: delegates are stored with weak references: make sure you keep a strong reference to your delegates or they may be released prematurely.

◆ connect()

- (void) 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 LSConnectionOptions::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. Note that the request to connect is accomplished by the client in a separate thread; this means that an invocation of 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.

Exceptions
NSExceptionif no server address was configured.
NSExceptionif a LSConnectionOptions::maxConcurrentSessionsPerServerExceededPolicy of "BLOCKING" was specified an the current number of sessions open to the configured server address is equal to or greater than LSConnectionOptions::maxConcurrentSessionsPerServer.

◆ disconnect()

- (void) 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 LSSubscription 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 of 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.

◆ initWithServerAddress:adapterSet:()

- (nonnull instancetype) initWithServerAddress: (nullable NSString *)  serverAddress
adapterSet: (nullable NSString *)  adapterSet 

Creates an object to be configured to connect to a Lightstreamer server and to handle all the communications with it.


Each LSLightstreamerClient is the entry point to connect to a Lightstreamer server, subscribe to as many items as needed and to send messages.

Parameters
serverAddressthe address of the Lightstreamer Server to which this LightstreamerClient will connect to. It is possible to specify it later by using nil here. See LSConnectionDetails::serverAddress for details.
adapterSetthe 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 nil here. See LSConnectionDetails::adapterSet for details.
Exceptions
NSExceptionif a not valid address is passed. See LSConnectionDetails::serverAddress for details.

◆ removeDelegate:()

- (void) removeDelegate: (nonnull id< LSClientDelegate >)  delegate

Removes a delegate from the LSLightstreamerClient instance so that it will not receive events anymore.


A delegate can be removed at any time.

Parameters
delegateThe delegate to be removed.

◆ sendMessage:()

- (void) sendMessage: (nonnull NSString *)  message

A simplified version of the #sendMessage:withSequence:timeout:delegate:enqueWhileDisconnected:.


The internal implementation will call sendMessage:message withSequence:nil timeout:0 delegate:nil enqueWhileDisconnected:NO

Parameters
messagea text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection.

◆ sendMessage:withSequence:timeout:delegate:enqueueWhileDisconnected:()

- (void) sendMessage: (nonnull NSString *)  message
withSequence: (nullable NSString *)  sequence
timeout: (NSTimeInterval)  delayTimeout
delegate: (nullable id< LSClientMessageDelegate >)  delegate
enqueueWhileDisconnected: (BOOL)  enqueueWhileDisconnected 

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 delegate. The supplied delegate is guaranteed to be eventually invoked; delegates 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. 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 LSClientMessageDelegate::messageDidAbort 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
messagea text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection.
sequencean 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 nil, "UNORDERED_MESSAGES" is used as the sequence name.
delayTimeouta timeout, expressed in seconds. If higher than the Server default timeout, the latter will be used instead.
The parameter is optional; if 0 is supplied, the Server default timeout will be applied.
This timeout is ignored for the special "UNORDERED_MESSAGES" sequence, for which a custom server-side timeout applies.
delegatean object suitable for receiving notifications about the processing outcome. The parameter is optional; if not supplied, no notification will be available.
Note: delegates are stored with weak references: make sure you keep a strong reference to your delegates or they may be released prematurely.
enqueueWhileDisconnectedif 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:()

+ (void) setLoggerProvider: (nonnull id< LSLoggerProvider >)  provider

Static method that permits to configure the logging system used by the library.


The logging system must respect the LSLoggerProvider 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
providerA LSLoggerProvider instance that will be used to generate log messages by the library classes.

◆ subscribe:()

- (void) subscribe: (nonnull LSSubscription *)  subscription

Operation method that adds a LSSubscription to the list of "active" subscriptions.


The LSSubscription 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 LSSubscription are automatically persisted across different sessions as long as a related unsubscribe call is not issued. LSSubscriptions can be given to the LSLightstreamerClient at any time. Once done the LSSubscription immediately enters the "active" state.
Once "active", a LSSubscription instance cannot be provided again to a LSLightstreamerClient 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 LSSubscriptionDelegate::subscriptionDidSubscribe event.

Parameters
subscriptionA LSSubscription object, carrying all the information needed to process its pushed values.

◆ unsubscribe:()

- (void) unsubscribe: (nonnull LSSubscription *)  subscription

Operation method that removes a LSSubscription that is currently in the "active" state.


By bringing back a LSSubscription to the "inactive" state, the unsubscription from all its items is requested to Lightstreamer Server. LSSubscription can be unsubscribed from at any time. Once done the LSSubscription 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 LSSubscriptionDelegate::subscriptionDidUnsubscribe event.

Parameters
subscriptionAn "active" LSSubscription object that was activated by this LSLightstreamerClient instance.

Property Documentation

◆ connectionDetails

- (LSConnectionDetails*) connectionDetails
readnonatomicassign

Bean 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 bean can be overwritten by values received from a Lightstreamer Server.

◆ connectionOptions

- (LSConnectionOptions*) connectionOptions
readnonatomicassign

Bean object that contains options and policies for the connection to the server.


This instance is set up by the LSLightstreamerClient object at its own creation.
Properties of this bean can be overwritten by values received from a Lightstreamer Server.

◆ delegates

- (NSArray*) delegates
readnonatomicassign

List containing the LSClientDelegate instances that were added to this client.

Returns
a list containing the delegates that were added to this client.

◆ LIB_NAME

- (NSString*) LIB_NAME
readnonatomicassign

A constant string representing the name of the library.

◆ LIB_VERSION

- (NSString*) LIB_VERSION
readnonatomicassign

A constant string representing the version of the library.

◆ limitExceptionsUse

- (BOOL) limitExceptionsUse
readwritenonatomicassign

◆ status

- (NSString*) status
readnonatomicassign

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" no connection is currently active;
  • "DISCONNECTED:WILL-RETRY" no connection is currently active but one will be open after a timeout.

◆ subscriptions

- (NSArray*) subscriptions
readnonatomicassign

List containing all the LSSubscription instances that are currently "active" on this LightstreamerClient.


Internal second-level LSSubscription are not included.

Returns
A list, containing all the LSSubscription currently "active" on this LSLightstreamerClient.
The list can be empty.

The documentation for this class was generated from the following file: