Server-Sent Events (SSE) API Reference

public interface ServerSentEventListener {
    /**
     * Called when the SSE connection is successfully opened.
     * Provides access to the initial HTTP response.
     *
     * @param response the successful HTTP response with headers and status
     */
    default void onOpen(SuccessfulHttpResponse response) {}

    /**
     * Called when a server-sent event is received.
     * This is the preferred method that provides context for stream cancellation.
     * Experimental API introduced in version 1.8.0.
     *
     * @param event the parsed server-sent event
     * @param context context object providing access to parsing control
     */
    default void onEvent(ServerSentEvent event, ServerSentEventContext context) {
        onEvent(event);
    }

    /**
     * Called when a server-sent event is received.
     * This is a legacy method. Use onEvent(ServerSentEvent, ServerSentEventContext)
     * for stream cancellation support.
     *
     * @param event the parsed server-sent event
     */
    default void onEvent(ServerSentEvent event) {}

    /**
     * Called when an error occurs during streaming.
     * This is the only abstract method and must be implemented.
     *
     * @param throwable the error that occurred
     */
    void onError(Throwable throwable);

    /**
     * Called when the SSE connection is closed.
     * This is called for both normal completion and after errors.
     */
    default void onClose() {}
}

public class ServerSentEvent {
    /**
     * Creates a new server-sent event.
     *
     * @param event the event type (may be null for unnamed events)
     * @param data the event data
     */
    public ServerSentEvent(String event, String data);

    /**
     * Returns the event type.
     * May be null if the event had no explicit type.
     *
     * @return the event type, or null
     */
    public String event();

    /**
     * Returns the event data.
     *
     * @return the event data
     */
    public String data();
}

/**
 * Parses server-sent events (SSE) from an InputStream,
 * constructs ServerSentEvent objects,
 * and delivers them to the provided ServerSentEventListener.
 */
public interface ServerSentEventParser {
    /**
     * Parses an input stream containing server-sent events and notifies the listener.
     * This method blocks until the input stream is exhausted or an error occurs.
     *
     * For each complete event found in the stream, ServerSentEventListener.onEvent()
     * is called. If any parsing or processing error occurs,
     * ServerSentEventListener.onError() is called and parsing may terminate.
     *
     * @param httpResponseBody the input stream containing SSE data
     * @param listener the listener to receive parsed events or error notifications
     */
    void parse(InputStream httpResponseBody, ServerSentEventListener listener);
}

/**
 * Default implementation of ServerSentEventParser using BufferedReader.
 * Parses SSE format according to the standard:
 * - Lines starting with "event:" set the event type
 * - Lines starting with "data:" append to the event data
 * - Empty lines trigger event dispatch
 * - Other lines are ignored
 */
public class DefaultServerSentEventParser implements ServerSentEventParser {
    /**
     * Parses SSE data from the input stream.
     *
     * @param httpResponseBody the input stream containing SSE data
     * @param listener the listener to receive parsed events
     */
    public void parse(InputStream httpResponseBody, ServerSentEventListener listener);
}

/**
 * Context object for server-sent event handling.
 * Experimental API introduced in version 1.8.0.
 */
public class ServerSentEventContext {
    /**
     * Creates a new context with a parsing handle.
     *
     * @param parsingHandle the handle for controlling stream parsing
     */
    public ServerSentEventContext(ServerSentEventParsingHandle parsingHandle);

    /**
     * Returns the parsing handle for controlling the stream.
     *
     * @return the parsing handle
     */
    public ServerSentEventParsingHandle parsingHandle();
}

/**
 * Handle that can be used to cancel the parsing of server-sent events.
 * Experimental API introduced in version 1.8.0.
 */
public interface ServerSentEventParsingHandle {
    /**
     * Cancels the parsing of server-sent events.
     * After calling this method, no more events will be processed.
     */
    void cancel();

    /**
     * Returns true if parsing was cancelled by calling cancel().
     *
     * @return true if cancelled, false otherwise
     */
    boolean isCancelled();
}

/**
 * Default implementation of ServerSentEventParsingHandle.
 * Since: 1.8.0
 */
public class DefaultServerSentEventParsingHandle implements ServerSentEventParsingHandle {
    /**
     * Creates a new handle for the given input stream.
     *
     * @param inputStream the input stream to manage
     */
    public DefaultServerSentEventParsingHandle(InputStream inputStream);

    /**
     * Cancels parsing by closing the input stream.
     * Sets the cancelled flag and closes the underlying InputStream.
     */
    public void cancel();

    /**
     * Returns true if cancel() has been called.
     *
     * @return true if cancelled, false otherwise
     */
    public boolean isCancelled();
}

event: message
data: First line of data
data: Second line of data

event: update
data: {"status": "processing"}

data: Data without explicit event type