Atmosphere and JSF are good friends

Decision to write this long article was driven by PrimeFaces community. People have troubles to develop web applications with server push techniques. Even with Atmosphere - framework for building portable Comet and WebSocket based applications. Portable means it can run on Tomcat, JBoss, Jetty, GlassFish or any other application server which supports Servlet specification 2.5 or higher. If you want to be independent on underlying server and don't want to have headaches during implementation, use Atmosphere framework. It simplifies development and can be easy integrated into JSF or any other web frameworks (don't matter). I read Atmosphere doesn't play nice with JSF or similar. PrimeFaces had a special Athmosphere handler for JSF in 2.2.1. But that's all is not necessary. It doesn't matter what for a web framework you use - the intergration is the same. My intention is to show how to set up a bidirectional communication between client and server by using of Atmosphere. My open source project "Collaborative Online-Whiteboard" demonstrates that this approach works well for all three transport protocols - Long-Polling, Streaming and WebSocket. This is an academic web application built on top of the Raphaël / jQuery JavaScript libraries, Atmosphere framework and PrimeFaces. You can open two browser windows (browser should support WebSocket) and try to draw shapes, to input text, to paste image, icon, to remove, clone, move elements etc.

We need a little theory at first. For bidirectional communication we need to define a Topic at first (called sometimes "channel"). Users subscribe to the Topic and act as Subscribers to receive new data (called updates or messages as well). A subscriber acts at the same time as Publisher and can send data to all subscribers (broadcasting). Topic can be expressed by an unique URL - from the technical point of view. URL should be specified in such a manner that all bidirectional communication goes through AtmosphereServlet. JSF requests should go through FacesServlet. This is a very important decision and probably the reason why Atmosphere integration in various web frameworks like JSF and Struts sometimes fails. Bidirectional communication should be lightweight and doesn't run all JSF lifecycle phases! This can be achieved by proper servlet-mapping in web.xml. The picture below should demonstrate the architecture (example of my open source project).

For my use case I need messages in JSON format, but generally any data can be passed over bidirectional channel (XML, HTML). What is the Topic exactly? It depends on web application how you define the Topic. You can let user types it self (e.g. in chat applications) or make it predefined. In my application I equate Topic with Whiteboard-Id which is generated as UUID. Furthermore, I have introduced User-Id (= Publisher-Id) as well and called it Sender. Sender serves as identificator to filter Publisher out of all Subscribers. Publisher is normally not interested in self notification. I'm going to show using of Sender later. My Topic-URL follows this pattern

http://host:port/pubsub/{topic}/{sender}.topic

and looks like e.g. as

http://localhost:8080/pubsub/ea288b4c-f2d5-467f-8d6c-8d23d6ab5b11/e792f55e-2309-4770-9c48-de75354f395d.topic

I use Atmosphere with Jersey I think it's a better way than to write Atmosphere handlers or try to integrate MeteorServlet. Therefore, to start using of Atmosphere, you need a dependency to current Atmosphere and Jersey. Below is a dependency configuration for Maven users. Note: I cut logging off.

<dependency>
    <groupId>org.atmosphere</groupId>
    <artifactId>atmosphere-jersey</artifactId>
    <version>0.8-SNAPSHOT</version>
    <exclusions>
        <exclusion>
            <groupId>org.atmosphere</groupId>
            <artifactId>atmosphere-ping</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.apache.geronimo.specs</groupId>
    <artifactId>geronimo-servlet_3.0_spec</artifactId>
    <version>1.0</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>1.6.2</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-nop</artifactId>
    <version>1.6.2</version>
</dependency>

The next step is to add Atmosphere-jQuery plugin to the client side. This plugin can be downloaded from the Atmosphere's homepage. After placing jquery.atmosphere.js under webapp/resources/js you can include it with

<h:outputScript library="js" name="jquery.atmosphere.js" target="head"/>

Yes, I know that Atmosphere can load jquery.atmosphere.js from JAR file in classpath, but a manual include is better in JSF environment. Now we are able to subscribe to the Topic and communicate with the server on the client side. There are two calls: jQuery.atmosphere.subscribe() and jQuery.atmosphere.response.push(). To establish a bidirectional communication, you need to call subscribe(). You have to call this method just once when page has been loaded. After that the method push() is responsible for data publushing to all subsribers. In the mentioned above web application I have an JavaScript object WhiteboardDesigner which encapsulates the Atmosphere's subscribe() call in the method subscribePubSub().

