Interface ServerSentEventServer

All Superinterfaces:

AutoCloseable

public interface ServerSentEventServer
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 both a Server and a ServerSentEventServer.

For example:

// Set up our HTTP and SSE servers
Server server = Server.withPort(8080).build;
ServerSentEventServer sseServer = ServerSentEventServer.withPort(8081).build();

// Wire servers into our config
SokletConfig config = SokletConfig.withServer(server)
  .serverSentEventServer(sseServer)
  .build();

// Run the app
try (Soklet soklet = Soklet.withConfig(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	ServerSentEventServer.Builder	Builder used to construct a standard implementation of ServerSentEventServer.
static interface	ServerSentEventServer.RequestHandler	Request/response processing contract for ServerSentEventServer implementations.

Method Summary

Modifier and Type	Method	Description
Optional<? extends ServerSentEventBroadcaster>	acquireBroadcaster(ResourcePath resourcePath)	Given a ResourcePath that corresponds to a Resource Method annotated with ServerSentEventSource, acquire a ServerSentEventBroadcaster which is capable of "pushing" messages to all connected Server-Sent Event clients.
default void	close()	AutoCloseable-enabled synonym for stop().
void	initialize(SokletConfig sokletConfig, ServerSentEventServer.RequestHandler requestHandler)	The Soklet instance which manages this ServerSentEventServer will invoke this method exactly once at initialization time - this allows Soklet to "talk" to your ServerSentEventServer.
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 ServerSentEventServer.Builder	withPort(Integer port)	Acquires a builder for ServerSentEventServer 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 ServerSentEventBroadcaster> acquireBroadcaster(@Nullable
 ResourcePath resourcePath)

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

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

Your code should not hold long-lived references to ServerSentEventBroadcaster 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 ServerSentEventSource-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
 ServerSentEventServer.RequestHandler requestHandler)

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

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 ServerSentEventServer-provided request as input and supplies a MarshaledResponse as output for the ServerSentEventServer to write back to the client

withPort

@Nonnull
static ServerSentEventServer.Builder withPort(@Nonnull
 Integer port)

Acquires a builder for ServerSentEventServer instances.

Parameters:

port - the port number on which the server should listen

Returns:

the builder