SSE Method

Removed in 1.6.0. Spring 4.2 has built-in support for Server-sent events

Since 1.2.2

Server

Server-Sent Event methods are an alternative to POLL methods. They are called from the EventSource object from Javascript.

A Server-Sent Event method is annotated with @ExtDirectMethod(value = ExtDirectMethodType.SSE). If a SSE method needs to support parameters they have to be annotated with @RequestParam. The value attribute must match the name of the request parameter and is optional if the code is compiled with debug informations. If there is no value attribute Spring tries to read the name of the parameter from the debug informations.

A SSE method can either return an instance of SSEvent or any object which will be converted to a String with the object's toString() method.

@Service
public class Poll {

    @ExtDirectMethod(value = ExtDirectMethodType.SSE)
    public SSEvent sse1(@RequestParam int id) {
        SSEvent event = new SSEvent();
        event.setRetry(10000);
        event.setData("some data");
        return event;
    }

    @ExtDirectMethod(value = ExtDirectMethodType.SSE)
    public String sse2() {
        return "some data";
    }	
}

The annotation @RequestParam works the same way as in Spring MVC.

The signature of a SSE method can also contain server object parameters (see also Simple method).

@ExtDirectMethod(value = ExtDirectMethodType.SSE)
public SSEvent sse1(HttpServletResponse response, HttpServletRequest request,
                       HttpSession session, Locale locale, 
                       @RequestParam(value = "id") int id) {
    ...
}

The parameters may appear in any order and the name of the parameter is irrelevant.

Http Streaming (since 1.3.0)

Events can be written in a streaming fashion with the help of the class SSEWriter. Add this class to the method as a parameter and write events with the write method. There are two write methods available. The first one takes a SSEvent and the second any object as a parameter. The object will be converted to a string with the object's toString() method and then wrapped in a SSEvent (data property) by the library.

 @ExtDirectMethod(ExtDirectMethodType.SSE)
 public void sse(SSEWriter sseWriter) {
   SSEvent event = new SSEvent();
   event.set....	    
   sseWriter.write(event);
   //do something else or wait for something or ...
   sseWriter.write("a string");
   sseWriter.write(2);
   //...
 }

Such a method can return nothing, a SSEvent or any Object. If the method returns anything the library writes it into the output stream and then closes the response.

Client

The client uses the EventSource object to communicate with a SSE method.

api.js will create a variable for each SSE method that contains the URL for the EventSource constructor function. By default these variables have the form Ext.app.SSE.name_of_the_bean.name_of_the_method. The example above creates these two variables: Ext.app.SSE.poll.sse1 and Ext.app.SSE.poll.sse2

The code for calling the sse1 method then looks like this:

var es = new EventSource(Ext.app.SSE.poll.sse1);
es.addEventListener('message', sse1MessageHandler, false);

function sse1MessageHandler(event) {
    //...
}

Polyfill

Not all browsers support Server-Sent Events. See supported browsers on CanIuse.com. Yaffle/EventSource is a pollyfill that provide implementation of the EventSource object. This way SSE should work in most of the browsers.

IE6 until IE9 need some additional special handling. First they need this two headers to be sent from the server.

response.setHeader("Cache-Control", "no-cache");
response.setHeader("Access-Control-Allow-Origin", "*");

And the server has to send 2 KB of some data as the first message. One way to do that is sending a comment message with 2048 spaces.

For an example see the sse method of the Poll class from the extdirectspring-demo project.

More informations

http://www.w3.org/TR/eventsource/
https://developer.mozilla.org/en-US/docs/Server-sent_events/EventSource
https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events
http://www.html5rocks.com/en/tutorials/eventsource/basics/