GitHub - ably/ably-java: Java, Android, Clojure and Scala client library SDK for Ably realtime messaging service

Ably Pub/Sub Java SDK

Build any realtime experience using Ably’s Pub/Sub Java SDK. Supported on all popular platforms and frameworks, including Kotlin and Android.

Ably Pub/Sub provides flexible APIs that deliver features such as pub-sub messaging, message history, presence, and push notifications. Utilizing Ably’s realtime messaging platform, applications benefit from its highly performant, reliable, and scalable infrastructure.

Find out more:

• Ably Pub/Sub docs.
• Ably Pub/Sub examples.

Getting started

Everything you need to get started with Ably:

• Getting started with Pub/Sub using Java.
• SDK Setup for Java.

Supported platforms

Ably aims to support a wide range of platforms. If you experience any compatibility issues, open an issue in the repository or contact Ably support.

The following platforms are supported:

Installation

The Java SDK is available as a Maven dependency. To get started with your project, install the package:

Install for Maven:

<dependency>
    <groupId>io.ably</groupId>
    <artifactId>ably-java</artifactId>
    <version>1.7.2</version>
</dependency>

Install for Gradle:

implementation 'io.ably:ably-java:1.7.2'
implementation 'org.slf4j:slf4j-simple:2.0.7'

Run the following to instantiate a client:

import io.ably.lib.realtime.AblyRealtime;
import io.ably.lib.types.ClientOptions;

ClientOptions options = new ClientOptions(apiKey);
AblyRealtime realtime = new AblyRealtime(options);

Usage

The following code connects to Ably's realtime messaging service, subscribes to a channel to receive messages, and publishes a test message to that same channel.

// Initialize Ably Realtime client
ClientOptions options = new ClientOptions("your-ably-api-key");
options.clientId = "me";
AblyRealtime realtimeClient = new AblyRealtime(options);

// Wait for connection to be established
realtimeClient.connection.on(ConnectionEvent.connected, connectionStateChange -> {
    System.out.println("Connected to Ably");
    
    // Get a reference to the 'test-channel' channel
    Channel channel = realtimeClient.channels.get("test-channel");
    
    // Subscribe to all messages published to this channel
    channel.subscribe(message -> {
        System.out.println("Received message: " + message.data);
    });
    
    // Publish a test message to the channel
    channel.publish("test-event", "hello world");
});

Live Objects

Ably Live Objects provide realtime, collaborative data structures that automatically synchronize state across all connected clients. Build interactive applications with shared data that updates instantly across devices.

Install Live Objects

Add the following dependency to your build.gradle file:

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

Example app

The Ably Live Objects Example app is an interactive demo showcasing Live Objects with realtime color voting and collaborative task management.

The example app demonstrates:

• Color Voting: Realtime voting system with live vote counts synchronized across all devices
• Task Management: Collaborative task management where users can add, edit, and delete tasks that sync in realtime

To run the example app, follow the setup instructions in the examples README.

Proxy support

You can add proxy support to the Ably Java SDK by configuring ProxyOptions in your client setup, enabling connectivity through corporate firewalls and secured networks.

import io.ably.lib.realtime.AblyRealtime;
import io.ably.lib.rest.AblyRest;
import io.ably.lib.transport.Defaults;
import io.ably.lib.types.ClientOptions;
import io.ably.lib.types.ProxyOptions;
import io.ably.lib.http.HttpAuth;

public class AblyWithProxy {
    public static void main(String[] args) throws Exception {
        // Configure Ably Client options
        ClientOptions options = new ClientOptions();
        
        // Setup proxy settings
        ProxyOptions proxy = new ProxyOptions();
        proxy.host = "your-proxy-host";  // Replace with your proxy host
        proxy.port = 8080;               // Replace with your proxy port
        
        // Optional: If the proxy requires authentication
        proxy.username = "your-username";  // Replace with proxy username
        proxy.password = "your-password";  // Replace with proxy password
        proxy.prefAuthType = HttpAuth.Type.BASIC;  // Choose your preferred authentication type (e.g., BASIC or DIGEST)

        // Attach the proxy settings to the client options
        options.proxy = proxy;

        // Create an instance of Ably using the configured options
        AblyRest ably = new AblyRest(options);

        // Alternatively, for real-time connections
        AblyRealtime ablyRealtime = new AblyRealtime(options);

        // Use the Ably client as usual
    }
}

Contribute

Read the CONTRIBUTING.md guidelines to contribute to Ably.

Releases

The CHANGELOG.md contains details of the latest releases for this SDK. You can also view all Ably releases on changelog.ably.com.

Support, feedback, and troubleshooting

For help or technical support, visit Ably's support page or GitHub Issues for community-reported bugs and discussions.