// Subscribes to bidirectional channel.
// This method should be called once the web-application is ready to use.
this.subscribePubSub = function() {
  jQuery.atmosphere.subscribe(
    this.pubSubUrl,
    this.pubSubCallback,
    jQuery.atmosphere.request = {
      transport: this.pubSubTransport,
      maxRequest: 100000000
    });
    
    this.connectedEndpoint = jQuery.atmosphere.response;
}

The first parameter this.pubSubUrl is the shown above Topic-URL. The second parameter this.pubSubCallback is the callback function. The third parameter is the request configuration which keeps among other things transport protocol defined in this.pubSubTransport: "long-polling", "streaming" or "websocket". The last line assigns jQuery.atmosphere.response the variable this.connectedEndpoint which allows us data publishing via push(). So now when new data being received, the callback function this.pubSubUrl gets called. Inside of the callback we can extract received data from response object. You can get the idea how to handle broadcasted data from my example:

// Callback method defined in the subscribePubSub() method.
// This method is always called when new data (updates) are available on server side.
this.pubSubCallback = function(response) {
  if (response.transport != 'polling' &&
      response.state != 'connected' &&
      response.state != 'closed' && response.status == 200) {
      var data = response.responseBody;
      if (data.length > 0) {
        // convert to JavaScript object
        var jsData = JSON.parse(data);

       // get broadcasted data
        var action = jsData.action;
        var sentProps = (jsData.element != null ? jsData.element.properties : null);
        switch (action) {
          case "create" :
            ...
            break;
          case "update" :
            ...
            break;
          case "remove" :
            ...
            break;
          ... 
          default :
        }
        ...
      }
  }
}

To publish data over the Topic-URL you need to call this.connectedEndpoint.push(). this.connectedEndpoint is a defined above shortcut for jQuery.atmosphere.response. I call it in my example for created whiteboard elements as follows (just an example):

// Send changes to server when a new image was created.
this.sendChanges({
  "action": "create",
  "element": {
    "type": "Image",
    "properties": {
      "uuid": ...,
      "x": ...,
      "y": ...,
      "url": ...,
      "width": ...,
      "height": ...
    }
  }
});

// Send any changes on client side to the server.
this.sendChanges = function(jsObject) {
  // set timestamp
  var curDate = new Date();
  jsObject.timestamp = curDate.getTime() + curDate.getTimezoneOffset() * 60000;

  // set user
  jsObject.user = this.user;

  // set whiteboard Id
  jsObject.whiteboardId = this.whiteboardId;

  var outgoingMessage = JSON.stringify(jsObject);

  // send changes to all subscribed clients
  this.connectedEndpoint.push(this.pubSubUrl, null, jQuery.atmosphere.request = {data: 'message=' + outgoingMessage});
}

Passed JavaScript object jsObject is converted to JSON via JSON.stringify(jsObject) befor it's sending to the server.

What is necessary on the server side? Calls jQuery.atmosphere.subscribe() and jQuery.atmosphere.response.push() have to be caught on the server side. I use Jersey and its annotations to catch GET- / POST-requests for the certain Topic-URL in a declarative way. For that are responsible annotations @GET, @POST und @PATH. I have developed the class WhiteboardPubSub to catch the Topic-URL by means of @Path("/pubsub/{topic}/{sender}"). With @GET annotated method subscribe() catches the call jQuery.atmosphere.subscribe(). This method tells Atmosphere to suspend the current request until an event occurs. Topic (= Broadcaster) is also created in this method. Topic-String is extracted by the annotation @PathParam from the Topic-URL. You can imagine a Broadcaster as a queue. As soon as a new message lands in the queue all subscribers get notified (browsers which are connected with Topic get this message). With @POST annotated method publish() catches the call jQuery.atmosphere.response.push(). Client's data will be processed there and broadcasted to all subscribed connections. This occurs independent from the underlying transport protocol.

@Path("/pubsub/{topic}/{sender}")
@Produces("text/html;charset=ISO-8859-1")
public class WhiteboardPubSub
{
  private @PathParam("topic") Broadcaster topic;

  @GET
  public SuspendResponse<String> subscribe() {
    return new SuspendResponse.SuspendResponseBuilder<String>().
               broadcaster(topic).outputComments(true).build();
  }

