Package org.atmosphere.cpr

Interface AtmosphereHandler

All Known Subinterfaces:

AnnotatedProxy, AtmosphereServletProcessor

All Known Implementing Classes:

AbstractReflectorAtmosphereHandler, AbstractReflectorAtmosphereHandler.Default, AtmosphereHandlerAdapter, ManagedAtmosphereHandler, OnMessage, ReflectorServletProcessor

public interface AtmosphereHandler

Implementation of AtmosphereHandler allows creation of event-driven web applications which are hosted in the browser. An AtmosphereHandler allows a web application to suspend and resume an HTTP response. An HTTP response can be suspended AtmosphereResource.suspend() and later resume via AtmosphereResource.resume(). Messages can also be shared between suspended responses and their associated AtmosphereHandler using a Broadcaster. Any invocation of Broadcaster.broadcast(java.lang.Object) will allow a suspended response to write the content of the message onStateChange(org.atmosphere.cpr.AtmosphereResourceEvent).

A class implementing AtmosphereHandler must be thread safe.

For example, a simple pubsub based AtmosphereHandler will take the form of

 public class AtmosphereHandlerPubSub extends AbstractReflectorAtmosphereHandler {

    public void onRequest(AtmosphereResource r) throws IOException {

        AtmosphereRequest req = r.getRequest();
        AtmosphereResponse res = r.getResponse();
        String method = req.getMethod();

        // Suspend the response.
        if ("GET".equalsIgnoreCase(method)) {
            // Log all events on the console, including WebSocket events.
            r.addEventListener(new WebSocketEventListenerAdapter());

            res.setContentType("text/html;charset=ISO-8859-1");

            Broadcaster b = lookupBroadcaster(req.getPathInfo());
            r.setBroadcaster(b).suspend();
        } else if ("POST".equalsIgnoreCase(method)) {
            Broadcaster b = lookupBroadcaster(req.getPathInfo());

            String message = req.getReader().readLine();

            if (message != null && message.indexOf("message") != -1) {
                b.broadcast(message.substring("message=".length()));
            }
        }
    }

    public void destroy() {
    }

    Broadcaster lookupBroadcaster(String pathInfo) {
        String[] decodedPath = pathInfo.split("/");
        Broadcaster b = BroadcasterFactory.getDefault().lookup(decodedPath[decodedPath.length - 1], true);
        return b;
    }

}

It is recommended to use the AtmosphereHandlerService or ManagedService annotation to reduce the number of lines of code and take advantage of AtmosphereInterceptor such as AtmosphereResourceStateRecovery and AtmosphereResourceLifecycleInterceptor.

Author:

Jeanfrancois Arcand

Method Summary

Modifier and Type	Method	Description
void	destroy()	Destroy this handler
void	onRequest(AtmosphereResource resource)	When a client sends a request to its associated AtmosphereHandler, it can decide if the underlying connection can be suspended (creating a Continuation) or handle the connection synchronously.
void	onStateChange(AtmosphereResourceEvent event)	This method is invoked when the Broadcaster executes a broadcast operation.

Method Detail

onRequest

void onRequest(AtmosphereResource resource)
        throws java.io.IOException

When a client sends 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 requests for which HTTP method is a GET and use the POST method to send data to the server, without marking the connection as asynchronous.

Parameters:

resource - an AtmosphereResource

Throws:

java.io.IOException

onStateChange

void onStateChange(AtmosphereResourceEvent event)
            throws java.io.IOException

This method is invoked when the Broadcaster executes a broadcast operation. 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.

Parameters:

event - an AtmosphereResourceEvent

Throws:

java.io.IOException

destroy

void destroy()

Destroy this handler