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
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description void
close()
Stops the event stream.void
send(java.lang.String message)
Sends a message (without an ID or event type)void
send(java.lang.String message, java.lang.String event)
Sends a message with an event type (without an ID).void
send(java.lang.String message, java.lang.String event, java.lang.String eventID)
Sends a message with an event type and ID.void
sendComment(java.lang.String comment)
Sends a comment to the client.void
setClientReconnectTime(long timeToWait, java.util.concurrent.TimeUnit unit)
Sends a message to the client instructing it to reconnect after the given time period in case of any disconnection (including callingclose()
from the server).static SsePublisher
start(MuRequest request, MuResponse response)
Creates a new Server-Sent Events publisher.
-
-
-
Method Detail
-
send
void send(java.lang.String message) throws java.io.IOException
Sends a message (without an ID or event type)- Parameters:
message
- The message to send- Throws:
java.io.IOException
- Thrown if there is an error writing to the client, for example if the user has closed their browser.
-
send
void send(java.lang.String message, java.lang.String event) throws java.io.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 sendevent
- An event name. Ifnull
is specified, clients default to a message type ofmessage
- Throws:
java.io.IOException
- Thrown if there is an error writing to the client, for example if the user has closed their browser.
-
send
void send(java.lang.String message, java.lang.String event, java.lang.String eventID) throws java.io.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 sendevent
- An event name. Ifnull
is specified, clients default to a message type ofmessage
eventID
- An identifier for the message. If set, and the browser reconnects, then the last event ID will be sent by the browser in theLast-Event-ID
request header.- Throws:
java.io.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(java.lang.String comment) throws java.io.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:
java.io.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, java.util.concurrent.TimeUnit unit) throws java.io.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:
java.io.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 MuRequestresponse
- The current MuResponse- Returns:
- Returns a publisher that can be used to send messages to the client.
-
-