Package rife.engine

Class SseConnection

java.lang.Object

rife.engine.SseConnection

All Implemented Interfaces:

AutoCloseable

public class SseConnection
extends Object
implements AutoCloseable

An SseConnection instance represents a single server-sent events (SSE) connection to a client.

An SSE connection is obtained inside an element through Context.sse() or Context.sse(SseBroadcaster). Creating it prepares the response for event streaming: the content type is set to text/event-stream, response buffering is disabled, and the headers are flushed to the client so that it knows that the stream has been established. Every event that is sent afterwards will immediately be flushed to the client.

The first variant keeps the element in control of the connection, which stays open for as long as the element is executing:

get("/events", c -> {
     var sse = c.sse();
     while (sse.isOpen()) {
         sse.send(new ServerSentEvent().name("tick").template(c.template("tick_fragment")));
         // ...
     }
 });

The second variant registers the connection with an SseBroadcaster and detaches it from the element, which returns immediately while the connection stays open. Events can then be pushed from anywhere in the application through the broadcaster.

Sending an event to a client that has disconnected will mark the connection as closed, which can be detected with isOpen().

Since:

1.10

See Also:

• ServerSentEvent
• SseBroadcaster
• Context.sse()
• Context.sse(SseBroadcaster)

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CONTENT_TYPE_EVENT_STREAM	The content type that is used for server-sent events streams.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes this connection.
boolean	comment(String comment)	Sends a comment line, typically used as a keep-alive heartbeat.
Context	context()	Retrieves the context of the request that established this connection.
boolean	isOpen()	Indicates whether this connection is still open.
String	lastEventId()	Retrieves the ID of the last event that the client received.
boolean	send(CharSequence data)	Sends an event with the provided text as its data.
boolean	send(ServerSentEvent event)	Sends an event to the client of this connection.
boolean	send(Template template)	Sends an event with the content of the provided template as its data.
boolean	send(Template template, String blockId)	Sends an event with the content of a single template block as its data.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CONTENT_TYPE_EVENT_STREAM

public static final String CONTENT_TYPE_EVENT_STREAM

The content type that is used for server-sent events streams.

Since:

1.10

See Also:

• Constant Field Values

Method Details

send

public boolean send(ServerSentEvent event)

Sends an event to the client of this connection.

The event will immediately be flushed. When the client has disconnected, the connection is marked as closed and false is returned.

Parameters:

event - the event to send

Returns:

true when the event was sent successfully; or

false when the connection was closed

Since:

1.10

See Also:

• send(CharSequence)
• send(Template)
• isOpen()

send

public boolean send(CharSequence data)

Sends an event with the provided text as its data.

Parameters:

data - the data of the event

Returns:

true when the event was sent successfully; or

false when the connection was closed

Since:

1.10

See Also:

• send(ServerSentEvent)
• send(Template)

send

public boolean send(Template template)

Sends an event with the content of the provided template as its data.

The filtered tags of the template will be resolved against the context of this connection.

Parameters:

template - the template whose content will be used as event data

Returns:

true when the event was sent successfully; or

false when the connection was closed

Since:

1.10

See Also:

• send(ServerSentEvent)
• send(Template, String)

send

public boolean send(Template template,
 String blockId)

Sends an event with the content of a single template block as its data.

The filtered tags of the template will be resolved against the context of this connection.

Parameters:

template - the template that contains the block

blockId - the ID of the block whose content will be used as event data

Returns:

true when the event was sent successfully; or

false when the connection was closed

Since:

1.10

See Also:

• send(ServerSentEvent)
• send(Template)

comment

public boolean comment(String comment)

Sends a comment line, typically used as a keep-alive heartbeat.

Parameters:

comment - the comment text

Returns:

true when the comment was sent successfully; or

false when the connection was closed

Since:

1.10

See Also:

• send(ServerSentEvent)
• SseBroadcaster.heartbeat(java.time.Duration)

lastEventId

public String lastEventId()

Retrieves the ID of the last event that the client received.

Browsers transmit this through the Last-Event-ID request header when they reconnect. When that header is absent, the lastEventId request parameter is used instead, which makes it possible for pages to provide the ID of the last event that was rendered as part of the stream URL of the initial connection.

Returns:

the last event ID; or

null when the client didn't provide one

Since:

1.10

See Also:

• SseBroadcaster.lastEventId()
• SseBroadcaster.history(int)

isOpen

public boolean isOpen()

Indicates whether this connection is still open.

A disconnect is detected when the servlet container reports that the asynchronous request has completed, timed out or errored, and otherwise when sending an event to the client fails. This means that a stale connection can still report being open until the container notices, or until the next event or heartbeat is sent.

Returns:

true when the connection is open; or

false when it has been closed

Since:

1.10

See Also:

• close()

context

public Context context()

Retrieves the context of the request that established this connection.

Returns:

this connection's context

Since:

1.10

See Also:

• SseBroadcaster.send(ServerSentEvent, SseConnectionFilter)

close

public void close()

Closes this connection.

For detached connections, this will complete the underlying asynchronous request and end the response.

Specified by:

close in interface AutoCloseable

Since:

1.10

See Also:

• isOpen()