Interface ServerSentEventUnicaster

public interface ServerSentEventUnicaster

Unicasts a Server-Sent Event or comment payload to a specific client listening on a ResourcePath.

For example:

@ServerSentEventSource("/chats/{chatId}/event-source")
public HandshakeResult chatEventSource(
  @PathParameter Long chatId,
  // Browsers will send this header automatically on reconnects
  @RequestHeader(name="Last-Event-ID", optional=true) String lastEventId
) {
  Chat chat = myChatService.find(chatId);

  // Exceptions that bubble out will reject the handshake and go through the
  // ResponseMarshaler::forThrowable path, same as non-SSE Resource Methods
  if (chat == null)
    throw new NoSuchChatException();

  // If a Last-Event-ID header was sent, pull data to "catch up" the client
  List<ChatMessage> catchupMessages = new ArrayList<>();

  if(lastEventId != null)
    catchupMessages.addAll(myChatService.findCatchups(chatId, lastEventId));

  // Customize "accept" handshake with a client initializer
  return HandshakeResult.acceptWithDefaults()
    .clientInitializer((unicaster) -> {
      // Unicast "catchup" initialization events to this specific client.
      // The unicaster is guaranteed to write these events before any
      // other broadcaster does, allowing clients to safely catch up
      // without the risk of event interleaving
      catchupMessages.stream()
        .map(catchupMessage -> ServerSentEvent.withEvent("chat-message")
          .id(catchupMessage.id())
          .data(catchupMessage.toJson())
          .retry(Duration.ofSeconds(5))
          .build())
        .forEach(event -> unicaster.unicastEvent(event));
    })
    .build();
}

See https://www.soklet.com/docs/server-sent-events#client-initialization for detailed documentation.

Formal specification is available at https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events.

Author:

Mark Allen

Method Summary

Modifier and Type	Method	Description
ResourcePath	getResourcePath()	The runtime Resource Path with which this unicaster is associated.
void	unicastComment(String comment)	Unicasts a single Server-Sent Event comment to a specific client listening to this unicaster's ResourcePath.
void	unicastEvent(ServerSentEvent serverSentEvent)	Unicasts a single Server-Sent Event payload to a specific client listening to this unicaster's ResourcePath.

Method Details

unicastEvent

void unicastEvent(@Nonnull
 ServerSentEvent serverSentEvent)

Unicasts a single Server-Sent Event payload to a specific client listening to this unicaster's ResourcePath.

In practice, implementations will generally return "immediately" and unicast operation[s] will occur on separate threads of execution.

However, mock implementations may wish to block until the unicast has completed - for example, to simplify automated testing.

Parameters:

serverSentEvent - the Server-Sent Event payload to unicast

unicastComment

void unicastComment(@Nonnull
 String comment)

Unicasts a single Server-Sent Event comment to a specific client listening to this unicaster's ResourcePath.

Specify a blank string to generate a bare ":" Server-Sent Event comment line.

In practice, implementations will generally return "immediately" and unicast operation[s] will occur on separate threads of execution.

However, mock implementations may wish to block until the unicast has completed - for example, to simplify automated testing.

Parameters:

comment - the comment payload to unicast

getResourcePath

@Nonnull
ResourcePath getResourcePath()

The runtime Resource Path with which this unicaster is associated.

For example, a client may successfully complete a Server-Sent Event handshake for Resource Method @ServerSentEventSource("/examples/{exampleId}") by making a request to GET /examples/123. The server, immediately after accepting the handshake, might then acquire a unicaster to "catch up" the client according to the Last-Event-ID header value (for example).

A unicaster specific to /examples/123 is then created (if necessary) and managed by Soklet, and can be used to send SSE payloads to that specific client via unicastEvent(ServerSentEvent).

Returns:

the runtime Resource Path instance with which this unicaster is associated