Interface SseEventSource
- All Superinterfaces:
AutoCloseable
public interface SseEventSource extends 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.
Reconnect support
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:
- 200 - with
"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. - 200 - with unsupported or missing
"Content-Type"
header: This is an error condition.onError
is invoked. - 204 - This indicates that server has no events to send. Only
onComplete
is invoked. - 503 - with
"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 inonComplete
invocation). After the specified delay, the client should automatically attempt to reconnect which will result in a new response. - 503 - with invalid or missing
"Retry-After"
header: This is an error condition.onError
is invoked. - Any other status code: This is an error condition.
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.
- Since:
- 2.1
- Author:
- Marek Potociar
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
SseEventSource.Builder
JAX-RSSseEventSource
builder class. -
Method Summary
Modifier and Type Method Description default void
close()
Close this event source.boolean
close(long timeout, 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 beenopened
.void
open()
Open the connection to the supplied SSE underlyingweb target
and start processing incomingevents
.void
register(Consumer<InboundSseEvent> onEvent)
Register aInboundSseEvent
consumer.void
register(Consumer<InboundSseEvent> onEvent, Consumer<Throwable> onError)
RegisterInboundSseEvent
andThrowable
consumers.void
register(Consumer<InboundSseEvent> onEvent, Consumer<Throwable> onError, Runnable onComplete)
RegisterInboundSseEvent
andThrowable
consumers and onComplete callback.static SseEventSource.Builder
target(WebTarget endpoint)
Create a newevent source builder
that provides convenient way how to configure and fine-tune various aspects of a newly prepared event source instance.
-
Method Details
-
register
Register aInboundSseEvent
consumer.Given consumer is invoked once per each received event.
- Parameters:
onEvent
- event consumer.- Throws:
IllegalArgumentException
- when the provided parameter isnull
.
-
register
RegisterInboundSseEvent
andThrowable
consumers.Event consumer is invoked once per each received event,
Throwable
consumer is invoked invoked upon a unrecoverable error encountered by aSseEventSource
.- Parameters:
onEvent
- event consumer.onError
- error consumer.- Throws:
IllegalArgumentException
- when the any of the provided parameters isnull
.
-
register
RegisterInboundSseEvent
andThrowable
consumers and onComplete callback.Event consumer is invoked once per each received event,
Throwable
consumer is invoked invoked upon a unrecoverable error encountered by aSseEventSource
, 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.- Parameters:
onEvent
- event consumer.onError
- error consumer.onComplete
- onComplete handler.- Throws:
IllegalArgumentException
- when the any of the provided parameters isnull
.
-
target
Create a newevent source builder
that provides convenient way how to configure and fine-tune various aspects of a newly prepared event source instance.- Parameters:
endpoint
- SSE streaming endpoint. Must not benull
.- Returns:
- a builder of a new event source instance pointing at the specified SSE streaming endpoint.
- Throws:
NullPointerException
- in case the supplied web target isnull
.
-
open
void open()Open the connection to the supplied SSE underlyingweb target
and start processing incomingevents
.- Throws:
IllegalStateException
- in case the event source has already been opened earlier.
-
isOpen
boolean isOpen()Check if this event source instance has already beenopened
.- Returns:
true
if this event source is open,false
otherwise.
-
close
default void close()Close this event source.The method will wait up to 5 seconds for the internal event processing tasks to complete.
- Specified by:
close
in interfaceAutoCloseable
-
close
Close this event source and wait for the internal event processing task to complete for up to the specified amount of wait time.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 returningfalse
.- Parameters:
timeout
- the maximum time to wait.unit
- the time unit of the timeout argument.- Returns:
true
if this executor terminated andfalse
if the timeout elapsed before termination or the termination was interrupted.
-