atmosphere.js API
The atmosphere.js client supports many features. This document describes all the features and how to use them. Using the script is simple and can be summarized as:
- Create a Request object
- Subscribe
- Received Events
- Publish Messages
As simple as
var socket = atmosphere;
var request = new atmosphere.AtmosphereRequest();
var subSocket = socket.subscribe(request);
subSocket.push(data);The first step when writing a client side application with Atmosphere is to get a reference to the main Atmosphere's client object.
The available methods when doing
var socket = atmosphere;are
Subscribe or connect to the remote server. The request's transport will be used. If the transport is not supported by the client or server, the request.fallbackTransport will be used. See this page for the list of supported by browsers and servers. This function returns an AtmosphereRequest (called socket above) that can be used to push messages to the server. For example, if the websocket transport is used, the websocket connection can be reused for pushing messages. For other transport, a new connection will be made every time the socket.push method is used.
Publish or push data to the remote server. Depending on the transport used, a new connection will be used or the same connection reused. A new connection will be used when selected transport is polling, long-polling, streaming, jsonp or sse. The same connection will be reused if transport is websocket.
Unsubscribe or close the connection.
var request = new atmosphere.AtmosphereRequest();
request.**{options}**or
var request = **{options}**The URL to connect. URL must always starts with http:// or https://
Useful if you want atmosphere to use a particular url for websocket transport. When webSocketUrl is not defined, url is used instead.
The connect timeout. If the client fails to connect, the fallbackTransport will be used.
The interval in milliseconds before an attempt to reconnect will be made.
The maximum time a connection stay opened when no message (or event) are sent or received.
The HTTP method to use.
A list of headers to send
The request's content-type
The request body (required when doing a POST or PUT)
Suspend the request, always reconnect if the connection gets closed (for whatever reason), independently of the transport used.
The maximum number of requests that will be executed. Once the maximum gets reached, the connection will be closed. Default is -1, which means no limit.
When the streaming transport is used, the maximum size of the body received. Once reached the connection will be closed and re-opened
The log level. Value allowed are 'info', 'debug' and 'error'
The transport Atmosphere will use between the client and server. Allowed value are polling, long-polling, streaming, jsonp, sse and websocket
If either the client or server isn't able to support the selected 'transport', the fallback value will be used. Allowed value are polling, long-polling, streaming, jsonp, sse and websocket
Used when the fallbackTransport gets used.
The WebSocket API to use. As an example, you can use Flash WebSocket
The token delimiter used to wrap request.data when websockets messages are sent. This value is used with the webSocketUrl attribute.
Enable CORS Cross Origin Resource Sharing.
When enableXDR is set to true, the rewriteURL will be used to decide if the JSESSION_ID cookie be send to the remote server.
Pass all headers as query string. Some browser only support the GET method with some transport and prevent setting headers. As an example, the WebSocket API doesn't allow setting headers, and instead the headers will be passed as a query string. See this class for the list of supported headers.
By default Atmosphere does not add any extra headers to the request. The information like X-Atmosphere-Transport, X-Cache-Date etc. used by the server to track the browser state and the custom headers that you have put in the 'headers' parameter of the AtmosphereRequest are passed as a query string by default (attachHeadersAsQueryString). So if you don't really need that information passed as extra headers, let that value to true and instead let the attachHeadersAsQueryString pass the same information. Letting that value to true also facilitate CORS requests handling because no extra headers are added.
Execute the request's callback before or after reconnecting again to the server.
True when user credentials are to be included in a cross-origin request. False when they are to be excluded in a cross-origin request and when cookies are to be ignored in its response.
Track the size of the received request. This attribute must be used with the help of the Atmosphere's Server Side components called TrackMessageSizeFilter. When used, the server will use the following protocol when sending messages back to the client
<message-length><message-delimiter> message <message-delimiter>
This attribute is useful when your server side component send large chunked message. Using the trackMessageLength, the client will make sure the message has been fully received before invoking the callback. If not set, the callback might be invoked with partial message.
The token that delimit the message when the trackMessageLength attribute is used.
When set to true, Atmospere will share a connection between different browser tabs and windows. Otherwise, a new connection will be established for each tab/window. Also see this example.
When set to true, the atmosphere.js will send extra requests to handshake some data with the server. For example, the X-Atmosphere-Tracking-uuid will be handshaked before the first application request. A close message will also be sent when the browser tabs/windows are getting close to the server.
When enableXDR is used or when a request is made via CORS, the browser may refuse to read custom headers like the one Atmosphere is using. Set that value to false to stop reading that value. If enableProtocol is set to true, always set that value to false.
The maximum reconnect after a connection is marked as 'dead'. The onError will get called after the maximum is reached.
The reconnect interval when long-polling transport is used and a response received.
By default, if the server respond with a status code higher than 300, a reconnect will be executed and the onReconnect invoked. Setting it to false and the onError function will be called instead.
The specific interval in seconds of heartbeat sent from the server to this client. The value will be accepted by the server if and only if it's greater than the setting configured on server side. Note that the client does not define himself the interval of heartbeat sent from client to the server. This interval is specifies by the server with this setting.
When the page is about to reload, atmosphere.js will send a 'close' message to the server synschronously. Set that value to true to send the close asynchronously.
Set that value to the time, in millisecond, to wait for the ACK message from the server. This property only works when atmosphere-postman is used.
Set it to false if to prevent atmosphere.js to reconnect when the server is going down.
Firefox will change the window.location value when a file is downloaded from the same page and will close all connection. To prevent the issue with websocket, set that value to true. The drawback is 2 connections will be made when the page is reloading.
Whether atmosphere should handle online/offline events.. The default is to close the connection on an offline event and reconnect automatically on the online event, and generate callback events for each as appropriate). If your app is going to be handling the online/offline events itself it may make sense to disable the automatic atmosphere handling. Each connection is individually configured, so some connections may be automatic, while others handled by the application.
A function that will be invoked during the life cycle of a request. The response's function callback is defined as:
function(AtmosphereResponse) {
}The callback will be invoked every time the request's life cycle events. See AtmosphereResponse.state for a list of life cycle events. It is recommended to use the specific function's callback instead of this request's options: see request.onOpen, request.onClose, request.onMessage etc. for more details.
Invoked when the connection gets opened.
Invoked when the connection gets closed
Invoked when a message gets delivered
Invoked when an unexpected error occurs
Invoked when the client reconnects to the server
Invoked when the request.transport value is polling and a response was sent back by the server.
Invoked when the request.timeout value expire. An application may decide to reconnect in that case.
Invoked when the request.transport fail because it is not supported by the client or the server. You can reconfigure a new transport (request.transport) from that function.
Publish or push data to the remote server. Depending on the transport used, a new connection will be used or the same connection re-used. A new connection will be used when selected transport is polling, long-polling, streaming, jsonp or sse. The same connection will be reused if transport is websocket.
Same as push(AtmosphereRequest), but by only passing data using {}
The AtmosphereResponse which gets passed to AtmosphereRequest's function is defined as
The HTTP response's status code
The HTTP status reason phrase
The response's body
An array of response's headers.
Indicate the response state. Value can be messageReceived, messagePublished, opening, re-opening, closed, error
The transport used between the client and the server. Value are polling, long-polling, streaming, websocket, jsonp, sse.
The error's message when an unexpected error occurs.
The AtmosphereRequest that initiated the response.
var request = new $.atmosphere.AtmosphereRequest();
request.url = document.location.toString() + 'chat';
request.contentType = "application/json";
request.transport = 'websocket';
request.fallbackTransport = 'long-polling';or
var request = { url: document.location.host + 'chat',
contentType : "application/json",
logLevel : 'debug',
transport : 'websocket' ,
fallbackTransport: 'long-polling'}; request.onOpen = function(response) {
content.html($('<p>',
{ text: 'Atmosphere connected using ' + response.transport }));
input.removeAttr('disabled').focus();
status.text('Choose name:');
};
request.onReconnect = function (request, response) {
socket.info("Reconnecting")
};
request.onMessage = function (response) {
var message = response.responseBody;
try {
var json = JSON.parse(message);
} catch (e) {
console.log('Error: ', message.data);
return;
}
if (!logged) {
logged = true;
status.text(myName + ': ').css('color', 'blue');
input.removeAttr('disabled').focus();
} else {
input.removeAttr('disabled');
var me = json.author == author;
var date = typeof(json.time) == 'string' ?
parseInt(json.time) : json.time;
addMessage(json.author, json.text, me ?
'blue' : 'black', new Date());
}
};
request.onError = function(response) {
content.html($('<p>', { text: 'Sorry, but '
+ 'there some problem with your '
+ 'socket or the server is down' }));
}; var subSocket = socket.subscribe(request); subSocket.push(JSON.stringify({ author: author, message: msg }));- Understanding Atmosphere
- Understanding @ManagedService
- Using javax.inject.Inject and javax.inject.PostConstruct annotation
- Understanding Atmosphere's Annotation
- Understanding AtmosphereResource
- Understanding AtmosphereHandler
- Understanding WebSocketHandler
- Understanding Broadcaster
- Understanding BroadcasterCache
- Understanding Meteor
- Understanding BroadcastFilter
- Understanding Atmosphere's Events Listeners
- Understanding AtmosphereInterceptor
- Configuring Atmosphere for Performance
- Understanding JavaScript functions
- Understanding AtmosphereResourceSession
- Improving Performance by using the PoolableBroadcasterFactory
- Using Atmosphere Jersey API
- Using Meteor API
- Using AtmosphereHandler API
- Using Socket.IO
- Using GWT
- Writing HTML5 Server-Sent Events
- Using STOMP protocol
- Streaming WebSocket messages
- Configuring Atmosphere's Classes Creation and Injection
- Using AtmosphereInterceptor to customize Atmosphere Framework
- Writing WebSocket sub protocol
- Configuring Atmosphere for the Cloud
- Injecting Atmosphere's Components in Jersey
- Sharing connection between Browser's windows and tabs
- Understanding AtmosphereResourceSession
- Manage installed services
- Server Side: javadoc API
- Server Side: atmosphere.xml and web.xml configuration
- Client Side: atmosphere.js API
- Getting started with Atmosphere
- Spring, WebSocket and Atmosphere
- Starting with atmosphere framework, GWT and Maven under Eclipse