Interface HandshakeResult

All Known Implementing Classes:
HandshakeResult.Accepted, HandshakeResult.Rejected
public sealed interface HandshakeResult permits HandshakeResult.Accepted, HandshakeResult.Rejected
Represents the result of a ServerSentEventSource "handshake".

Once a handshake has been accepted, you may acquire a broadcaster via ServerSentEventServer.acquireBroadcaster(ResourcePath) - the client whose handshake was accepted will then receive Server-Sent Events broadcast via ServerSentEventBroadcaster.broadcastEvent(ServerSentEvent).

You might have a JavaScript Server-Sent Event client that looks like this: 

// Register an event source
let eventSourceUrl =
  'https://sse.example.com/chats/123/event-source?signingToken=xxx';

let eventSource = new EventSource(eventSourceUrl);

// Listen for Server-Sent Events
eventSource.addEventListener('chat-message', (e) => {
  console.log(`Chat message: ${e.data}`);
});

And then a Soklet Server-Sent Event Source that looks like this, which performs the handshake: 

// Resource Method that acts as a Server-Sent Event Source
@ServerSentEventSource("/chats/{chatId}/event-source")
public HandshakeResult chatEventSource(
  @PathParameter Long chatId,
  @QueryParameter String signingToken
) {
  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 NotFoundException();

  // You'll normally want to use a transient signing token for SSE authorization
  myAuthorizationService.verify(signingToken);

  // Accept the handshake with no additional data
  // (or use a variant to send headers/cookies).
  // Can also reject via HandshakeResult.rejectWithResponse(...)
  return HandshakeResult.accept();
}

Finally, broadcast to all clients who had their handshakes accepted: 

// Sometime later, acquire a broadcaster...
ResourcePath resourcePath = ResourcePath.withPath("/chats/123/event-source");
ServerSentEventBroadcaster broadcaster = sseServer.acquireBroadcaster(resourcePath).get();

// ...construct the payload...
ServerSentEvent event = ServerSentEvent.withEvent("chat-message")
  .data("Hello, world") // often JSON
  .retry(Duration.ofSeconds(5))
  .build();

// ...and send it to all connected clients.
broadcaster.broadcastEvent(event);

Full documentation is available at https://www.soklet.com/docs/server-sent-events.

Author:
Mark Allen

  • Method Details

    • accept

      @Nonnull static HandshakeResult.Accepted accept()
      Vends an instance that indicates a successful handshake, with no additional information provided.
      Returns:
      an instance that indicates a successful handshake

    • acceptWithDefaults

      @Nonnull static HandshakeResult.Accepted.Builder acceptWithDefaults()
      Vends a builder for an instance that indicates a successful handshake.

      The builder supports specifying optional response headers, cookies, and a post-handshake client initialization hook, which is useful to "catch up" in a Last-Event-ID handshake scenario.

      Returns:
      a builder for an instance that indicates a successful handshake

    • rejectWithResponse

      @Nonnull static HandshakeResult.Rejected rejectWithResponse(@Nonnull Response response)
      Vends an instance that indicates a rejected handshake along with a logical response to send to the client.
      Parameters:
      response - the response to send to the client
      Returns:
      an instance that indicates a rejected handshake