Interface ServerSentEventBroadcaster

public interface ServerSentEventBroadcaster
Broadcasts a Server-Sent Event payload to all clients listening on a ResourcePath.

For example: 

// Acquire our SSE broadcaster (sends to anyone listening to "/examples/123")
ServerSentEventServer server = ...;
ServerSentEventBroadcaster broadcaster = server.acquireBroadcaster(ResourcePath.fromPath("/examples/123")).orElseThrow();

// Create our SSE payload
ServerSentEvent event = ServerSentEvent.withEvent("test")
  .data("example")
  .build();

// Publish SSE payload to all listening clients
broadcaster.broadcastEvent(event);

Soklet's default ServerSentEventServer implementation guarantees at most one broadcaster is registered per ResourcePath at a time; instances may be recreated after becoming idle. That implementation is responsible for the creation and management of ServerSentEventBroadcaster instances.

You may acquire a broadcaster via ServerSentEventServer.acquireBroadcaster(ResourcePath).

See https://www.soklet.com/docs/server-sent-events 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 Details

    • getResourcePath

      @NonNull ResourcePath getResourcePath()
      The runtime Resource Path with which this broadcaster is associated.

      Soklet guarantees exactly one ServerSentEventBroadcaster instance exists per ResourcePath.

      For example, a client may register for SSE broadcasts for Resource Method @ServerSentEventSource("/examples/{exampleId}") by making a request to GET /examples/123.

      A broadcaster specific to /examples/123 is then created (if necessary) and managed by Soklet, and can be used to send SSE payloads to all clients via broadcastEvent(ServerSentEvent).

      Returns:
      the runtime Resource Path instance with which this broadcaster is associated

    • getClientCount

      @NonNull Long getClientCount()
      Approximately how many clients are listening to this broadcaster's ResourcePath?

      For performance reasons, this number may be an estimate, or a snapshot of a recent moment-in-time. It's possible for some clients to have already disconnected, but we won't know until we attempt to broadcast to them.

      Returns:
      the approximate number of clients who will receive a broadcasted event

    • broadcastEvent

      void broadcastEvent(@NonNull ServerSentEvent serverSentEvent)
      Broadcasts a Server-Sent Event payload to all clients listening to this broadcaster's ResourcePath.

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

      However, mock implementations may wish to block until broadcasts have completed - for example, to simplify automated testing.

      Parameters:
      serverSentEvent - the Server-Sent Event payload to broadcast

    • broadcastEvent

      <T> void broadcastEvent(@NonNull Function<Object,T> keySelector, @NonNull Function<T, ServerSentEvent> eventProvider)
      Broadcasts a Server-Sent Event where the payload is dynamically generated and memoized based on a specific trait of the client (e.g. Locale or User Role).

      This method is designed for high-scale scenarios where generating the payload is expensive (e.g. JSON serialization with localization) and the number of distinct variations (keys) is significantly smaller than the number of clients.

      The implementation guarantees that eventProvider is called exactly once per unique key derived by keySelector among the currently active clients.

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

      However, mock implementations may wish to block until broadcasts have completed - for example, to simplify automated testing.

      Type Parameters:
      T - the type of the grouping key (e.g. Locale or String)
      Parameters:
      keySelector - a function that derives a grouping key from the client's associated context object. (If the client has no context, the implementation passes null)
      eventProvider - a function that provides the ServerSentEvent for a given key

    • broadcastComment

      void broadcastComment(@NonNull ServerSentEventComment serverSentEventComment)
      Broadcasts a single Server-Sent Event comment to all clients listening to this broadcaster's ResourcePath.

      Use ServerSentEventComment.heartbeatInstance() to emit a heartbeat comment.

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

      However, mock implementations may wish to block until broadcasts have completed - for example, to simplify automated testing.

      Parameters:
      serverSentEventComment - the comment payload to broadcast

    • broadcastComment

      <T> void broadcastComment(@NonNull Function<Object,T> keySelector, @NonNull Function<T, ServerSentEventComment> commentProvider)
      Broadcasts a Server-Sent Event comment where the payload is dynamically generated and memoized based on a specific trait of the client (e.g. Locale or User Role).

      This follows the same memoization pattern as broadcastEvent(Function, Function).

      The implementation guarantees that commentProvider is called exactly once per unique key derived by keySelector among the currently active clients.

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

      However, mock implementations may wish to block until broadcasts have completed - for example, to simplify automated testing.

      Type Parameters:
      T - the type of the grouping key
      Parameters:
      keySelector - a function that derives a grouping key from the client's associated context object
      commentProvider - a function that provides the comment payload for a given key