1. Home
  2. /API Reference
  3. /REST API Libraries
  4. /RTDS Java Library

RTDS Java Library

Java library for using the Airship Real-Time Data Streaming API.

Resources

Installation

Add the library using Maven by adding the following lines to your pom.xml:

<!-- Airship Library Dependency-->
<dependency>
    <groupId>com.urbanairship</groupId>
    <artifactId>connect-client</artifactId>
    <version>VERSION</version>
    <!-- Replace VERSION with the version you want to use -->
</dependency>

The client library provides all the components you need to consume a mobile event stream.

Max strength encryption policy

RTDS requests with this client may experience SSL handshake failures unless using the Java Cryptography Extension (JCE) Unlimited Strength package cipher suite.

If you encounter a generic connection failure java.lang.RuntimeException, the max strength encryption policy might be the culprit, and you should ensure this JCE Unlimited Strength package is installed on your system. Use the package that corresponds to your JRE version:

These files are not required for JRE 9 or for JRE 8u151 or newer.

Getting started

The following sections provide information for setting up, consuming, and filtering the stream,

Setting up the stream

To set up the stream for consumption, first set the Creds, and then create a StreamQueryDescriptor and use the descriptor to create a Stream.

Configure the stream
  Creds creds = Creds.newBuilder()
          .setAppKey("key")
          .setToken("token")
          .build();

  StreamQueryDescriptor descriptor = StreamQueryDescriptor.newBuilder()
          .setCreds(creds)
          .build();

Consuming the stream

After the steam is configured, it can be consumed.

Example stream that disconnects after 60 seconds
  final Stream stream = new Stream(descriptor, Optional.<StartPosition>absent());

  final ScheduledExecutorService scheduledExecutorService = Executors.newScheduledThreadPool(1);

  Runnable stopConsuming = new Runnable() {
      public void run() {
          try {
              stream.close();
          } catch (Exception e) {
              e.printStackTrace();
          } finally {
              scheduledExecutorService.shutdown();
          }
      }
  };

  scheduledExecutorService.schedule(stopConsuming, 60, TimeUnit.SECONDS);

  while (stream.hasNext()) {
      String event = stream.next();
      System.out.println("Event: " + event);
  }

Filtering the stream

The following shows various filters and stream customizations:

Filters and customization example
  Optional<StartPosition> startPosition = Optional.fromNullable(StartPosition.relative(StartPosition.RelativePosition.EARLIEST));

  DeviceFilter device1 = new DeviceFilter(DeviceFilterType.ANDROID_CHANNEL, "152d00c3-c49c-4172-88ce-539c511cf346");
  DeviceFilter device2 = new DeviceFilter(DeviceFilterType.IOS_CHANNEL, "67fa2bad-9e83-4259-b925-bc08c184f72e");
  DeviceFilter device3 = new DeviceFilter(DeviceFilterType.NAMED_USER_ID, "cool_user");

  NotificationFilter notification = new NotificationFilter(NotificationFilter.Type.GROUP_ID, "58179035-dd1f-4b04-b023-5035c6335786");

  Filter filter = Filter.newBuilder()
          .setLatency(20000000)
          .addDevices(device1, device2, device3)
          .addDeviceTypes(DeviceType.ANDROID, DeviceType.IOS)
          .addNotifications(notification)
          .addEventTypes("OPEN")
          .build();

  Subset subset = Subset.createSampleSubset(0.3f);

  StreamQueryDescriptor descriptor = StreamQueryDescriptor.newBuilder()
          .setCreds(creds)
          .addFilters(filter)
          .setSubset(subset)
          .build();

  final Stream stream = new Stream(descriptor, startPosition);

Filter, Subset, and DeviceFilter can also be applied to a stream to retrieve whatever information wanted.