Atmosphere Client Specification 1.0 - Atmosphere/wasync Wiki


Create a WebSocket/HTTP Client which support the same set of functionality than atmosphere.js. For example, transport fallback should be supported. The API will be asynchronous and will support callbacks and Future. The API will build on top of the AHC library



Developed under the Atmosphere's umbrella, the client library should also works with with other framework like node.js, socketio protocol, cometd, etc. An Extension/PlugIn API will be defined so framework specific information can be added. For example, The Atmosphere's server needs some specifics headers (X-Cache-Date, X-Atmosphere-Transport, etc.) and that information will be provided as an extension.

Transports supported

The following transports will be supported.

Response's Decoder

The client will support the concepts of decoder, which will allow an application to write callback that gets invoked with a decoded response. The Callback API will then be invoked using a decoded response.

Request's Encoder

The client will support the concepts of encoder, which will allow an application to encode message before the get send.

Request/Response Interceptor

The client will support the concept of AtmosphereInterceptor, e.g you can intercept/filter the request's message before they get delivered to encoders and then sent to the remote server. You can also intercept/filter response's messages before they are delivered to decoders and callback.

NEEDS DECISION: Completely new Filter API (like the one in AHC) or AtmosphereInterceptor

AtmosphereHandler/Callback (or Handler)

Callbacks will be available for

NEEDS DECISION: Completely new Callback API or AtmosphereHandler


Broadcasters will work the same way they work on the server side, achieving the same goal.


Supported options: * various timeout: connect, request duration, response time, etc. * list of transport to use (start with the first one, try the second in case of failure) * etc (probably expose all AHC options?)

Code Sample

Basic request

   Options b = AtmosphereClient.options();

   AtmosphereClient client = AtmosphereClientFactory.newClient(;
   Future<AtmosphereResource> f = client.send(data)   
    .on("message",new CallBack<Data>() {
            public void on(MessageEvent<Data> m) { ... }})
    .on("close", new CloseCallback() {
            public void on(CloseEvent e) {...}})
    .on("reconnect", new ReconnectCallBack() {
            public void on(ReconnectEvent e) {...}}


public class JacksonEncoder implements Encoder<Data> {
     final ObjectMapper mapper = new ObjectMapper();
     // Data is from the request's body
     public byte[] encode(Data data) {
         return mapper.writeValueAsBytes(data);


public class JacksonDecoder implements Decoder<Data> {
     final ObjectMapper mapper = new ObjectMapper();
     public Data decode(byte[] responseBody) {
         return mapper.readValue(responseBody, Data.class);


public class ClientAtmosphereInterceptor implements AtmosphereInterceptor {

    public Action intercept(AtmosphereResource r) {
        // Do something, add headers, query string etc.
        return Action.CONTINUE;