It is really simple to add clustering support to an Atmosphere's Comet based application, and deploy it inside any Servlet Container supporting Servlet 3.0, Comet or not. You just have to decide which group technology you want to use, thanks to Atmosphere Plug in: Shoal or JGroups!

First, if you want to get started with Atmosphere, I recommend to take a look at atmosphere-cpr (POJO based) and atmosphere-core (Annotations/REST based) introduction first. Let's start with the Chat sample written against atmosphere-cpr. The AtmosphereHandler#onEvent looks like

  if (req.getMethod().equalsIgnoreCase("GET")) {
              event.suspend();
             Broadcaster bc = event.getBroadcaster();
             bc.getBroadcasterConfig().addFilter(new XSSHtmlFilter());
              bc.broadcast(event.getAtmosphereConfig().getWebServerName()
                      + "**has suspended a connection from "
                      + req.getRemoteAddr());
          } else if (req.getMethod().equalsIgnoreCase("POST")) {
              res.setCharacterEncoding("UTF-8");
              String action = req.getParameterValues("action")[0];
              String name = req.getParameterValues("name")[0];
              
             if ("login".equals(action)) {
                 req.getSession().setAttribute("name", name);
                 event.getBroadcaster().broadcast("System Message from "
                         + event.getAtmosphereConfig().getWebServerName() + "**" + name + " has joined.");
                 res.getWriter().write("success");
                 res.getWriter().flush();
             } else if ("post".equals(action)) {
                 String message = req.getParameterValues("message")[0];
                 event.getBroadcaster().broadcast(name + "**" + message);
                 res.getWriter().write("success");
                 res.getWriter().flush();
             } else {
                 res.setStatus(422);
                 
                 res.getWriter().write("success");
                 res.getWriter().flush();
             }   
         }   
         return event;
     }

One nice feature of Atmosphere is the support of Broadcaster. Broadcaster are used to broadcast messages between suspended responses, e.g. for the chat sample, every time a new message is entered by a user, we use a Broadcaster to broadcast that message to all other users. Broadcaster supports BroadcastFilter, which are really useful for manipulating messages before they get written by the set of suspended connections. If you look at line 80/81 above, we configure the Broadcaster with the XSSHtmlFilter to prevent a malicious chatter to send us Javascript as message, and push that script back to other user. Indeed, BroadcastFilters are quite useful when it's time to filter/transform/agreggate messages or to broadcast messages to other components like EJB, JMS topics/queues...or cluster!. The good news is Atmosphere supports two clusters technology: JGroups and Shoal. To add cluster support to the above Chat application, all we need to do is:

 res.setContentType("text/html");
          res.addHeader("Cache-Control", "private");
          res.addHeader("Pragma", "no-cache");
  
          if (req.getMethod().equalsIgnoreCase("GET")) {
              event.suspend();
              Broadcaster bc = event.getBroadcaster();
              bc.getBroadcasterConfig().addFilter(
                  new JGroupsFilter(bc, event.getAtmosphereConfig().getWebServerName()));
              bc.getBroadcasterConfig().addFilter(new XSSHtmlFilter());

Just need to add the XXXFilter, where xxx is the group technology you want to use: ShoalFilter or JGroupsFilter, and that's it! Just adding line 91 makes your atmosphere-cpr application clustered and any invocation of Broadcaster.broadcast will reach all AtmosphereHandler instance in the same cluster.

HUH that was too complicated :-)! Let's now use atmosphere-core's support for annotations. The Atmosphere's REST based Chat sample looks like:

 @Path("/chat")
  public class ResourceChat {
  
      @Suspend()
      @GET
      @Produces("text/html")
      public String suspend() {
          return "";
      }           
      
      @Broadcast
      @Consumes("application/x-www-form-urlencoded")
      @POST
      @Produces("text/html")
      @BroadcastFilter({XSSHtmlFilter.class,JsonpFilter.class})
      public String publishMessage(MultivaluedMap form) {
          String action = form.getFirst("action");
          String name = form.getFirst("name");
          
          if ("login".equals(action)) {
              return ("System Message" + "__" + name + " has joined.");
          } else if ("post".equals(action)) { 
              return name + "__" + form.getFirst("message");
          } else {
              throw new WebApplicationException(422);
          }   
      }   
  } 

In order to add clustering support, we just need to annotate the method that broadcast message, e.g:

@Broadcast
      @Consumes("application/x-www-form-urlencoded")
      @POST
      @Produces("text/html")
      @BroadcastFilter({XSSHtmlFilter.class,JsonpFilter.class})
      @Cluster(
          name="chat",
          value=ShoalFilter.class
      )
      public String publishMessage(MultivaluedMap form) {
         String action = form.getFirst("action");
          String name = form.getFirst("name");
          
          if ("login".equals(action)) {
              return ("System Message" + "__" + name + " has joined.");
          } else if ("post".equals(action)) {
              return name + "__" + form.getFirst("message");
          } else {
              throw new WebApplicationException(422);
          }
      }
  }

That's it!. By just annotating the proper method, Atmosphere will makes sure to properly configure the Shoal/JGroups so every broadcast will be shared inside the cluster.

For any questions or to download the above sample, go to our main site and use our Nabble forum (no subscription needed) or follow us on Twitter and tweet your questions there!

From http://weblogs.java.net/blog/jfarcand