public interface SseEventSource
extends java.lang.AutoCloseable
incoming Server-Sent Events.
SSE event source instances of this class are thread safe. To build a new instance, you can use the
SseEventSource.target(endpoint) factory method to get a new event
source builder that can be further customised and eventually used to create a new SSE event source.
Once a SseEventSource is created, it can be used to open a connection to the associated
web target. After establishing the connection, the event source starts processing any incoming
inbound events. Whenever a new event is received, an Consumer<InboundSseEvent>#accept(InboundSseEvent) method is invoked on any registered event consumers.
The SseEventSource supports automated recuperation from a connection loss, including
negotiation of delivery of any missed events based on the last received SSE event id field value, provided
this field is set by the server and the negotiation facility is supported by the server. In case of a connection loss,
the last received SSE event id field value is sent in the
"Last-Event-ID" HTTP
request header as part of a new connection request sent to the SSE endpoint. Upon a receipt of such reconnect request, the SSE
endpoint that supports this negotiation facility is expected to replay all missed events. Note however, that this is a
best-effort mechanism which does not provide any guaranty that all events would be delivered without a loss. You should
therefore not rely on receiving every single event and design your client application code accordingly.
By default, when a connection to the SSE endpoint is lost, the event source will wait 500 ms
before attempting to reconnect to the SSE endpoint. The SSE endpoint can however control the client-side retry delay
by including a special retry field value in any sent event. JAX-RS SseEventSource tracks any
received SSE event retry field values set by the endpoint and adjusts the reconnect delay accordingly,
using the last received retry field value as the reconnect delay.
In addition to handling the standard connection loss failures, JAX-RS SseEventSource behaves differently to various
HTTP response status codes and headers:
"Content-Type" header of "text/event-stream": This is normal
operation. onEvent is invoked for each event. onComplete is invoked when there are no more
events. onError is invoked only if an unrecoverable error occurs during processing."Content-Type" header: This is an
error condition. onError is invoked.onComplete is invoked."Retry-After" header set to a valid value: This indicates
that the server is unavailable, but that the client should reconnect later. No consumers are invoked unless the client
event source is closed, prior to reconnecting (resulting in onComplete invocation). After the specified
delay, the client should automatically attempt to reconnect which will result in a new response."Retry-After" header: This is an error
condition. onError is invoked.onError is invoked.
In the case of an error condition response, the Throwable passed to the onError consumer
should be a WebApplicationException containing the invalid Response object.
Note that if, for any of the registered event consumers, an invocation of Consumer<InboundSseEvent>#accept(InboundSseEvent) method throws an exception, this is not an error condition.
Thus onError is not invoked and event processing is not stopped.
Users are encouraged to handle exceptions on their own as part of the event processing logic.
| Modifier and Type | Interface and Description |
|---|---|
static class |
SseEventSource.Builder
JAX-RS
SseEventSource builder class. |
| Modifier and Type | Method and Description |
|---|---|
default void |
close()
Close this event source.
|
boolean |
close(long timeout,
java.util.concurrent.TimeUnit unit)
Close this event source and wait for the internal event processing task to complete for up to the specified amount of
wait time.
|
boolean |
isOpen()
Check if this event source instance has already been
opened. |
void |
open()
Open the connection to the supplied SSE underlying
web target and start processing incoming
events. |
void |
register(java.util.function.Consumer<InboundSseEvent> onEvent)
Register a
InboundSseEvent consumer. |
void |
register(java.util.function.Consumer<InboundSseEvent> onEvent,
java.util.function.Consumer<java.lang.Throwable> onError)
Register
InboundSseEvent and Throwable consumers. |
void |
register(java.util.function.Consumer<InboundSseEvent> onEvent,
java.util.function.Consumer<java.lang.Throwable> onError,
java.lang.Runnable onComplete)
Register
InboundSseEvent and Throwable consumers and onComplete callback. |
static SseEventSource.Builder |
target(WebTarget endpoint)
Create a new
event source builder that provides convenient way how to configure and
fine-tune various aspects of a newly prepared event source instance. |
void register(java.util.function.Consumer<InboundSseEvent> onEvent)
InboundSseEvent consumer.
Given consumer is invoked once per each received event.
onEvent - event consumer.java.lang.IllegalArgumentException - when the provided parameter is null.void register(java.util.function.Consumer<InboundSseEvent> onEvent, java.util.function.Consumer<java.lang.Throwable> onError)
InboundSseEvent and Throwable consumers.
Event consumer is invoked once per each received event, Throwable consumer is invoked invoked upon a
unrecoverable error encountered by a SseEventSource.
onEvent - event consumer.onError - error consumer.java.lang.IllegalArgumentException - when the any of the provided parameters is null.void register(java.util.function.Consumer<InboundSseEvent> onEvent, java.util.function.Consumer<java.lang.Throwable> onError, java.lang.Runnable onComplete)
InboundSseEvent and Throwable consumers and onComplete callback.
Event consumer is invoked once per each received event, Throwable consumer is invoked invoked upon a
unrecoverable error encountered by a SseEventSource, onComplete callback is invoked after a successful
connection and when there are no further events to be received. Note that the onComplete callback will not be
invoked if the onError callback has been invoked.
onEvent - event consumer.onError - error consumer.onComplete - onComplete handler.java.lang.IllegalArgumentException - when the any of the provided parameters is null.static SseEventSource.Builder target(WebTarget endpoint)
event source builder that provides convenient way how to configure and
fine-tune various aspects of a newly prepared event source instance.endpoint - SSE streaming endpoint. Must not be null.java.lang.NullPointerException - in case the supplied web target is null.void open()
web target and start processing incoming
events.java.lang.IllegalStateException - in case the event source has already been opened earlier.boolean isOpen()
opened.true if this event source is open, false otherwise.default void close()
The method will wait up to 5 seconds for the internal event processing tasks to complete.
close in interface java.lang.AutoCloseableboolean close(long timeout,
java.util.concurrent.TimeUnit unit)
The method blocks until the event processing task has completed execution after a shutdown request, or until the timeout occurs, or the current thread is interrupted, whichever happens first.
In case the waiting for the event processing task has been interrupted, this method restores the
interrupt flag on the thread before returning false.
timeout - the maximum time to wait.unit - the time unit of the timeout argument.true if this executor terminated and false if the timeout elapsed before termination or the
termination was interrupted.