co.paralleluniverse.comsat.webactors

Class SSE

java.lang.Object

co.paralleluniverse.comsat.webactors.SSE

public final class SSE
extends Object

Utility classes for SSE (Server-Sent Events). To start an SSE stream in response to an HttpRequest, do the following:

request.getFrom().send(new HttpResponse(self(), SSE.startSSE(request)));

This will result in a HttpStreamOpened message being sent to the web actor from a newly created actor that represents the SSE connection. To send SSE events, simply send WebDataMessages to that actor:

// send events
sseActor.send(new WebDataMessage(self(), SSE.event("this is an SSE event!")));

You might want to consider wrapping the actor sending HttpStreamOpened with a mapping channel to transform a specialized message class into WebDataMessage using the methods in this class.

For a good tutorial on SSE, please see: Stream Updates with Server-Sent Events, by Eric Bidelman

Method Summary

Methods

Modifier and Type	Method and Description
static String	event(long id, String payload) Encodes a given payload and id as an SSE event message.
static String	event(long id, String eventType, String payload) Encodes a given payload as an SSE event message.
static String	event(String payload) Encodes a given payload as an SSE event message.
static String	event(String eventType, String payload) Encodes a given payload as an SSE event message.
static long	getLastEventId(HttpRequest request) Returns the SSE last-event-id value from the request (the Last-Event-ID header).
static String	reconnectTimeout(long reconnectTimeout) Encodes an indication to the client to attempt a reconnect if the connection is closed within the given time.
static HttpResponse.Builder	startSSE(HttpRequest request) This method returns a new HttpResponse with its content type and character encoding set in compliance with to the SSE spec, and an empty body.
static HttpResponse.Builder	startSSE(HttpRequest request, long reconnectTimeout) This method returns a new HttpResponse with its content type and character encoding set in compliance with to the SSE spec, and a body encoding a reconnection timeout indication.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

startSSE

public static HttpResponse.Builder startSSE(HttpRequest request)

This method returns a new HttpResponse with its content type and character encoding set in compliance with to the SSE spec, and an empty body.

Parameters:

request - the HttpRequest in response to which we wish to start an SSE stream.

Returns:

an HttpResponse.Builder (which can have other metadata, such as headers or cookies added to).

startSSE

public static HttpResponse.Builder startSSE(HttpRequest request,
                            long reconnectTimeout)

This method returns a new HttpResponse with its content type and character encoding set in compliance with to the SSE spec, and a body encoding a reconnection timeout indication.

Parameters:

request - the HttpRequest in response to which we wish to start an SSE stream.

reconnectTimeout - the amount of time, in milliseconds, the client should wait before attempting to reconnect after the connection has closed (will be encoded in the message body as retry: ...)

Returns:

an HttpResponse.Builder (which can have other metadata, such as headers or cookies added to).

getLastEventId

public static long getLastEventId(HttpRequest request)

Returns the SSE last-event-id value from the request (the Last-Event-ID header).

Parameters:

request - the request

Returns:

the SSE last-event-id value from the request, or -1 if not specified.

event

public static String event(long id,
           String eventType,
           String payload)

Encodes a given payload as an SSE event message. The returned value can be used as the body of a WebDataMessage.

Parameters:

id - the SSE event id (will be encoded in the message as id: ...)

eventType - the name of the type of the event (will be encoded in the message as event: ...)

payload - the message payload (will be encoded in the message as data: ...)

Returns:

the payload encoded as an SSE event

event

public static String event(String eventType,
           String payload)

Encodes a given payload as an SSE event message. The returned value can be used as the body of a WebDataMessage.

Parameters:

eventType - the name of the type of the event (will be encoded in the message as event: ...)

payload - the message payload (will be encoded in the message as data: ...)

Returns:

the payload encoded as an SSE event

event

public static String event(long id,
           String payload)

Encodes a given payload and id as an SSE event message. The returned value can be used as the body of a WebDataMessage.

Parameters:

id - the SSE event id (will be encoded in the message as id: ...)

payload - the message payload (will be encoded in the message as data: ...)

Returns:

the id and payload encoded as an SSE event

event

public static String event(String payload)

Encodes a given payload as an SSE event message. The returned value can be used as the body of a WebDataMessage.

Parameters:

payload - the message payload the message payload (will be encoded in the message as data: ...)

Returns:

the payload encoded as an SSE event

reconnectTimeout

public static String reconnectTimeout(long reconnectTimeout)

Encodes an indication to the client to attempt a reconnect if the connection is closed within the given time. This string may be concatenated ahead of a string encoding an SSE event, like so: reconnectTimeout(t) + event(x)).

Parameters:

reconnectTimeout - the amount of time, in milliseconds, the client should wait before attempting to reconnect after the connection has closed (will be encoded in the message as retry: ...)

Returns:

a string encoding the reconnection timeout indication