Java / Android Quick Start

Installation

The library is hosted on the Jcenter repository, so you need to ensure that the repo is referenced also; IDEs will typically include this by default:

repositories {
	jcenter()
}

Maven

<dependency>
  <groupId>com.scaledrone</groupId>
  <artifactId>scaledrone-java</artifactId>
  <version>0.5.0</version>
  <type>pom</type>
</dependency>

Gradle

compile 'com.scaledrone:scaledrone-java:0.5.0'

Android

If you are using this library on Android make sure you add the INTERNET permission to the manifest file.

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

Connecting

To connect to a channel you need to first create it in the admin panel of Scaledrone's website. One instance of Scaledrone establishes a single connection.

Connecting to a new channel is done by creating a new instance of <code>Scaledrone</code> and calling the <code>connect()</code> method.

final Scaledrone drone = new Scaledrone("channel_id");
drone.connect(new Listener() {
    // overwrite the Listener methods
});

Listening to messages

Rooms are used to isolate different message types. To listen to messages, you need to subscribe to a specific room. Users can freely connect to multiple rooms (this does not create extra connections).

A received message is of type JsonNode. Jackson JsonNode can easily be transferred into POJO or String.

drone.subscribe("myroom", new RoomListener() {
    @Override
    public void onMessage(Room room, JsonNode message, Member member) {
        // parse as string
        System.out.println("Message: " + message.asText());

        // or parse as POJO
        try {
            ObjectMapper mapper = new ObjectMapper();
            Pojo pojo = mapper.treeToValue(message, Pojo.class);
            System.out.println("Message: " + pojo);
        } catch (JsonProcessingException e) {
            e.printStackTrace();
        }
    }
    // overwrite other methods
});

Sending messages

Messages are published to rooms. All users subscribed to the room will receive the message (including the user that sent the message, if they are subscribed). You don't have to be subscribed to a room when publishing to it.

The published message will be converted to JSON using Jackson.

drone.publish("roomName", data);
// or
room.publish(data);

Basic example

Make sure you replace the CHANNEL_ID string with your Scaledrone channel's ID from the dashboard.

final Scaledrone drone = new Scaledrone("CHANNEL_ID");
drone.connect(new Listener() {
    @Override
    public void onOpen() {
        drone.subscribe("myroom", new RoomListener() {
            @Override
            public void onOpen(Room room) {
                room.publish("Hello world");
            }

            @Override
            public void onOpenFailure(Room room, Exception ex) {
                // This can happen when you don't have correct permissions
                System.out.println("Failed to subscribe to room: " + ex.getMessage());
            }

            @Override
            public void onMessage(Room room, JsonNode message, Member member) {
                System.out.println("Message: " + message.asText());
            }
        });
    }

    @Override
    public void onOpenFailure(Exception ex) {
        System.out.println("Failed to open connection: " + ex.getMessage());
    }

    @Override
    public void onFailure(Exception ex) {
        System.out.println("Unexcpected failure: " + ex.getMessage());
    }

    @Override
    public void onClosed(String reason) {
        System.out.println("Connection closed: " + reason);
    }
});

Who's online functionality

To keep track of users that are connected to a room see the observable rooms documentation.

Authentication

Socket client authentication is an optional step and can be used to give precise access to specific actions and rooms. Read more about this from the authentication documentation as well as the full Java API docs.