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<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 in onComplete 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.

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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public abstract static class	SseEventSource.Builder JAX-RS `SseEventSource` builder class.

Method Summary

Modifier and Type	Method and Description
public default void	close() Implements java.lang.AutoCloseable.close. Close this event source.
public boolean	Returns: `true` if this executor terminated and `false` if the timeout elapsed before termination or the termination was interrupted. close(final long the maximum time to wait. timeout, final TimeUnit the time unit of the timeout argument. unit) Close this event source and wait for the internal event processing task to complete for up to the specified amount of wait time.
public boolean	Returns: `true` if this event source is open, `false` otherwise. isOpen() Check if this event source instance has already been `opened`.
public void	open() Open the connection to the supplied SSE underlying `web target` and start processing incoming `events`.
public void	register(Consumer<InboundSseEvent> event consumer. onEvent) Register a `InboundSseEvent` consumer.
public void	register(Consumer<InboundSseEvent> event consumer. onEvent, Consumer<Throwable> error consumer. onError) Register `InboundSseEvent` and `Throwable` consumers.
public void	register(Consumer<InboundSseEvent> event consumer. onEvent, Consumer<Throwable> error consumer. onError, Runnable onComplete handler. onComplete) Register `InboundSseEvent` and `Throwable` consumers and onComplete callback.
public static SseEventSource.Builder	Returns: a builder of a new event source instance pointing at the specified SSE streaming endpoint. target(final WebTarget SSE streaming endpoint. Must not be `null`. 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

close	back to summary
public default void close() Implements java.lang.AutoCloseable.close. Close this event source. The method will wait up to 5 seconds for the internal event processing tasks to complete. Annotations @Override

back to summary

public default void close()

Implements java.lang.AutoCloseable.close.

Close this event source.

The method will wait up to 5 seconds for the internal event processing tasks to complete.

Annotations

@Override

close back to summary

close	back to summary
public boolean close(final long timeout, final 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:long the maximum time to wait. unit:TimeUnit the time unit of the timeout argument. Returns:boolean `true` if this executor terminated and `false` if the timeout elapsed before termination or the termination was interrupted.

public boolean close(final long timeout, final 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:long: the maximum time to wait.
unit:TimeUnit: the time unit of the timeout argument.

Returns:boolean

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

isOpen back to summary

isOpen	back to summary
public boolean isOpen() Check if this event source instance has already been `opened`. Returns:boolean `true` if this event source is open, `false` otherwise.

public boolean isOpen()

Check if this event source instance has already been opened.

Returns:boolean: true if this event source is open, false otherwise.

open back to summary

open	back to summary
public void open() Open the connection to the supplied SSE underlying `web target` and start processing incoming `events`. Exceptions IllegalStateException: in case the event source has already been opened earlier.

public void open()

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

Exceptions

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

register	back to summary
public void register(Consumer<InboundSseEvent> onEvent) Register a `InboundSseEvent` consumer. Given consumer is invoked once per each received event. Parameters onEvent:Consumer<InboundSseEvent> event consumer. Exceptions IllegalArgumentException: when the provided parameter is `null`.

public void register(Consumer<InboundSseEvent> onEvent)

Given consumer is invoked once per each received event.

Parameters

onEvent:Consumer<InboundSseEvent>: event consumer.

Exceptions

IllegalArgumentException:: when the provided parameter is null.

register	back to summary
public 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:Consumer<InboundSseEvent> event consumer. onError:Consumer<Throwable> error consumer. Exceptions IllegalArgumentException: when the any of the provided parameters is `null`.

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

Event consumer is invoked once per each received event, Throwable consumer is invoked invoked upon a unrecoverable error encountered by a SseEventSource.

Parameters

onEvent:Consumer<InboundSseEvent>: event consumer.
onError:Consumer<Throwable>: error consumer.

Exceptions

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

register	back to summary
public 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 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:Consumer<InboundSseEvent> event consumer. onError:Consumer<Throwable> error consumer. onComplete:Runnable onComplete handler. Exceptions IllegalArgumentException: when the any of the provided parameters is `null`.

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

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.

Parameters

onEvent:Consumer<InboundSseEvent>: event consumer.
onError:Consumer<Throwable>: error consumer.
onComplete:Runnable: onComplete handler.

Exceptions

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

target back to summary

target	back to summary
public static SseEventSource.Builder target(final 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:WebTarget SSE streaming endpoint. Must not be `null`. Returns:SseEventSource.Builder a builder of a new event source instance pointing at the specified SSE streaming endpoint. Exceptions NullPointerException: in case the supplied web target is `null`.

public static SseEventSource.Builder target(final 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:WebTarget: SSE streaming endpoint. Must not be null.

Returns:SseEventSource.Builder

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

Exceptions

NullPointerException:: in case the supplied web target is null.

jakarta.ws.rs.sse back to summary

public abstract Class SseEventSource.Builder

Class Inheritance

extends Object

java.lang.Object
jakarta.ws.rs.sse.SseEventSource.Builder

JAX-RS SseEventSource builder class.

Event source builder provides methods that let you conveniently configure and subsequently build a new SseEventSource instance. You can obtain a new event source builder instance using a static SseEventSource.target(endpoint) factory method.

For example:

SseEventSource es = SseEventSource.target(endpoint)
        .reconnectingEvery(5, SECONDS)
        .build();
es.register(System.out::println);
es.open();

Field Summary

Modifier and Type	Field and Description
public static final String	JAXRS_DEFAULT_SSE_BUILDER_PROPERTY Name of the property identifying the `SseEventSource.Builder` implementation to be returned from `SseEventSource.Builder#newBuilder()`.

Constructor Summary

Access	Constructor and Description
protected	Builder() Allows custom implementations to extend the SSE event source builder class.

Method Summary

Modifier and Type	Method and Description
public abstract SseEventSource	Returns: new event source instance, ready to be connected to the SSE endpoint. build() Build new SSE event source pointing at a SSE streaming `web target`.
pack-priv static SseEventSource.Builder	Returns: new SSE event source builder instance. newBuilder() Create a new SSE event source instance using the default implementation class provided by the JAX-RS implementation provider.
public abstract SseEventSource.Builder	Returns: updated event source builder instance. reconnectingEvery(long the default time to wait before attempting to recover from a connection loss. delay, TimeUnit time unit of the reconnect delay parameter. unit) Set the initial reconnect delay to be used by the event source.
protected abstract SseEventSource.Builder	Returns: updated event source builder instance. target(WebTarget SSE streaming endpoint. Must not be `null`. endpoint) Set the SSE streaming endpoint.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

JAXRS_DEFAULT_SSE_BUILDER_PROPERTY	back to summary
public static final String JAXRS_DEFAULT_SSE_BUILDER_PROPERTY Name of the property identifying the `SseEventSource.Builder` implementation to be returned from `SseEventSource.Builder#newBuilder()`.

Constructor Detail

Builder	back to summary
protected Builder() Allows custom implementations to extend the SSE event source builder class.

Method Detail

build back to summary

build	back to summary
public abstract SseEventSource build() Build new SSE event source pointing at a SSE streaming `web target`. The returned event source is ready, but not `connected` to the SSE endpoint. It is expected that you will manually invoke its `open()` method once you are ready to start receiving SSE events. In case you want to build an event source instance that is already connected to the SSE endpoint, use the event source builder `open()` method instead. Once the event source is open, the incoming events are processed by the event source in an asynchronous task that runs in an internal single-threaded `scheduled executor service`. Returns:SseEventSource new event source instance, ready to be connected to the SSE endpoint. See Also `open()`

public abstract SseEventSource build()

Build new SSE event source pointing at a SSE streaming web target.

The returned event source is ready, but not connected to the SSE endpoint. It is expected that you will manually invoke its open() method once you are ready to start receiving SSE events. In case you want to build an event source instance that is already connected to the SSE endpoint, use the event source builder open() method instead.

Once the event source is open, the incoming events are processed by the event source in an asynchronous task that runs in an internal single-threaded scheduled executor service.

Returns:SseEventSource: new event source instance, ready to be connected to the SSE endpoint.
See Also: open()

newBuilder	back to summary
pack-priv static SseEventSource.Builder newBuilder() Create a new SSE event source instance using the default implementation class provided by the JAX-RS implementation provider. Returns:SseEventSource.Builder new SSE event source builder instance.

newBuilder

back to summary

pack-priv static SseEventSource.Builder newBuilder()

Create a new SSE event source instance using the default implementation class provided by the JAX-RS implementation provider.

Returns:SseEventSource.Builder: new SSE event source builder instance.

reconnectingEvery back to summary

reconnectingEvery	back to summary
public abstract SseEventSource.Builder reconnectingEvery(long delay, TimeUnit unit) Set the initial reconnect delay to be used by the event source. Note that this value may be later overridden by the SSE endpoint using either a `retry` SSE event field or `HTTP 503 + Retry-After` mechanism as described in the `SseEventSource` javadoc. Parameters delay:long the default time to wait before attempting to recover from a connection loss. unit:TimeUnit time unit of the reconnect delay parameter. Returns:SseEventSource.Builder updated event source builder instance.

public abstract SseEventSource.Builder reconnectingEvery(long delay, TimeUnit unit)

Set the initial reconnect delay to be used by the event source.

Note that this value may be later overridden by the SSE endpoint using either a retry SSE event field or HTTP 503 + Retry-After mechanism as described in the SseEventSource javadoc.

Parameters

delay:long: the default time to wait before attempting to recover from a connection loss.
unit:TimeUnit: time unit of the reconnect delay parameter.

Returns:SseEventSource.Builder

updated event source builder instance.

target back to summary

target	back to summary
protected abstract SseEventSource.Builder target(WebTarget endpoint) Set the SSE streaming endpoint. Parameters endpoint:WebTarget SSE streaming endpoint. Must not be `null`. Returns:SseEventSource.Builder updated event source builder instance. Exceptions NullPointerException: in case the supplied web target is `null`.

protected abstract SseEventSource.Builder target(WebTarget endpoint)

Set the SSE streaming endpoint.

Parameters

endpoint:WebTarget: SSE streaming endpoint. Must not be null.

Returns:SseEventSource.Builder

updated event source builder instance.

Exceptions

NullPointerException:: in case the supplied web target is null.

public Interface SseEventSource

Reconnect support

Nested and Inner Type Summary

Method Summary

Method Detail

public abstract Class SseEventSource.Builder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail