Ably Pub/Sub Java SDK

Overview

Requirements

Installation

Server

dependencies {
    implementation("io.ably.pubsub:server:2.1.0")
}

Device

dependencies {
    implementation("io.ably.pubsub:device:2.1.0")
}

<dependency>
    <groupId>io.ably.pubsub</groupId>
    <artifactId>device-jvm</artifactId>
    <version>2.1.0</version>
</dependency>

Quick start

Server

import java.util.concurrent.CompletableFuture;

import io.ably.pubsub.realtime.Channel;
import io.ably.pubsub.realtime.PubSubRealtimeClient;
import io.ably.pubsub.server.PubSubServer;
import io.ably.pubsub.types.Message;

public class ServerQuickStart {
    public static void main(String[] args) throws Exception {
        String ablyApiKey = System.getenv("ABLY_API_KEY");
        PubSubRealtimeClient realtime = PubSubServer.realtimeClientBuilder()
            .key(ablyApiKey)
            .build();

        // Subscribing attaches the channel. A message published while connecting is queued.
        Channel channel = realtime.channels.get("test-channel");
        CompletableFuture<Message> received = new CompletableFuture<>();
        channel.subscribe(received::complete);
        channel.publish("test-event", "hello world");

        System.out.println("Received: " + received.get().data);
        realtime.close();
    }
}

import io.ably.pubsub.http.PubSubHttpClient;
import io.ably.pubsub.server.PubSubServer;
import io.ably.pubsub.types.AblyException;

public class ServerPublish {
    public static void main(String[] args) throws AblyException {
        String ablyApiKey = System.getenv("ABLY_API_KEY");
        PubSubHttpClient http = PubSubServer.httpClientBuilder()
            .key(ablyApiKey)
            .build();

        http.channels.get("test-channel").publish("test-event", "hello world");
    }
}

Important

Server clients must authenticate with an API key. To use a token instead, see Server clients and token authentication.

package com.example;

import io.ably.pubsub.http.Auth;
import io.ably.pubsub.http.PubSubHttpClient;
import io.ably.pubsub.server.PubSubServer;
import io.ably.pubsub.types.AblyException;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class AblyAuthServer {
    private final PubSubHttpClient http;

    public AblyAuthServer() throws AblyException {
        String ablyApiKey = System.getenv("ABLY_API_KEY");
        http = PubSubServer.httpClientBuilder()
            .key(ablyApiKey)
            .build();
    }

    @GetMapping(value = "/ably-auth", produces = MediaType.APPLICATION_JSON_VALUE)
    public String ablyAuth() throws AblyException {
        // Authenticate the caller first. Grant only the operations this user needs.
        String userId = "me"; // the signed-in user's ID, from your session
        Auth.TokenParams params = new Auth.TokenParams();
        params.clientId = userId;
        // Without a capability, the token gets all of the API key's capabilities.
        params.capability = "{\"test-channel\":[\"publish\",\"subscribe\",\"history\"]}";

        return http.auth.createTokenRequest(params, null).asJson();
    }

    public static void main(String[] args) {
        SpringApplication.run(AblyAuthServer.class, args);
    }
}

Device

import io.ably.pubsub.device.PubSubDevice;
import io.ably.pubsub.realtime.Channel;
import io.ably.pubsub.realtime.PubSubRealtimeClient;
import io.ably.pubsub.types.AblyException;

public class DeviceQuickStart {
    public static void main(String[] args) throws AblyException {
        PubSubRealtimeClient realtime = PubSubDevice.clientBuilder()
            .authUrl("https://your-server.example.com/ably-auth")
            .clientId("me")
            .build();

        // The client connects automatically. Subscribing attaches the channel.
        Channel channel = realtime.channels.get("test-channel");
        channel.subscribe(message -> System.out.println("Received: " + message.data));
        channel.publish("test-event", "hello world");
    }
}

Migrating from 1.x

Common configuration

Endpoint

String ablyApiKey = System.getenv("ABLY_API_KEY");
PubSubRealtimeClient realtime = PubSubServer.realtimeClientBuilder()
    .key(ablyApiKey)
    .endpoint("nonprod:sandbox")
    .build();

Network client

dependencies {
    implementation("io.ably.pubsub:server:2.1.0") {
        exclude(group = "io.ably.pubsub", module = "network-client-okhttp")
    }
    runtimeOnly("io.ably.pubsub:network-client-default:2.1.0")
}

Proxy

import io.ably.pubsub.http.HttpAuth;
import io.ably.pubsub.types.ProxyOptions;

ProxyOptions proxy = new ProxyOptions();
proxy.host = "your-proxy-host";
proxy.port = 8080;

// Only if the proxy requires authentication.
proxy.username = "your-username";
proxy.password = "your-password";
proxy.prefAuthType = HttpAuth.Type.BASIC;

String ablyApiKey = System.getenv("ABLY_API_KEY");
PubSubRealtimeClient realtime = PubSubServer.realtimeClientBuilder()
    .key(ablyApiKey)
    .proxy(proxy)
    .build();

Logging

import io.ably.pubsub.util.Log;

String ablyApiKey = System.getenv("ABLY_API_KEY");
PubSubRealtimeClient realtime = PubSubServer.realtimeClientBuilder()
    .key(ablyApiKey)
    .logLevel(Log.DEBUG)
    .logHandler((severity, tag, msg, tr) -> System.err.println(tag + ": " + msg))
    .build();

Live Objects

dependencies {
    runtimeOnly("io.ably.pubsub:liveobjects:2.1.0")
}

Known limitations

Further reading

Contributing

Support, feedback and troubleshooting

License