io.muserver

Interface AsyncSsePublisher

public interface AsyncSsePublisher

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

This is preferrable to the (blocking) SsePublisher when you have a large number of subscribers as messages will be sent in a non-blocking fashion.

The usage is that same as for the synchronous version except that each send method returns a CompletionStage which contains completion or exception info.

See Also:

SsePublisher

Method Summary

Modifier and Type	Method and Description
void	close() Stops the event stream.
CompletionStage<?>	send(String message) Sends a message (without an ID or event type)
CompletionStage<?>	send(String message, String event) Sends a message with an event type (without an ID).
CompletionStage<?>	send(String message, String event, String eventID) Sends a message with an event type and ID.
CompletionStage<?>	sendComment(String comment) Sends a comment to the client.
CompletionStage<?>	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).
void	setResponseCompleteHandler(ResponseCompleteListener responseCompleteListener) Add a listener for when request processing is complete.
static AsyncSsePublisher	start(MuRequest request, MuResponse response) Creates a new Server-Sent Events publisher.

Method Detail

send

CompletionStage<?> send(String message)

Sends a message (without an ID or event type)

Parameters:

message - The message to send

Returns:

completion stage that completes when the event has been sent. If there is a problem during sending of an event, completion stage will be completed exceptionally.

send

CompletionStage<?> send(String message,
                        String event)

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

Returns:

completion stage that completes when the event has been sent. If there is a problem during sending of an event, completion stage will be completed exceptionally.

send

CompletionStage<?> send(String message,
                        String event,
                        String eventID)

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.

Returns:

completion stage that completes when the event has been sent. If there is a problem during sending of an event, completion stage will be completed exceptionally.

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

CompletionStage<?> sendComment(String comment)

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.

Returns:

completion stage that completes when the comment has been sent. If there is a problem during sending of an event, completion stage will be completed exceptionally.

setClientReconnectTime

CompletionStage<?> 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). 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.

Returns:

completion stage that completes when the event has been sent. If there is a problem during sending of an event, completion stage will be completed exceptionally.

setResponseCompleteHandler

void setResponseCompleteHandler(ResponseCompleteListener responseCompleteListener)

Add a listener for when request processing is complete. One use of this is to detect early client disconnects so that expensive operations can be cancelled.

Check ResponseInfo.completedSuccessfully() for false for SSE streams that did not complete.

Parameters:

responseCompleteListener - The handler to invoke when the request is complete.

start

static AsyncSsePublisher 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.