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.withPath("/examples/123")).get();

// 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 exactly one ServerSentEventBroadcaster instance exists per ResourcePath. 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

    • broadcastComment

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

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

      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:
      comment - the comment payload to broadcast