io.muserver

Interface SsePublisher

public interface SsePublisher

An interface for sending Server-Sent Events (SSE) to a client.

The following example creates a publisher and publishes 10 messages to it from another thread:

 server = httpsServer()
     .addHandler(Method.GET, "/streamer", (request, response, pathParams) -> {
         SsePublisher ssePublisher = SsePublisher.start(request, response);
         new Thread(() -> {
             try {
                 for (int i = 0; i < 100; i++) {
                     ssePublisher.send("This is message " + i);
                     Thread.sleep(1000);
                 }
             } catch (Exception e) {
                 // the user has probably disconnected; stop publishing
             } finally {
                 ssePublisher.close();
             }
         }).start();

     })
     .start();
 

Method Summary

Modifier and Type	Method and Description
void	close() Stops the event stream.
void	send(String message) Sends a message (without an ID or event type)
void	send(String message, String event) Sends a message with an event type (without an ID).
void	send(String message, String event, String eventID) Sends a message with an event type and ID.
void	sendComment(String comment) Sends a comment to the client.
void	setClientReconnectTime(long timeToWait, TimeUnit unit) Sends a message to the client instructing it to reconnect after the given time period in case of any disconnection (including calling close() from the server).
static SsePublisher	start(MuRequest request, MuResponse response) Creates a new Server-Sent Events publisher.

Method Detail

send

void send(String message)
   throws IOException

Sends a message (without an ID or event type)

Parameters:

message - The message to send

Throws:

IOException - Thrown if there is an error writing to the client, for example if the user has closed their browser.

send

void send(String message,
          String event)
   throws IOException

Sends a message with an event type (without an ID).

Clients can use the event type to listen to different types of events, for example if the event type is pricechange the the following JavaScript can be used:

     var source = new EventSource('/streamer');
     source.addEventListener('pricechange', e => console.log(e.data));
 

Parameters:

message - The message to send

event - An event name. If null is specified, clients default to a message type of message

Throws:

IOException - Thrown if there is an error writing to the client, for example if the user has closed their browser.

send

void send(String message,
          String event,
          String eventID)
   throws IOException

Sends a message with an event type and ID.

Clients can use the event type to listen to different types of events, for example if the event type is pricechange the the following JavaScript can be used:

     var source = new EventSource('/streamer');
     source.addEventListener('pricechange', e => console.log(e.data));
 

Parameters:

message - The message to send

event - An event name. If null is specified, clients default to a message type of message

eventID - An identifier for the message. If set, and the browser reconnects, then the last event ID will be sent by the browser in the Last-Event-ID request header.

Throws:

IOException - Thrown if there is an error writing to the client, for example if the user has closed their browser.

close

void close()

Stops the event stream.

Warning: most clients will reconnect several seconds after this message is called. To prevent that happening, close the stream from the client or on the next request return a 204 No Content to the client.

sendComment

void sendComment(String comment)
          throws IOException

Sends a comment to the client. Clients will ignore this, however it can be used as a way to keep the connection alive.

Parameters:

comment - A single-line string to send as a comment.

Throws:

IOException - Thrown if there is an error writing to the client, for example if the user has closed their browser.

setClientReconnectTime

void setClientReconnectTime(long timeToWait,
                            TimeUnit unit)
                     throws IOException

Sends a message to the client instructing it to reconnect after the given time period in case of any disconnection (including calling close() from the server). A common default (controlled by the client) is several seconds.

Note: clients could ignore this value.

Parameters:

timeToWait - The time the client should wait before attempting to reconnect in case of any disconnection.

unit - The unit of time.

Throws:

IOException - Thrown if there is an error writing to the client, for example if the user has closed their browser.

start

static SsePublisher start(MuRequest request,
                          MuResponse response)

Creates a new Server-Sent Events publisher. This is designed by be called from within a MuHandler.

This will set the content type of the response to text/event-stream and disable caching.

The request will also switch to async mode, which means you can use the returned publisher in another thread.

IMPORTANT: The close() method must be called when publishing is complete.

Parameters:

request - The current MuRequest

response - The current MuResponse

Returns:

Returns a publisher that can be used to send messages to the client.