Note that this documentation is a note to self and mostly likely is currently wrong because my code isn't working yet!

Atmosphere

Atmosphere provides consistent client side (JavaScript) and server side (Java) libraries for websocket like support across different web browsers and web servers.

This documentation is written from the perspective of a developer trying to integrate the support into a Scala application which already uses jQuery on the client.

Installing

The web server support is supplied with the library:

"org.atmosphere" % "atmosphere-runtime" % "0.7.2"

The web client support is supplied with the jquery.atmosphere.js library which can be downloaded from here: https://raw.github.com/Atmosphere/atmosphere/master/modules/jquery/src/main/webapp/jquery/jquery.atmosphere.js. All the sources can be found in the github repository here: https://github.com/Atmosphere/atmosphere.

Note that there is a change in the Jetty Websocket API in more recent versions of 7.x and all the 8.x versions which requires the use of Atmosphere version 2.0.0-SNAPSHOT.

Establishing a socket ‘connection’

A websocket like connection should be initiated by the client (web browser) by making an HTTP request to the server requesting a connection. The request should look something like:

$.atmosphere.subscribe(
    SERVER_CONNECTION_URL,
    callback,
    $.atmosphere.request = { transport: ‘websocket’ } );

The SERVER_CONNECTION_URL is a URL on the server which should be set up to use the Atmosphere Java library to establish the connection (see later).

The callback should be a function that will handle the confirmation of the connection from the server.

The $.atmosphere.request allows various parameters to be set for the socket connection. In this example we are defining the preferred transport mechanism to use: asking to establish a websocket connection though this will automatically fall-back to another type of connection if websocket is unsupported by client or server. We could also ask for long-polling or streaming.

Handling the callback

The callback function will be called by the query.atmosphere.js library once a socket connection has been established with the server and with any messages that follow after that. The callback function should be of the form:

function callback(response) { … }

Within this function response.transport (String) will contain the type of connection transport that has been established though it can also have values that suggest state of the connection e.g.: polling, connected and closed.

The response.status (Integer) appears to indicate that the body of the response contains data which can be found in response.responseBody (String).

`$.atmosphere.response`

After the subscription has been requested the push function of the $.atmosphere.response object is defined as a function for sending messages on the socket connection. This push request has the following form:

$.atmosphere.response.push(
    SERVER_CONNECTION_URL,
    null,
    $.atmosphere.request = {data: ‘the data’} );

The second parameter is a callback function. This callback function, if not already registered during the subscription process, will be added to the list of callbacks for the connection. If a null value is passed (as in this example) then no callback is added or removed.

`$.atmosphere.close()`

The $.atmosphere.close() function will close any existing connection and is a short form of $.atmosphere.closeSuspendedConnection().

sroebuck/atmosphere.md