Java Client wAsync

Java Client — wAsync

atmosphere-wasync is an async Java client for connecting to Atmosphere endpoints. It supports WebSocket, SSE, streaming, long-polling, and gRPC transports, powered by java.net.http (JDK 21+).

Dependency

<dependency>
    <groupId>org.atmosphere</groupId>
    <artifactId>atmosphere-wasync</artifactId>
    <version>4.0.4</version>
</dependency>

Quick Start

Client client = Client.newClient();

Request request = client.newRequestBuilder()
    .uri("ws://localhost:8080/atmosphere/chat")
    .transport(Request.TRANSPORT.WEBSOCKET)
    .build();

Socket socket = client.create();
socket.on(Event.OPEN, r -> System.out.println("Connected"))
      .on(Event.MESSAGE, msg -> System.out.println("Received: " + msg))
      .on(Event.ERROR, e -> ((Throwable) e).printStackTrace())
      .on(Event.CLOSE, r -> System.out.println("Disconnected"));

socket.open(request);
socket.fire("Hello from Java!");

Core API

Client

Factory for creating sockets and request builders:

Client client = Client.newClient();

Socket socket = client.create();                    // Default options
Socket socket = client.create(options);             // Custom options
RequestBuilder<?> rb = client.newRequestBuilder();  // Request builder
OptionsBuilder<?, ?> ob = client.newOptionsBuilder(); // Options builder

Socket

The connection handle — register event handlers, connect, and send messages:

// Event handlers (chainable)
socket.on(Event.OPEN, handler)
      .on(Event.MESSAGE, handler)
      .on(Event.ERROR, handler)
      .on(Event.CLOSE, handler);

// Connect
socket.open(request);

// Send data (returns CompletableFuture<Void>)
socket.fire("text message");
socket.fire(byteArray);

// State
socket.status();   // Socket.STATUS — OPEN, CLOSE, ERROR, REOPENED

// Disconnect
socket.close();

Request

Configure the connection via RequestBuilder:

Request request = client.newRequestBuilder()
    .uri("ws://localhost:8080/atmosphere/chat")
    .transport(Request.TRANSPORT.WEBSOCKET)
    .header("Authorization", "Bearer token")
    .queryString("room", "lobby")
    .encoder(new JacksonEncoder())
    .decoder(new JacksonDecoder())
    .build();

Events

Event	When Fired
Event.OPEN	Connection established
Event.MESSAGE	Data received
Event.ERROR	Error occurred
Event.CLOSE	Connection closed
Event.REOPENED	Reconnected after disconnect
Event.HEADERS	Response headers received
Event.STATUS	HTTP status received
Event.TRANSPORT	Transport negotiated

Transports

Transport	URI Scheme	Description
WEBSOCKET	ws:// / wss://	Full-duplex WebSocket
SSE	http:// / https://	Server-Sent Events
STREAMING	http:// / https://	HTTP streaming
LONG_POLLING	http:// / https://	Long-polling
GRPC	grpc://	gRPC bidirectional streaming

Transport Fallback

Request request = client.newRequestBuilder()
    .uri("http://localhost:8080/atmosphere/chat")
    .transport(Request.TRANSPORT.WEBSOCKET)
    .fallbackTransport(Request.TRANSPORT.LONG_POLLING)
    .build();

Options

Configure reconnection, timeouts, and runtime behavior:

Options options = client.newOptionsBuilder()
    .reconnect(true)
    .reconnectTimeoutInMilliseconds(5000)
    .build();

Socket socket = client.create(options);

Encoders and Decoders

Transform objects before sending and after receiving:

// Encoder: Java object → wire format
public class JacksonEncoder implements Encoder<Message, String> {
    @Override
    public String encode(Message m) {
        return objectMapper.writeValueAsString(m);
    }
}

// Decoder: wire format → Java object
public class JacksonDecoder implements Decoder<String, Message> {
    @Override
    public Message decode(String s) {
        return objectMapper.readValue(s, Message.class);
    }
}

// Register on request
Request request = client.newRequestBuilder()
    .uri("ws://localhost:8080/chat")
    .transport(Request.TRANSPORT.WEBSOCKET)
    .encoder(new JacksonEncoder())
    .decoder(new JacksonDecoder())
    .build();

gRPC Transport

Connect to an Atmosphere gRPC server:

Request request = client.newRequestBuilder()
    .uri("grpc://localhost:9090/chat")
    .transport(Request.TRANSPORT.GRPC)
    .build();

Socket socket = client.create();
socket.on(Event.MESSAGE, msg -> System.out.println(msg))
      .open(request);

socket.fire("Hello via gRPC!");

See gRPC Transport for server-side setup.

See Also

• Getting Started with atmosphere.js — TypeScript/JavaScript client
• gRPC Transport — gRPC server setup
• Understanding Broadcaster — the pub/sub bus