Understanding AtmosphereResource

This document describes the AtmosphereResource concept. If your application uses atmosphere-jersey, you can skip this document (but you can always inject AtmosphereResource in Jersey)

AtmosphereResource concept

The AtmosphereResource is the central concept of the Atmosphere Framework. An AtmosphereResource represents a remote connection. You can also see an AtmosphereResource as a communication channel between a browser and an application. An application uses an AtmosphereResource to handle the life cycle of the connection. For example, to tell the Atmosphere Framework to not close its connection and leave it open for later use, call

    atmosphereResource.suspend();

You can read information about the request and populate the response from an AtmosphereResource. As simple as:

   AtmosphereRequest request = atmosphereResource.getRequest();
   AtmosphereResponse response = atmosphereResource.getResponse();

If you are familiar with the Servlet technology, AtmosphereRequest/AtmosphereResponse can be seen as HttpServletRequest/Response. You can read/write using those objects. You can write messages (or events) using the AtmosphereResponse or directly using the AtmosphereResource:

  atmosphereResource.write("hello").write("world");

An AtmosphereResource gets delivered to an Atmosphere components, which can be

• AtmosphereHandler
• Meteor
• Service annotated class ManagedService, MeteorService, WebSocketHandlerService, AtmospherehandlerService and AtmosphereService
• WebSocketHandler
• Jersey Resource

An AtmosphereResource is created every time a new connection is made, including when a WebSocket messages is received.

An AtmosphereResource is always associated with one or several channels of communication (read Broadcaster). When created, one or more Broadcasters are associated with an AtmosphereResource and can be retrieved using

  Broadcaster b = atmosphereResource.getBroadcaster();
  atmosphereResource.setBroadcaster(broadcasterX); // returned when getBroadcaster() gets called.
  atmosphereResource.addBroadcaster(broadcasterY); // returned when broadcasters() gets called.

You can see a Broadcaster as a "topic" or "channel". You can subscribe to a channel, or Broadcaster, by adding an AtmosphereResource to it. You simply do:

  broadcaster.addAtmosphereResource(atmosphereResource);

Once added, messages or events will be delivered to an AtmosphereResource every time Broadcaster.broadcast gets invoked. An AtmosphereResource is associated with an AtmosphereResourceEvent, which always contains the last broadcasted events. You can get it by doing

  Object message = atmosphereResource.getAtmosphereResourceEvent().getMessage();

If you use annotation, the message will be directly delivered to your annotated method.

This allows applications to write the event back to the remote client. For example, a remote browser can subscribe to two broadcasters:

 @Inject
 private BroadcasterFactory factory;

 ...

 factory.lookup("Java topic").addAtmosphereResource(atmosphereResource);
 factory.lookup("Scala topic").addAtmosphereResource(atmosphereResource);

Now every time a new event or message gets broadcasted, it will be sent back to the browser for further processing.

You can attach event listeners to an AtmosphereResource and get notified every time the AtmosphereResource state is about to change. As simple as

  atmosphereResource.addEventListener(new AtmosphereResourceEventListenerAdapter() ...);

AtmosphereResource are closely tied with AtmosphereHandler. Read this document if you want to learn more about it.

AtmosphereResourceFactory

An AtmosphereResource has a unique identifier that can be retrieved using

  String uuid = atmosphereResource.uuid();

Since, by default, an AtmosphereResource is always associated with one or several Broadcasters, you can store that unique id and later retrieve its associated AtmosphereResource using the AtmosphereResourceFactory:

  AtmosphereResource r = atmosphereResourceFactory.find(uuid);

The AtmosphereResourceFactory will look inside all available Broadcasters. You can also remove an AtmosphereResource from all Broadcasters by doing

   AtmosphereResource r = atmosphereResourceFactory.remove(uuid);

That means no more events will be written back to the client, unless you use the AtmosphereResource.write API directly.

Retrieving the original AtmosphereResource with WebSocket

To support WebSocket the same way as other transport, Atmosphere, by default, creates an AtmosphereResource for the handshake operation, and new AtmosphereResource every time a new websocket message is received. In case your application needs to retrieve the original one, e.g the one used for the handshake, just use the following attribute from any AtmosphereRequest:

   String uuid = (String)request.getAttribute(ApplicationConfig.SUSPENDED_ATMOSPHERE_RESOURCE_UUID);
   AtmosphereResource resource = atmosphereResourceFactory.find(uuid);