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
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 send 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 the 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 the any send 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
automatically deals with any
HTTP 503 Service Unavailable
responses from an SSE endpoint, that contain a
"Retry-After" HTTP header with a valid value. The
HTTP 503 + "Retry-After" technique is often used by HTTP endpoints
as a means of connection and traffic throttling.
In case a HTTP 503 + "Retry-After" response is received in return to a connection
request, JAX-RS SSE event source will automatically schedule a new reconnect attempt and use the received
"Retry-After" HTTP header value as a one-time override of the reconnect delay.
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,
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(Consumer<InboundSseEvent> onEvent)
Register a
InboundSseEvent consumer. |
void |
register(Consumer<InboundSseEvent> onEvent,
Consumer<Throwable> onError)
Register
InboundSseEvent and Throwable consumers. |
void |
register(Consumer<InboundSseEvent> onEvent,
Consumer<Throwable> onError,
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(Consumer<InboundSseEvent> onEvent)
InboundSseEvent
consumer.
Given consumer is invoked once per each received event.
onEvent
- event consumer.IllegalArgumentException
- when the provided parameter is null
.void register(Consumer<InboundSseEvent> onEvent, Consumer<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.IllegalArgumentException
- when the any of the provided parameters is null
.void register(Consumer<InboundSseEvent> onEvent, Consumer<Throwable> onError, 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 when there are no
further events to be received.
onEvent
- event consumer.onError
- error consumer.onComplete
- onComplete handler.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
.NullPointerException
- in case the supplied web target is null
.void open()
web target
and start processing incoming
events
.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 AutoCloseable
boolean close(long timeout, 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.Copyright © 1996-2017, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.