# Server Libraries

Server libraries for using the Real-Time Data Streaming API.

<!-- PAGE: RTDS Java Library, PATH: https://www.airship.com/docs/developer/rest-api/connect/libraries/java/ -->

# RTDS Java Library

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

* [Github Repo](https://github.com/urbanairship/connect-java-library/)
* [Maven Central](https://mvnrepository.com/artifact/com.urbanairship/connect-client)
* [RTDS API Reference](https://www.airship.com/docs/developer/rest-api/connect/)


## Installation

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

```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:

- [JCE Unlimited Strength Jurisdiction Policy Files 7](http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html)
- [JCE Unlimited Strength Jurisdiction Policy Files 8](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html)

**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**

```java
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**

```java
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**

```java
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.


<!-- /PAGE: RTDS Java Library -->

<!-- PAGE: RTDS Node Library, PATH: https://www.airship.com/docs/developer/rest-api/connect/libraries/node/ -->

# RTDS Node Library

> Node library for using the Airship Real-Time Data Streaming API.## Resources

* [GitHub Repo](https://github.com/urbanairship/node-connect-client)
* [Node Package Manager (npm)](https://www.npmjs.com/package/urban-airship-connect)

## Installation

Install using `npm`:

```bash
npm install urban-airship-connect
```


## Example usage

**Basic usage example**

```javascript
var connect = require('urban-airship-connect')

var connectStream = connect('appKey', 'authToken')

connectStream.on('data', function (data) {
  // will be called with each event
})

// write to the stream to set filters/offset/start
connectStream.write({start: 'LATEST'})
```


<!-- /PAGE: RTDS Node Library -->

<!-- PAGE: RTDS Python Library, PATH: https://www.airship.com/docs/developer/rest-api/connect/libraries/python/ -->

# RTDS Python Library

> Python library for using the Airship Real-Time Data Streaming API.## Resources

* [Github Repo](https://github.com/urbanairship/connect-python-library)
* [Python Package Index (PyPI)](https://pypi.python.org/pypi/uaconnect)
* [RTDS API Reference](https://www.airship.com/docs/developer/rest-api/connect/)

## Installation

Install using `pip`:

```bash
pip install uaconnect
```


## Usage

The following sections describe various usage information for the [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds) (RTDS) API.

### RTDS Event Consumer

To consume standard events from the RTDS API, instantiate an ``EventConsumer`` object
with the application key, access token, and an [offset recorder](#offset-recorders). You can then open the
connection and start reading events.

**Create an event consumer**

```python
>>> import uaconnect
>>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     access_token='access_token',
...     recorder=uaconnect.FileRecorder('.offset'))
>>> consumer.connect()
>>> for event in consumer.read():
...     if event is None:
...        continue
>>>     print("Got event: {}".format(event))
>>>     consumer.ack(event)
```


### RTDS Compliance Event Consumer

To consume [compliance events](https://www.airship.com/docs/developer/rest-api/connect/operations/compliance-event-stream/) from the RTDS API, instantiate a ``ComplianceConsumer`` object
with the application key, master secret and an offset recorder. You can then open the
connection and start reading events.

**Create a compliance event consumer**

```python
>>> import uaconnect
 >>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     master_secret='master_secret',
...     recorder=uaconnect.FileRecorder('.offset'))
>>> consumer.connect()
>>> for event in consumer.read():
...     if event is None:
...        continue
>>>     print("Got event: {}".format(event))
 >>>     consumer.ack(event)
```


### Alternate Data Center Support

When instantiating an ``EventConsumer`` or ``ComplianceConsumer``, you can pass the optional
`url` argument to explicitly specify the data center your project is located in. Possible
values are `US`, `EU`, or an arbitrary base URL in the form of `http://domain.xyz/`. The
library will build the URL path properly from there. If no `url` is specified, `US` is used.

**EU example**

```python
>>> import uaconnect
>>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     master_secret='master_secret',
...     url='EU',
...     recorder=uaconnect.FileRecorder('.offset'))
```


### Offset Recorders

Offset recorders inherit from the abstract base class `uaconnect.Recorder`,
implementing `read_offset` and `write_offset` methods. One recorder is
included in the library, `FileRecorder`, which stores the offset on disk. In
the `uaconnect.ext.redisrecorder` package there is an example implementation
of using a Redis instance to store the offset.

`ack` calls should be placed depending on whether in a failure scenario your
app wishes to possibly replay an already handled event or risk dropping one.
For the latter, call ``ack`` as soon as the event is read. For the former, call
`ack` only after the event has been fully handled.

### Advanced Options When Connecting

Airship Real-Time Data Streaming supports a variety of options when connecting
to make sure that you're only consuming the data that you want. `uaconnect`
makes it easy to use these connection parameters and filters.

#### Specifying Offsets

One of the advantages of RTDS is that you can resume from a
specific place in the stream. This is done by specifying the ``offset``
that's associated with the event. While ``uaconnect`` automatically tracks
offsets for you with ``uaconnect.FileRecorder``, you can also explicitly set an
offset.

**Set a particular offset**

```python
>>> import uaconnect
>>> recorder = uaconnect.FileRecorder(".offset") # or wherever you would like the file to exist
>>> recorder.write_offset("8865499359") # a randomly chosen offset
>>> recorder.read_offset()
'8865499359'
```


An alternative here is to just write the offset explicitly into the file or
whatever `Recorder` subclass you're using to track offsets.

**Check the offset**

```bash
cat .offset
886549935
```


Now, the next time you connect, it will pick up from that last offset.

If you'd like to manually set the offset for a connection to a known value
instead of the recorder's offset, set `resume_offset` like so:

**Resume from a particular offset**

```python
>>> consumer.connect(resume_offset='123456789')
```


#### Using filters

Filters are a powerful way of filtering what specific information you'd like to
see from the RTDS stream. You can filter by event type, device type, latency
on an event, or even specific devices or notifications.

Here's a brief example on how to use filters with `uaconnect`:

**Filter example**

```python
>>> import uaconnect
>>> consumer = uaconnect.EventConsumer(
...     app_key='application_key',
...     access_token='access_token',
...     recorder=uaconnect.FileRecorder('.offset')
...     )
>>> f = uaconnect.Filter()
>>> f.types("PUSH_BODY", "SEND") # only receive PUSH_BODY and SEND events.
>>> consumer.add_filter(f)
>>> consumer.connect()
```



<!-- /PAGE: RTDS Python Library -->