javax.ws.rs.sse

Interface SseEventSource

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

SseEventSourceImpl

public interface SseEventSource
extends AutoCloseable

Client for reading and processing 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#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 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. 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, 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, 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.

Since:

2.1

Author:

Marek Potociar

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SseEventSource.Builder SseEventSource builder class.

Method Summary

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.

Method Detail

register

void register(Consumer<InboundSseEvent> onEvent)

Register a InboundSseEvent consumer.

Given consumer is invoked once per each received event.

Parameters:

onEvent - event consumer.

Throws:

IllegalArgumentException - when the provided parameter is null.

register

void register(Consumer<InboundSseEvent> onEvent,
              Consumer<Throwable> onError)

Register 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.

Parameters:

onEvent - event consumer.

onError - error consumer.

Throws:

IllegalArgumentException - when the any of the provided parameters is null.

register

void register(Consumer<InboundSseEvent> onEvent,
              Consumer<Throwable> onError,
              Runnable onComplete)

Register 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.

Parameters:

onEvent - event consumer.

onError - error consumer.

onComplete - onComplete handler.

Throws:

IllegalArgumentException - when the any of the provided parameters is null.

target

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.

Parameters:

endpoint - SSE streaming endpoint. Must not be null.

Returns:

a builder of a new event source instance pointing at the specified SSE streaming endpoint.

Throws:

NullPointerException - in case the supplied web target is null.

open

void open()

Open the connection to the supplied SSE underlying web target and start processing incoming events.

Throws:

IllegalStateException - in case the event source has already been opened earlier.

isOpen

boolean isOpen()

Check if this event source instance has already been opened.

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 interface AutoCloseable

close

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.

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.

Parameters:

timeout - the maximum time to wait.

unit - the time unit of the timeout argument.

Returns:

true if this executor terminated and false if the timeout elapsed before termination or the termination was interrupted.