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

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

 // Publish SSE payload to all listening clients
 broadcaster.broadcast(serverSentEvent);

Soklet guarantees exactly one ServerSentEventBroadcaster instance exists per ResourcePath. Soklet 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 broadcast(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

    • broadcast

      void broadcast(@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