Understanding AtmosphereHandler

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();
}

onRequest

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.

onStateChange

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)

destroy

When the Atmosphere Framework is stopped.

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

• AbstractReflectorAtmosphereHandler : contains an implementation of the onStateChanged method.
• ReflectorServletProcessor : used by the framework to support Servlet Based Technology like Jersey, Wicket, Grails, etc.
• SimpleWebSocketAtmosphereHandler: A very simple handler for implementing WebSocket. It is recommended to use the WebSocketHandler API instead of AtmosphereHandler if you are planning to write pure WebSockets applications.

To get started, read this document