A Handler that may perform the upgrade from HTTP to WebSocket.
The upgrade is performed only if the request matches all the requisites
necessary for the upgrade (which vary upon the HTTP protocol version),
otherwise the request handling is forwarded to the Handler child
of this Handler.
WebSocketUpgradeHandler may be a descendant of a ContextHandler, typically as a direct child, but
possibly also further down the Handler's tree, to enable WebSocket
upgrades for that ContextHandler only.
WebSocketUpgradeHandler may be a descendant of the Server, typically as a direct child, but
possibly also further down the Handler's tree, to enable WebSocket
upgrades for possibly multiple ContextHandlers.
Typical usage:
Server server = ...;
ContextHandler context = new ContextHandler("/app");
// Create the WebSocketUpgradeHandler.
WebSocketUpgradeHandler wsHandler = WebSocketUpgradeHandler.from(server, context, container ->
{
// Map upgrade requests to "/app/ws" to an echo WebSocket endpoint.
container.addMapping("/ws", (upgradeRequest, upgradeResponse, callback) -> new EchoEndPoint());
});
// Link WebSocketUpgradeHandler as a child of ContextHandler.
context.setHandler(wsHandler);
server.setHandler(context);
server.start();
A WebSocketUpgradeHandler is associated with a ServerWebSocketContainer
that is exported as a request context attribute and can be retrieved in this way:
public boolean process(Request request)
{
// Retrieve the WebSocket container from the context attributes.
ServerWebSocketContainer container = (ServerWebSocketContainer)request.getContext().getAttribute(WebSocketContainer.class.getName());
}
| Modifier and Type | Field and Description |
|---|---|
| private final Consumer | |
| private final ServerWebSocketContainer |
| Access | Constructor and Description |
|---|---|
| public | WebSocketUpgradeHandler(ServerWebSocketContainer
the container)ServerWebSocketContainer of this WebSocketUpgradeHandlerCreates a new |
| public | WebSocketUpgradeHandler(ServerWebSocketContainer
the container, Consumer<ServerWebSocketContainer> ServerWebSocketContainer of this WebSocketUpgradeHandlera configurator)Consumer that is called to allow the ServerWebSocketContainer to
be configured during the starting phase of the WebSocketUpgradeHandlerCreates a new |
| Modifier and Type | Method and Description |
|---|---|
| public WebSocketUpgradeHandler | Returns: thisWebSocketUpgradeHandlerthe configuration code configurator)
Deprecated
use
from(Server, ContextHandler, Consumer),
from(Server, Consumer) or getServerWebSocketContainer()
Configures the |
| protected void | doStart()
Overrides org. Starts the managed lifecycle beans in the order they were added. |
| public static WebSocketUpgradeHandler | Returns: a newWebSocketUpgradeHandlerthe server, ContextHandler Server object used to lookup common WebSocket componentsthe context)ContextHandler ancestor of the returned WebSocketUpgradeHandlerCreates a new |
| public static WebSocketUpgradeHandler | Returns: a newWebSocketUpgradeHandlerthe server, ContextHandler Server object used to lookup common WebSocket componentsthe context, Consumer<ServerWebSocketContainer> ContextHandler ancestor of the returned WebSocketUpgradeHandlera configurator)Consumer that is called to allow the ServerWebSocketContainer to
be configured during the starting phase of the WebSocketUpgradeHandlerCreates a new |
| public static WebSocketUpgradeHandler | |
| public static WebSocketUpgradeHandler | Returns: a newWebSocketUpgradeHandlerthe server, Consumer<ServerWebSocketContainer> Server object used to lookup common WebSocket componentsa configurator)Consumer that is called to allow the ServerWebSocketContainer to
be configured during the starting phase of the WebSocketUpgradeHandlerCreates a new |
| public Invocable. | |
| public ServerWebSocketContainer | |
| public boolean | handle(Request
the HTTP request to handle request, Response the HTTP response to handle response, Callback the callback to complete when the handling is complete callback)Overrides org. Implements org. Invoked to handle the passed HTTP request and response. |
| protected boolean |
| _configurator | back to summary |
|---|---|
| private final Consumer<ServerWebSocketContainer> _configurator | |
| _container | back to summary |
|---|---|
| private final ServerWebSocketContainer _container | |
| WebSocketUpgradeHandler | back to summary |
|---|---|
| public WebSocketUpgradeHandler(ServerWebSocketContainer container) Creates a new
| |
| WebSocketUpgradeHandler | back to summary |
|---|---|
| public WebSocketUpgradeHandler(ServerWebSocketContainer container, Consumer<ServerWebSocketContainer> configurator) Creates a new The configurator is invoked every time this
| |
| configure | back to summary |
|---|---|
| public WebSocketUpgradeHandler configure(Consumer<ServerWebSocketContainer> configurator)
Deprecated use Configures the This configuration is applied immediately and lost after a restart.
| |
| doStart | back to summary |
|---|---|
| protected void doStart() throws Exception Overrides org. Doc from org. Starts the managed lifecycle beans in the order they were added.
| |
| from | back to summary |
|---|---|
| public static WebSocketUpgradeHandler from(Server server, ContextHandler context) Creates a new The
| |
| from | back to summary |
|---|---|
| public static WebSocketUpgradeHandler from(Server server, ContextHandler context, Consumer<ServerWebSocketContainer> configurator) Creates a new The The configurator parameter is invoked every time this
| |
| from | back to summary |
|---|---|
| public static WebSocketUpgradeHandler from(Server server) Creates a new The
| |
| from | back to summary |
|---|---|
| public static WebSocketUpgradeHandler from(Server server, Consumer<ServerWebSocketContainer> configurator) Creates a new The The configurator parameter is invoked every time this
| |
| getInvocationType | back to summary |
|---|---|
| public Invocable. Overrides org. Overrides default org.
| |
| getServerWebSocketContainer | back to summary |
|---|---|
| public ServerWebSocketContainer getServerWebSocketContainer() | |
| handle | back to summary |
|---|---|
| public boolean handle(Request request, Response response, Callback callback) throws Exception Overrides org. Implements org. Doc from org. Invoked to handle the passed HTTP request and response. The request is accepted by returning true, then handling must be concluded by completing the passed callback. The handling may be asynchronous, i.e. this method may return true and complete the given callback later, possibly from a different thread. If this method returns false, then the callback must not be invoked and any mutation on the response reversed. Exceptions thrown by this method may be subsequently handled by an error The simplest implementation is:
public boolean handle(Request request, Response response, Callback callback)
{
callback.succeeded();
return true;
}
A HelloWorld implementation is:
public boolean handle(Request request, Response response, Callback callback)
{
response.write(true, ByteBuffer.wrap("Hello World\n".getBytes(StandardCharsets.UTF_8)), callback);
return true;
}
| |
| handle | back to summary |
|---|---|
| protected boolean handle(ServerWebSocketContainer container, Request request, Response response, Callback callback) | |