Module jakarta.ws.rs
Package jakarta.ws.rs.sse

Interface SseEventSource

All Superinterfaces:
AutoCloseable
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<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.

Since:
2.1