Package org.eclipse.jetty.websocket.server

Class WebSocketUpgradeHandler

java.lang.Object
org.eclipse.jetty.util.component.AbstractLifeCycle
org.eclipse.jetty.util.component.ContainerLifeCycle
org.eclipse.jetty.server.Handler.Abstract
org.eclipse.jetty.server.Handler.AbstractContainer
org.eclipse.jetty.server.Handler.Wrapper
org.eclipse.jetty.websocket.server.WebSocketUpgradeHandler
All Implemented Interfaces:
Handler, Handler.Container, Handler.Singleton, Request.Handler, Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle, Invocable
public class WebSocketUpgradeHandler extends Handler.Wrapper

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());
 }

  • Constructor Details

  • Method Details

    • from

      public static WebSocketUpgradeHandler from(Server server, ContextHandler context)

      Creates a new WebSocketUpgradeHandler.

      The WebSocketUpgradeHandler is not yet linked to the given ContextHandler, therefore the caller code must ensure that the returned WebSocketUpgradeHandler is a descendant of the given ContextHandler.

      Parameters:
      server - the Server object used to lookup common WebSocket components
      context - the ContextHandler ancestor of the returned WebSocketUpgradeHandler
      Returns:
      a new WebSocketUpgradeHandler
      See Also:

    • from

      public static WebSocketUpgradeHandler from(Server server, ContextHandler context, Consumer<ServerWebSocketContainer> configurator)

      Creates a new WebSocketUpgradeHandler.

      The WebSocketUpgradeHandler is not yet linked to the given ContextHandler, therefore the caller code must ensure that the returned WebSocketUpgradeHandler is a descendant of the given ContextHandler.

      The configurator parameter is invoked every time this WebSocketUpgradeHandler is started, so that the endpoint configuration (removed during the stopping phase) can be re-applied upon restart.

      Parameters:
      server - the Server object used to lookup common WebSocket components
      context - the ContextHandler ancestor of the returned WebSocketUpgradeHandler
      configurator - a Consumer that is called to allow the ServerWebSocketContainer to be configured during the starting phase of the WebSocketUpgradeHandler
      Returns:
      a new WebSocketUpgradeHandler

    • from

      public static WebSocketUpgradeHandler from(Server server)

      Creates a new WebSocketUpgradeHandler.

      The WebSocketUpgradeHandler is not yet linked to the given Server, therefore the caller code must ensure that the returned WebSocketUpgradeHandler is a descendant of the given Server.

      Parameters:
      server - the Server object used to lookup common WebSocket components
      Returns:
      a new WebSocketUpgradeHandler
      See Also:

    • from

      public static WebSocketUpgradeHandler from(Server server, Consumer<ServerWebSocketContainer> configurator)

      Creates a new WebSocketUpgradeHandler.

      The WebSocketUpgradeHandler is not yet linked to the given Server, therefore the caller code must ensure that the returned WebSocketUpgradeHandler is a descendant of the given Server.

      The configurator parameter is invoked every time this WebSocketUpgradeHandler is started, so that the endpoint configuration (removed during the stopping phase) can be re-applied upon restart.

      Parameters:
      server - the Server object used to lookup common WebSocket components
      configurator - a Consumer that is called to allow the ServerWebSocketContainer to be configured during the starting phase of the WebSocketUpgradeHandler
      Returns:
      a new WebSocketUpgradeHandler

    • configure

      @Deprecated public WebSocketUpgradeHandler configure(Consumer<ServerWebSocketContainer> configurator)
      Deprecated.
      use from(Server, ContextHandler, Consumer), from(Server, Consumer) or getServerWebSocketContainer()

      Configures the ServerWebSocketContainer associated with this WebSocketUpgradeHandler.

      This configuration is applied immediately and lost after a restart.

      Parameters:
      configurator - the configuration code
      Returns:
      this WebSocketUpgradeHandler

    • getServerWebSocketContainer

      public ServerWebSocketContainer getServerWebSocketContainer()

    • doStart

      protected void doStart() throws Exception
      Description copied from class: ContainerLifeCycle
      Starts the managed lifecycle beans in the order they were added.
      Overrides:
      doStart in class Handler.Abstract
      Throws:
      AbstractLifeCycle.StopException - If thrown, the lifecycle will immediately be stopped.
      Exception - If there was a problem starting. Will cause a transition to FAILED state

    • handle

      public boolean handle(Request request, Response response, Callback callback) throws Exception
      Description copied from interface: Request.Handler

      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 Request.Handler, if present, otherwise a default HTTP 500 error is generated and the callback completed while writing the error response.

      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;
 }
      Specified by:
      handle in interface Request.Handler
      Overrides:
      handle in class Handler.Wrapper
      Parameters:
      request - the HTTP request to handle
      response - the HTTP response to handle
      callback - the callback to complete when the handling is complete
      Returns:
      True if and only if the request will be handled, a response generated and the callback eventually called. This may occur within the scope of the call to this method, or asynchronously some time later. If false is returned, then this method must not generate a response, nor complete the callback.
      Throws:
      Exception - if there is a failure during the handling. Catchers cannot assume that the callback will be called and thus should attempt to complete the request as if a false had been returned.
      See Also:

    • handle

      protected boolean handle(ServerWebSocketContainer container, Request request, Response response, Callback callback)

    • getInvocationType

      public Invocable.InvocationType getInvocationType()
      Specified by:
      getInvocationType in interface Invocable
      Specified by:
      getInvocationType in interface Request.Handler
      Overrides:
      getInvocationType in class Handler.Wrapper
      Returns:
      The InvocationType of this object