  @POST
  @Broadcast
  public String publish(@FormParam("message") String message,
                      @PathParam("sender") String sender,
                      @Context AtmosphereResource resource) {
    // find current sender in all suspended resources and
    // remove it from the notification
    Collection<AtmosphereResource<?, ?>> ars = topic.getAtmosphereResources();
    if (ars == null) {
      return "";
    }

    Set<AtmosphereResource<?, ?>> arsSubset = new HashSet<AtmosphereResource<?, ?>>();
    HttpServletRequest curReq = null;
    for (AtmosphereResource ar : ars) {
      Object req = ar.getRequest();
      if (req instanceof HttpServletRequest) {
        String pathInfo = ((HttpServletRequest)req).getPathInfo();
        String resSender = pathInfo.substring(pathInfo.lastIndexOf('/') + 1);
        if (!sender.equals(resSender)) {
          arsSubset.add(ar);
        } else {
          curReq = (HttpServletRequest) req;
        }
      }
    }

    if (curReq == null) {
      curReq = (HttpServletRequest) resource.getRequest();
    }

    // process current message (JSON) and create a new one (JSON) for subscribed clients
    String newMessage = WhiteboardUtils.updateWhiteboardFromJson(curReq, message);

    // broadcast subscribed clients except sender
    topic.broadcast(newMessage, arsSubset);

    return "";
  }
}

In my case the method publish() looks for sender (= publisher of this message) among all subscribers and removes it from the notification. It looks a little bit complicated. In simple case you can write

@POST
@Broadcast
public Broadcastable publish(@FormParam("message") String message) {
  return new Broadcastable(message, "", topic);
}

and that's all! The last step is the mentioned above configuration in web.xml. *.jsf requests should be mapped to FacesServlet and *.topic requests to AtmosphereServlet. AtmosphereServlet can be configured comprehensively. Important configuration parameter is com.sun.jersey.config.property.packages. With this parameter you can tell Jersey where the annotated class is located (in my case WhiteboardPubSub). In my example Jersey scans the directory com.googlecode.whiteboard.pubsub.

<!-- Faces Servlet -->
<servlet>
  <servlet-name>Faces Servlet</servlet-name>
  <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
  <servlet-name>Faces Servlet</servlet-name>
  <url-pattern>*.jsf</url-pattern>
</servlet-mapping>

<!-- Atmosphere Servlet -->
<servlet>
  <description>AtmosphereServlet</description>
  <servlet-name>AtmosphereServlet</servlet-name>
  <servlet-class>org.atmosphere.cpr.AtmosphereServlet</servlet-class>
  <init-param>
    <param-name>com.sun.jersey.config.property.resourceConfigClass</param-name>
    <param-value>com.sun.jersey.api.core.PackagesResourceConfig</param-value>
  </init-param>
  <init-param>
    <param-name>com.sun.jersey.config.property.packages</param-name>
    <param-value>com.googlecode.whiteboard.pubsub</param-value>
  </init-param>
  <init-param>
    <param-name>org.atmosphere.useWebSocket</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>org.atmosphere.useNative</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>org.atmosphere.cpr.WebSocketProcessor</param-name>
    <param-value>org.atmosphere.cpr.HttpServletRequestWebSocketProcessor</param-value>
  </init-param>
  <init-param>
    <param-name>org.atmosphere.cpr.broadcastFilterClasses</param-name>
    <param-value>org.atmosphere.client.JavascriptClientFilter</param-value>
  </init-param>
  <load-on-startup>2</load-on-startup>
</servlet>
<servlet-mapping>
  <servlet-name>AtmosphereServlet</servlet-name>
  <url-pattern>*.topic</url-pattern>
</servlet-mapping>

Please check Atmosphere documentation and showcases for more information.

Summary: We have seen that few things are needed to establish the bidirectional comminication: Topic-URL, callback function for data receiving, subsribe() und push() methods on client side, an Jersey class on server side and configuration in web.xml to bind all parts together. JSF- und Atmosphere-requests should be treated separately. You maybe ask "but what is about the case if I need to access JSF stuff in Atmosphere-request?" For a simple case you can use this technique to access managed beans. If you want to have a fully access to all JSF stuff you should use this technique which allows accessing FacesContext somewhere from the outside.

P.S. Good news. Atmosphere's lead Jeanfrancois Arcand announced his intention to pursue the work on Atmosphere. He can invest more time now in his great framework.