Understanding AtmosphereHandler

jfarcand edited this page May 28, 2012 · 3 revisions


Step by Step Tutorials

Concepts & Architecture

15 Minutes Tutorial

Advanced Topics


Known WebServer Issues


External Documentations

githalytics.com alpha

Clone this wiki locally

An AtmosphereHandler is the central concept of an Atmosphere Framework application. AtmosphereHandler are the lowest component an application can implement. For example, the atmosphere-jersey and atmosphere-gwt build on top of AtmosphereHandler. The interface is defined as:

public interface AtmosphereHandler {

     * When a client send a request to its associated AtmosphereHandler, it can decide
     * if the underlying connection can be suspended (creating a Continuation)
     * or handle the connection synchronously.
     * It is recommended to only suspend request for which HTTP method is a GET
     * and use the POST method to send data to the server, without marking the
     * connection as asynchronous.
    void onRequest(AtmosphereResource resource) throws IOException;

     * This method is invoked when the Broadcaster execute a broadcast
     * operations. When this method is invoked its associated Broadcaster, any
     * suspended connection will be allowed to write the data back to its
     * associated clients. 
     * This method will also be invoked when a response get resumed,
     * e.g. when AtmosphereResource#resume gets invoked. In that case,
     * AtmosphereResourceEvent#isResuming will return true.
     * This method will also be invoked when the AtmosphereResource#suspend(long)
     * expires. In that case, AtmosphereResourceEvent#isResumedOnTimeout will return
     * true
    void onStateChange(AtmosphereResourceEvent event) throws IOException;

     * Destroy this handler
    void destroy();


The AtmosphereHandler.onRequest is invoked every time a new connection is made to an application. An application must take action and decide what to do with the AtmosphereResource, e.g. suspend, resume or broadcast events. You can also write String or bytes back to the client from that method.


This method gets invoked when:

  • The remote connection gets closed, either by a browser or a proxy
  • The remote connection reach its maximum idle time (AtmosphereResource.suspend)
  • Everytime a broadcast operation is executed (broadcaster.broadcast)


When the Atmosphere Framework is stopped.

The framework ships with some AtmosphereHandler implementation that can be extended easily:

To get started, read this document