Using Browser Push in Grails

browser push is the collective term for techniques that allow a server to send asynchronous data updates in near real time to a browser. this article provides an overview of browser push and then provides a sample of grails usage by extending the example project from the ‘ using jms in grails ‘ article in the june 2011 edition to send event-driven updates to the browser.

this article originally appeared in the july 2011 edition of groovymag .

when do you need real time data?

there are many application scenarios where the user requires information to be delivered in near real time. some examples from projects i’ve worked on:

• emergency services control room systems
• price information in a swaps trading platform
• call centre operators

now some of these may be better suited to a desktop client (e.g. griffon) where you can receive jms directly. however for this article we’ll assume the use of a browser-based application with javascript client side event handling.

how does browser push work?

there are a number of different techniques used for getting data to the browser in near real time.

polling

firstly this isn’t really push, but some systems just poll the server frequently e.g. every second. this has the advantage of working with every browser and server combination. as figure 1 illustrates, there can be some lag before the server event reaches the client depending on the polling frequency; there may also be some requests that are pure overhead. however polling might be more efficient in some scenarios where there are a high volume of frequent updates.

figure 1: polling request-response

long polling

this isn’t true push but is a good substitute. the server won’t respond to a request unless it has data for the client. upon receipt of data, or a timeout, the client will make a new request.

figure 2 illustrates the request-response behaviour, and when server events reach the client (including in the event of a timeout).

figure 2: long polling

streaming

in this case the server leaves the response open, meaning the browser stays in the page loading state and can receive updates (figure 3). this approach may be achieved by hidden iframes, multipart responses to xmlhttprequest etc. but is often vulnerable to timeouts and inconsistent support between browsers and proxy servers.

figure 3: http streaming

html5

the html5 specification includes two mechanisms: server sent events and websockets.

server sent events has a javascript api called eventsource and works over traditional http. server sent events open a unidirectional channel from server to client. the main difference between server-sent events and long polling is that sses are handled directly by the browser and the user simply has to listen for messages.

websockets incorporate full-duplex communication channels so they have been receiving more attention (though this isn’t always good as some browsers have now disabled websockets by default due to security concerns). figure 4 illustrates the request-response behaviour for websockets.

figure 4: websocket event propagation

what about comet / reverse ajax?

comet is used as an umbrella term covering long polling and streaming.

is that the same as continuations?

continuations was the name used by the original jetty comet implementation; the servlet 3.0 specification added asynchronous support that brings a standard api to consolidate the fragmented native container implementations.

and the bayeux pub/sub protocol?

this was created by the dojo foundation (with input from jetty developers) and is named after the bayeux tapestry which contains a comet (believed to be halley’s). it is a specification defining a publish/subscribe mechanism for asynchronous messages primarily over http that is independent of any implementation programming language and separates the transport negotiation from the messaging.

what are the core challenges?

the main problem for browser push stems from the 2 connection limit in the http/1.1 specification (rfc2616) for an http client communicating with a specific http server.

what grails plugins are available?

the two main plugins are atmosphere and cometd which utilize the java projects of the same names. at the time of writing the atmosphere plugin was more mature and most recently updated (version 0.4.0 supports grails 1.3.5+ vs. cometd 0.2.2 supporting grails 1.2.1+) – so this is used for the sample project.

note that cometd is built on top of the atmosphere project adding bayeux protocol support.

atmosphere fundamentals

atmosphere describes itself as a portable ajaxpush/comet and websocket framework. it has a jquery plugin client component and provides server components that can run inside any container removing container-specific implementation dependencies from you application. atmosphere can also be clustered (e.g. using jgroups) but that is beyond the scope of this article.

atmosphere has a number of modules available, but within grails we’ll be utilizing the core atmosphere runtime. the main component of this module is an atmospherehandler which can be used to suspend, resume and broadcast. the action of broadcasting involves distributing an event to one or many suspended responses. the suspended response can then decide to discard the event or send it back to the browser.

warning: you should understand whether atmosphere will block a thread per suspended connection for your target container due to potential performance / capacity implications.

atmosphere jquery plugin

the atmosphere jquery plugin provides cross-browser support for the ability to subscribe to and publish messages from client-side javascript. it has support for different transport modes, chiefly websocket, long-polling, streaming and polling; where websocket effectively works as an ‘auto-detect’ mode and falls back appropriately if the browser doesn’t yet support websockets – this means that atmosphere will choose the best available mode for your browser.

whilst it provides publish / subscribe functionality, we’ll only focus on the latter.

grails atmosphere plugin

the grails atmosphere plugin provides a number of key features:

• ability to write handlers using grails services
• automatic generation of configuration files
• taglib for including javascript resources
• stratosphereservlet extension to the atmosphereservlet to register statically configured handlers

practical example overview

in the june issue we built an application that queued messages for persistence. when a user created a new message, it was placed on a jms queue and the user was redirected to the list view with a flash message to inform them their message was queued for persistence.

whilst this was functional, it required the user to refresh their browser to update the list. for usability, it would be much nicer if there was an event-driven update of the page after a message has been created – that is our goal for this exercise.

figure 5 shows the data flow of the revised sample project using hohpe eip notation.

figure 5: example data flow

as usual the full source code for the sample grails project is available on github, the code accompanying this article is at https://github.com/rbramley/groovymagjms

controller

this is only undergoing a minor change to remove the flash.message from the save operation.

messagestoreservice

a jms topic will be used for sending an asynchronous event from the messagestoreservice when a message is persisted. the message sending requires def jmsservice so that the spring container auto-wiring can inject our dependency.

