StreamLink is an API that allows an application to exchange real-time financial data and trade messages with Caplin Liberator servers via the Web or other TCP/IP network.

It provides the following capabilities:

• Record Subscriptions (including type2 and type 3 data).
• Container subscriptions.
• Directory subscriptions.
• Permission subscriptions.
• Chat subscriptions.
• News headline and news story subscriptions.
• Connection status notification.
• Reconnection and failover.
• Publishing data to subjects.
• Creating and deleting objects on the Liberator.
• Throttling of individual subjects.
• Throttling of the entire session.

Getting Started

It is recommended that you read the Caplin StreamLink Overview to gain understanding of:

• What StreamLink is and how it can be used.
• Fundamental StreamLink concepts & features.
• How StreamLink can integrate with your own client application software to provide a streaming data display and support online trading of financial instruments.

Subscribing to data and receiving updates

To subscribe to data and receive updates to the data you need to:

• implement (code) some interfaces from the API User Layer,
• call various methods from the API User Layer to connect to a Liberator and set up the subscription.

Handling responses

The API operates asynchronously. This means that when the client application code issues a subscription request or a command to StreamLink, the response is not returned immediately through the method used to issue the request or command. Instead, you must set up a listener object (SubscriptionListener). You then supply this listener to StreamLink. StreamLink calls the appropriate callback method(s) on the listener object to communicate data and command responses back to the client code.

Implementing interfaces

Much of the StreamLink API is defined as interfaces. You must implement some of the interfaces in order use StreamLink. These implementations effectively integrate StreamLink with your client application. There are also protocols with implementations that are built into the API, so in these cases you do not need to write your own.

Note:The description of each interface states if you must implement it before use.

As a minimum you need to implement the SubscriptionListener interface. StreamLink calls your SubscriptionListener implementation to deal with events concerning subscriptions to data.

You should also implement the ConnectionListener interface if you want to provide users of your application with information about the state of the connection.

How to incorporate StreamLink into your Android application

To include StreamLink in your Eclipse Android project, simply add the StreamLink Android jar file to the project's libs directory. StreamLink then shows in the 'Android Dependencies' folder within the Package Explorer.

To allow StreamLink to access the network, you must add a user permission to the Android manifest file (AndroidManifest.xml):

<uses-permission android:name="android.permission.INTERNET" />

To allow StreamLink to monitor the network availability, add this permission:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Also see Managing network availability.

Interaction with UI main thread

The methods of the callback interfaces you register with StreamLink (for example, methods of SubscriptionListener) are always invoked on a non-GUI thread. Since all Android GUI updates must occur on the GUI thread, your implementation of these callbacks must not directly update the GUI.

One way to update the GUI from a StreamLink callback is to use a Handler class that delivers runnables to the GUI message queue, as follows:

...
this.handler = new Handler();
...
SubscriptionListener subscriptionListener = new BaseSubscriptionListener()
{
    public void onRecordUpdate(Subscription subscription, final RecordType1Event event) {
        handler.post(new Runnable() {
            public void run() {
                // implement handleStreamLinkRecordUpdate() to handle updates on GUI thread
                handleStreamLinkRecordUpdate(event); 
            }
        });
    }
};

Suspending and resuming the application

On Android, applications can be paused (put in the background) when others are made active. When this happens, you may wish to pause StreamLink so it does not receive new updates from the Liberator until the application is active again. To do this, your application should call the pause() and resume() methods of the StreamLink instance at the relevant times (for example, in the onStart() and onStop() methods of the main Activity).

When StreamLink is paused, it disconnects from the Liberator but retains its record of the current subscriptions. When resumed, it subscribes again to all subjects on the Liberator, and recommences supplying updates to all registered listeners.

How to set up logging

To log StreamLink messages to the Android Log Console (LogCat tab in Eclipse), add a StreamLink logger as follows:

streamlink.getLogger().addListener(new LogListener() {
    public void onLog(LogInfo logInfo) {
        Log.i("SL Log", logInfo.getMessage());
    }
}, LogLevel.FINEST);

This example logs all StreamLink messages at the log level LogLevel.FINEST or above to the Android log window, posting them at 'informational' level.

Managing network availability

When the network that the mobile device uses is not available, your application should tell StreamLink so it can stop trying to establish a connection to the Liberator. To do this, the application should register for notifications about changes to the network availability; see the demo app for a simple example of this. When such changes occur, the application should call the StreamLink object's networkAvailable() or networkUnavailable() method as appropriate.

Note: To receive network availability notifications, you must add the following permission to the Android manifest file (AndroidManifest.xml):

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Packages

Package	Description
com.caplin.streamlink	The interfaces within this package provide the functionality of StreamLink.
com.caplin.streamlink.alerts	The interfaces within this package provide the functionality of Triggers and Notifications.