Interface SseServer

All Superinterfaces:

AutoCloseable

public interface SseServer
extends AutoCloseable

A special HTTP server whose only purpose is to provide Server-Sent Event functionality.

A Soklet application which supports Server-Sent Events will be configured with a SseServer. A regular HttpServer is only required if the same application also serves ordinary HTTP Resource Methods.

For example:

// Set up our SSE server
SseServer sseServer = SseServer.fromPort(8081);

// Wire the SSE server into our config
SokletConfig config = SokletConfig.withSseServer(sseServer)
  .build();

// Add .httpServer(HttpServer.fromPort(8080)) if you also serve ordinary HTTP resources

// Run the app
try (Soklet soklet = Soklet.fromConfig(config)) {
  soklet.start();
  System.out.println("Soklet started, press [enter] to exit");
  soklet.awaitShutdown(ShutdownTrigger.ENTER_KEY);
}

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

Author:

Mark Allen

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final class	SseServer.Builder	Builder used to construct a standard implementation of SseServer.
static interface	SseServer.RequestHandler	Request/response processing contract for SseServer implementations.

Method Summary

Modifier and Type	Method	Description
@NonNull Optional<? extends SseBroadcaster>	acquireBroadcaster(@Nullable ResourcePath resourcePath)	Given a ResourcePath that corresponds to a Resource Method annotated with SseEventSource, acquire a SseBroadcaster which is capable of "pushing" messages to all connected Server-Sent Event clients.
default void	close()	AutoCloseable-enabled synonym for stop().
static @NonNull SseServer	fromPort(@NonNull Integer port)	Creates a SseServer configured with the given port and default settings.
void	initialize(@NonNull SokletConfig sokletConfig, @NonNull SseServer.RequestHandler requestHandler)	The Soklet instance which manages this SseServer will invoke this method exactly once at initialization time - this allows Soklet to "talk" to your SseServer.
@NonNull Boolean	isStarted()	Is this SSE server started (that is, able to handle requests from clients)?
void	start()	Starts the SSE server, which makes it able to accept requests from clients.
void	stop()	Stops the SSE server, which makes it unable to accept requests from clients.
static @NonNull SseServer.Builder	withPort(@NonNull Integer port)	Acquires a builder for SseServer instances.

Method Details

start

void start()

Starts the SSE server, which makes it able to accept requests from clients.

If the server is already started, no action is taken.

This method is designed for internal use by Soklet only and should not be invoked elsewhere.

stop

void stop()

Stops the SSE server, which makes it unable to accept requests from clients.

If the server is already stopped, no action is taken.

This method is designed for internal use by Soklet only and should not be invoked elsewhere.

isStarted

@NonNull Boolean isStarted()

Is this SSE server started (that is, able to handle requests from clients)?

Returns:

true if the server is started, false otherwise

close

default void close()
            throws Exception

AutoCloseable-enabled synonym for stop().

This method is designed for internal use by Soklet only and should not be invoked elsewhere.

Specified by:

close in interface AutoCloseable

Throws:

Exception - if an exception occurs while stopping the server

acquireBroadcaster

@NonNull Optional<? extends SseBroadcaster> acquireBroadcaster(@Nullable ResourcePath resourcePath)

Given a ResourcePath that corresponds to a Resource Method annotated with SseEventSource, acquire a SseBroadcaster which is capable of "pushing" messages to all connected Server-Sent Event clients.

When using the default SseServer, Soklet guarantees exactly one SseBroadcaster instance exists per ResourcePath (within the same JVM process). Soklet is responsible for the creation and management of SseBroadcaster instances.

Your code should not hold long-lived references to SseBroadcaster instances (e.g. in a cache or instance variables) - the recommended usage pattern is to invoke acquireBroadcaster(ResourcePath) every time you need a broadcaster reference.

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

Parameters:

resourcePath - the SseEventSource-annotated Resource Method for which to acquire a broadcaster

Returns:

a broadcaster for the given ResourcePath, or Optional.empty() if there is no broadcaster available

initialize

void initialize(@NonNull SokletConfig sokletConfig,
 @NonNull SseServer.RequestHandler requestHandler)

The Soklet instance which manages this SseServer will invoke this method exactly once at initialization time - this allows Soklet to "talk" to your SseServer.

This method is designed for internal use by Soklet only and should not be invoked elsewhere.

Parameters:

sokletConfig - configuration for the Soklet instance that controls this server

requestHandler - a Soklet-internal request handler which takes a SseServer-provided request as input and supplies a MarshaledResponse as output for the SseServer to write back to the client

withPort

static @NonNull SseServer.Builder withPort(@NonNull Integer port)

Acquires a builder for SseServer instances.

Parameters:

port - the port number on which the server should listen

Returns:

the builder

fromPort

static @NonNull SseServer fromPort(@NonNull Integer port)

Creates a SseServer configured with the given port and default settings.

Parameters:

port - the port number on which the server should listen

Returns:

a SseServer instance