Java SDK

The Java SDK brings Celeris to JVM programs: backend services, workers, command-line tools, and desktop applications. It behaves like the JavaScript SDK, with Java names, CompletableFuture, and unchecked exceptions.

Each channel connection automatically joins a segment named default. Access it with channel.defaultSegment(). That stream does not need an explicit subscription. Use additional named segments when you need separate topics.

Two artifacts

• com.useceleris:celeris-client (module and package com.useceleris.client) manages connections, messages, subscriptions, and presence.
• com.useceleris:celeris-server (module and package com.useceleris.server) signs credentials from your application's access decisions. It runs on trusted servers only.

With Maven:

<dependency>
  <groupId>com.useceleris</groupId>
  <artifactId>celeris-client</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>com.useceleris</groupId>
  <artifactId>celeris-server</artifactId>
  <version>1.0.0</version>
</dependency>

With Gradle:

implementation("com.useceleris:celeris-client:1.0.0")
implementation("com.useceleris:celeris-server:1.0.0")

Add the server artifact only where the signing secret can live. It depends on the client for the credential types and errors. The client does not include signing facilities.

Both artifacts need Java 17 or newer. The client has no runtime dependencies. Its WebSocket is the JDK's own java.net.http client. Android does not have that client, so the SDK does not support Android. The server signs with the JDK alone. On the module path, requires com.useceleris.server; reads the client too.

Follow the guides

1. Connection and lifecycle: obtain credentials, connect, observe state, recover, and clean up.
2. Messaging: subscribe, publish, receive, and understand delivery.
3. Payload formats: text, JSON with Jackson or Gson, and custom serializers.
4. Presence: list connections and watch presence events.
5. Errors and troubleshooting: handle failures where the SDK reports them.
6. Server-side usage: sign credentials and connect from a trusted backend.

Read Reconnection and Recovery for the shared explanation of retries, replay, and application reconciliation. Exact signatures live in the Java client API and Java server API.

Threads and futures in brief

• A client, its channels, and their segments are safe for concurrent use from any thread. Create one client per application. The client starts its threads when it first needs them. The threads are daemon threads. A program whose only work is message receipt must keep its main thread alive itself.
• Listeners run one at a time on the client's threads, in the order events happened, and never under an SDK lock. A listener can call publish, subscribe, close, or connect. The events those calls cause follow after the listener returns. Never wait for presenceList inside a listener. The SDK routes that reply only after listeners return, so the wait always times out. Compose on the future instead.
• connect, publish, and presenceList return a CompletableFuture. Futures complete on the client's worker threads, each as its own task, independently of event delivery and of one another. A listener can wait for connect or publish. A stage you attach can wait for any of the channel's futures.
• When you cancel the future that the SDK returned, or give it a deadline with orTimeout, the SDK abandons that operation: a connection attempt, a publish not yet written, or a presence query. A cancellation of a derived stage does not reach the operation.

Work with SDK values

Timestamps delivered with messages, notices, and presence are long Unix milliseconds. Convert one with Instant.ofEpochMilli(timestamp). Presence counts are int values. Timeouts and replay lookbacks are java.time.Duration values. Payloads are byte[], and every listener receives its own copy. Value types such as MessageMetadata and PresencePage are records.

Vocabulary