we’ll publish the event to the ‘msgevent’ topic using jmsservice.send(topic:'msgevent',[id:messageinstance.id, body:messageinstance.body]) once the message instance is persisted.

we’ll also introduce a 2 second sleep prior to persistence to ensure that the message is only delivered via the ‘reverse ajax’ route.

atmosphereservice

this implements our handler so that we can suspend the connection (listing 1) and subsequently resume it having invoked the callback with the data (listing 2).

as listing 3 shows, the service is also message-driven by subscribing to the jms ‘msgevent’ topic, converting the map message to json and broadcasting it to atmosphere.

critically, the service declares an atmosphere mapping which is also used by the client-side javascript:

static atmosphere = [mapping:'/atmosphere/messages']

def onrequest = { event ->
   // we should only have get requests here
   log.info "onrequest, method: ${event.request.method}"
 
   // mark this connection as suspended.
   event.suspend()
}

listing 1: suspending a request

def onstatechange = { event ->
  if (event.message) {
    log.info "onstatechange, message: ${event.message}"
 
    if (event.issuspended()) {
      event.resource.response.writer.with {
        write "parent.callback('${event.message}');"
        flush()
       }
      event.resume()
    }
  }
}

listing 2: resuming a connection

static exposes = ['jms']
 
@subscriber(topic='msgevent')
def onevent(msg) {
  def payload = msg
  if(msg instanceof map) {
    // convert map messages to json
    payload = msg.encodeasjson()
  }
 
  // broadcast to the atmosphere
  broadcaster['/atmosphere/messages'].broadcast(payload)
 
  return null
}

listing 3: topic message handling

front end

the front end for the sample is provided by a generated list view, and the head element of this file has been augmented with the addition of the atmosphere plugin resources taglib <atmosphere:resources/>.

listing 4 shows the javascript (using jquery) to register the subscription to the atmosphere handler along with a callback function. note that the uri would normally be derived from the javascript window.location but that has been omitted for simplicity.

var location = 'http://localhost:8080/groovymagjms/atmosphere/messages';
$.atmosphere.subscribe(location, callback, $.atmosphere.request = {transport: 'websocket'});

listing 4: atmosphere jquery plugin subscription

listing 5 shows the callback function that will parse the json of a successful 200 response and append a new row to the message list table (the html has been kept very simplistic for clarity).
the callback also handles the case where the json parsing fails as atmosphere sends ‘junk’ data to the server to establish the connection.

function callback(response) {
  if (response.status == 200) {
    var data = response.responsebody;
    if (data.length > 0) {
      try {
        var msgobj = jquery.parsejson(data);
        if (msgobj.id > 0) {
          var row = '<tr><td>' + msgobj.id + '</td><td>' + msgobj.body + '</td><td></td></tr>'
          $('tbody').append(row);
        }
      } catch (e) {
        // atmosphere sends commented out data to webkit based browsers
      }
    }
  }
}

listing 5: callback code

listings 4 and 5 are contained with a <script type="text/javascript"> block and a jquery $(document).ready(function(){ ... });

configuration

the sample project hasn’t customized the grails-app/conf/atmosphereconfig.groovy – you can use this file to pass init-param options to the atmosphereservlet (see http://atmosphere.java.net/nonav/apidocs/org/atmosphere/cpr/atmosphereservlet.html ).

the grails atmosphere plugin also creates web-app/meta-inf/context.xml and web-app/web-inf/context.xml – these files are included for portability across servlet containers (e.g. tomcat uses the meta-inf/context.xml and jboss uses web-inf/context.xml).

the plugin also creates some additional xml files and establishes a sitemesh exclusion at compilation time – this is documented on the plugin wiki: https://bitbucket.org/bgoetzmann/grails-atmosphere-plugin/wiki/home

in action

we’ll start the application using grails run-app and when then go to the message list at http://localhost:8080/groovymagjms/message/list we’ll see an empty list (figure 6).

figure 6: empty message list

figure 6: empty message list

selecting the ‘new message’ menu option from figure 6, will take us to the create message form as shown in figure 7. if we enter a body value and the click on ‘create’, we will be redirected to the message list (initially empty as per figure 6 and subsequently updated as per figure 8).

figure 7: create message form

figure 8: dynamically updated message list

if we choose to create another message, the message list when dynamically updated will appear as per figure 9. in this case, the first record was retrieved from the database (as distinguished by the hyperlinked id and the presence of the date created value).

figure 9: second pass message list update

as figure 10 shows, you can also try this with multiple browsers open on http://localhost:8080/groovymagjms/message/list and observe the subscribers receiving their updates.

figure 10: multiple consumers using different browsers

as shown in figure 11, if you modify the transport setting in listing 4 from ‘websocket’ to ‘long-polling’ and try it in chrome you will see the page appears to be endlessly loading, however ie 8 now behaves correctly.

figure 11: long-polling browsers

this experiment leads us to the revised version of the client subscription code from listing 4. listing 6 now specifies the transport as ‘websocket’ with a fallback transport of ‘long-polling’.

var location = 'http://localhost:8080/groovymagjms/atmosphere/messages';
$.atmosphere.subscribe(location, callback, $.atmosphere.request = {transport: 'websocket', fallbacktransport: 'long-polling'});

listing 6: client-side subscription with fallback

summary

we’ve seen why we might need browser push, how it works, and how to implement it in grails using one of the available plugins and client-side javascript.

however note that this example hasn’t tried to tackle authentication as this is typically dependent upon the security framework being utilized. as a next step for those that have authentication requirements, the cometd wiki provides a how-to at http://cometd.org/documentation/2.x/howtos/authentication

from http://leanjavaengineering.wordpress.com/2011/11/18/grails-push/