Getting started with the iOS and OS X Client libraries

The iOS and OS X Client Libraries have been developed using the Java SE library as a starting point. Obtaining a connection and subscribing to a table is a simple and straightforward procedure:

• Create an instance of LSClient
• Define an LSConnectionInfo object and open the connection
• When connected, define an LSTableInfo or LSExtendedTableInfo object and subscribe the table
• Start receiving the updates

Creating an instance of LSClient

To create an instance of LSClient simply alloc- and init-it, or use the factory method:

LSClient *client= [[LSClient alloc] init];

Or:

LSClient *client= [LSClient client];

Open the connection

To open the connection you must first define the connection specifications using an LSConnectionInfo object, for example:

LSConnectionInfo *connectionInfo= [LSConnectionInfo connectionInfoWithPushServerURL:@"http://push.lightstreamer.com" pushServerControlURL:nil user:nil password:nil adapter:@"DEMO"];

Done this, use the LSConnectionInfo object with the LSClient:

[client openConnectionWithInfo:connectionInfo delegate:self];

Please note that this call is blocking: it will not return until a connection has been established. Since this may take long, you may want to run it from a background thread, to avoid freezing the UI.

Listening for connection events

Your designated delegate will then receive an event when the connection actually starts:

- (void) clientConnection:(LSClient *)client didStartSessionWithPolling:(BOOL)polling {
    ...
}

Once this happens, you can start define an LSTableInfo object that describes the table you want to subscribe:

LSTableInfo *tableInfo= [LSTableInfo tableInfoWithGroup:@"item1 item2 item3" mode:LSModeMerge schema:@"stock_name last_price min max" dataAdapter:@"QUOTE_ADAPTER" snapshot:YES];

And then subscribe it using the LSClient:

LSSubscribedTableKey *tableKey= [[_client subscribeTableWithExtendedInfo:tableInfo delegate:self useCommandLogic:NO] retain];

Remember to retain the tableKey to later unsubscribe it.

Listening for table events

Your designated table delegate will then start to receive table updates as they are sent from the Server:

- (void) table:(LSSubscribedTableKey *)tableKey itemPosition:(int)itemPosition itemName:(NSString *)itemName didUpdateWithInfo:(LSUpdateInfo *)updateInfo {
    ...
}

Congratulations! Your subscription with your Lightstreamer Server is now set up!

Close the connection

Remember to always close the connection before releasing LSClient (it will not be released, otherwise):

[client closeConnection];

Automatic reconnections

The library has an advanced logic to automatically reconnect to the server in case of connection drops, timeouts, etc. The network availability is constantly monitored to attempt a reconnection only when it can be successful, and at the same time to preserve the device battery. At reconnection, the library will also automatically resubmit any subscription that was active when the connection dropped. This logic is active by default, and will stop trying only in presence of a clientConnection:didEndWithCause: event.

In view of this, avoid to manually manage the reconnection unless you have a strong reason to do so. If you really need to, close the connection during appropriate events to block the library's reconnection logic, e.g.:

- (void) clientConnection:(LSClient *)client didReceiveServerFailure:(LSPushServerException *)failure {
    [client closeConnection];
}

or:

- (void) clientConnection:(LSClient *)client didReceiveConnectionFailure:(LSPushConnectionException *)failure {
    [client closeConnection];
}

Using more than one LSClient

The library allows the use of more than one LSClient instance at the same time. However, consider that more clients means more threads, bigger memory footprint and more overhead. Moreover, please recall that every operating system poses hard limits on how many concurrent HTTP connections may be opened to the same end-point (i.e. host name and port). So, if you are going to use more that one LSClient to the same server check with the MaxConcurrentSessionsPerServerExceededPolicy parameter on LSConnectionInfo. With it, you can specify how the LSClient should behave in case this limit is exceeded. Finally, keep in mind that the library does not know a priori this limit, it simply confronts the number of open connections to the same server with the static parameter MaxConcurrentSessionsPerServer of LSConnectionInfo, which is our best guess of this limit. Highering or loweing this parameter is possible although discouraged, and may lead to unexpected results.