Lightstreamer Android Client SDK 5.2.1 API Reference

Summary

  1. Introduction
  2. Installing
  3. Quickstart
  4. Mobile Push Notifications
  5. Logging
  6. Compatibility
  7. Documentation
  8. Support
  9. License
  10. Packages

Introduction

This Android library enables any Android application to communicate bidirectionally with the Lightstreamer Server. The API allows to subscribe to real-time data delivered directly by the server or routed via mobile push notifications, and to send any message to the server.

The library exposes a fully asynchronous API. All the API calls that require any action from the library itself are queued for processing by a dedicated thread before being carried out. The same thread is also used to carry notifications for the appropriate listeners as provided by the custom code. Blocking operations and internal housekeeping are performed on different threads.

The library offers automatic recovery from connection failures, automatic selection of the best available transport, and full decoupling of subscription and connection operations. The subscriptions are always meant as subscriptions "to the LightstreamerClient", not "to the Server"; the LightstreamerClient is responsible of forwarding the subscriptions to the Server and re-forwarding all the subscriptions whenever the connection is broken and then reopened.

The library also offers support for mobile push notifications (MPN). While real-time subscriptions deliver their updates via the client connection, MPN subscriptions deliver their updates via push notifications, even when the application is offline. They are handled by a special module of the Server, the MPN Module, that keeps them active at all times and continues pushing with no need for a client connection. However, push notifications are not real-time, they may be delayed by the service provider (FCM) and their delivery is not guaranteed.

The Android library can be available depending on Edition and License Type. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

Installing

To add a dependency using Maven: 

<dependency>
  <groupId>com.lightstreamer</groupId>
  <artifactId>ls-android-client</artifactId>
  <version>5.2.1</version>
</dependency>
To add a dependency using Gradle: 

dependencies {
  implementation("com.lightstreamer:ls-android-client:5.2.1")
}

Quickstart

To connect to a Lightstreamer Server, a LightstreamerClient object has to be created, configured, and instructed to connect to the Lightstreamer Server. A minimal version of the code that creates a LightstreamerClient and connects to the Lightstreamer Server on https://push.lightstreamer.com will look like this: 

LightstreamerClient client = new LightstreamerClient("https://push.lightstreamer.com/","DEMO");
client.connect();
For each subscription to be subscribed to a Lightstreamer Server a Subscription instance is needed. A simple Subscription containing three items and two fields to be subscribed in MERGE mode is easily created (see Lightstreamer General Concepts): 

String[] items = { "item1","item2","item3" };
String[] fields = { "stock_name","last_price" };
Subscription sub = new Subscription("MERGE",items,fields);
sub.setDataAdapter("QUOTE_ADAPTER");
sub.setRequestedSnapshot("yes");
client.subscribe(sub);
Before sending the subscription to the server, usually at least one SubscriptionListener is attached to the Subscription instance in order to consume the real-time updates. The following code shows the values of the fields stock_name and last_price each time a new update is received for the subscription: 

sub.addListener(new SubscriptionListener() {
    public void onItemUpdate(ItemUpdate obj) {
        System.out.println(obj.getValue("stock_name") + ": " + obj.getValue("last_price"));
    }
    // other methods...
});

Mobile Push Notifications Quickstart

Mobile Push Notifications (MPN) are based on Google's Firebase Cloud Messaging technology. Before you can use MPN services, you need to After you have a Firebase project, you can create a MpnDevice, which represents a specific app running on a specific mobile device. 

FirebaseInstanceId.getInstance().getInstanceId().addOnCompleteListener(new OnCompleteListener<InstanceIdResult>() {
    public void onComplete(final Task<InstanceIdResult> task) {
        if (task.isSuccessful()) {
            MpnDevice device = new MpnDevice(context, task.getResult().getToken());
            client.registerForMpn(device);
        }
    }
});
To receive notifications, you need to subscribe to a MpnSubscription: it contains subscription details and the listener needed to monitor its status. Real-time data is routed via native push notifications. 

String[] items = { "item1","item2","item3" };
String[] fields = { "stock_name","last_price" };
MpnSubscription sub = new MpnSubscription("MERGE",items,fields);
Map<String, String> data= new HashMap<String, String>();
data.put("stock_name", "${stock_name}");
data.put("last_price", "${last_price}");
data.put("time", "${time}");
data.put("item", stockSubscription.getItems()[0]);
String format = new MpnBuilder().data(data).build();
sub.setNotificationFormat(format);
sub.setTriggerExpression("Double.parseDouble($[2])>45.0");
client.subscribe(sub, true);
The notification format lets you specify how to format the notification message. It can contain a special syntax that lets you compose the message with the content of the subscription updates (see §5.4.1 of the General Concepts guide).

The optional trigger expression lets you specify when to send the notification message: it is a boolean expression, in Java language, that when evaluates to true triggers the sending of the notification (see §5.4.2 of the General Concepts guide). If not specified, a notification is sent each time the Data Adapter produces an update.

Finally, you need to configure a service that extends FirebaseMessagingService in order to receive foreground/background notifications.
The steps are described in the Firebase documentation about Receive messages in an Android app. As an example, you can see the class MyFirebaseMessagingService in the Lightstreamer MPN StockList demo.

Logging

To enable the internal client logger, create an instance of LoggerProvider and set it as the default provider of LightstreamerClient. 

LightstreamerClient.setLoggerProvider(new ConsoleLoggerProvider(ConsoleLogLevel.DEBUG));

Compatibility

Android Client requires Android 8 (API level 26) or greater.

The library is compatible with Lightstreamer Server since version 7.4.0.

Documentation

Support

For questions and support please use the Official Forum. The issue list of this page is exclusively for bug reports and feature requests.

License

Apache 2.0