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:
org.eclipse.jetty.server.Handler, org.eclipse.jetty.server.Handler.Container, org.eclipse.jetty.server.Handler.Singleton, org.eclipse.jetty.server.Request.Handler, org.eclipse.jetty.util.component.Container, org.eclipse.jetty.util.component.Destroyable, org.eclipse.jetty.util.component.Dumpable, org.eclipse.jetty.util.component.Dumpable.DumpableContainer, org.eclipse.jetty.util.component.LifeCycle, org.eclipse.jetty.util.thread.Invocable
public class WebSocketUpgradeHandler extends org.eclipse.jetty.server.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());
}

  • Nested Class Summary

    Nested classes/interfaces inherited from class org.eclipse.jetty.server.Handler.Abstract

    org.eclipse.jetty.server.Handler.Abstract.NonBlocking

    Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

    org.eclipse.jetty.util.component.AbstractLifeCycle.AbstractLifeCycleListener, org.eclipse.jetty.util.component.AbstractLifeCycle.StopException

    Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.Container

    org.eclipse.jetty.util.component.Container.InheritedListener, org.eclipse.jetty.util.component.Container.Listener

    Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.Dumpable

    org.eclipse.jetty.util.component.Dumpable.DumpableContainer

    Nested classes/interfaces inherited from interface org.eclipse.jetty.server.Handler

    org.eclipse.jetty.server.Handler.Abstract, org.eclipse.jetty.server.Handler.AbstractContainer, org.eclipse.jetty.server.Handler.Collection, org.eclipse.jetty.server.Handler.Container, org.eclipse.jetty.server.Handler.Sequence, org.eclipse.jetty.server.Handler.Singleton, org.eclipse.jetty.server.Handler.Wrapper

    Nested classes/interfaces inherited from interface org.eclipse.jetty.util.thread.Invocable

    org.eclipse.jetty.util.thread.Invocable.Callable, org.eclipse.jetty.util.thread.Invocable.InvocationType, org.eclipse.jetty.util.thread.Invocable.ReadyTask, org.eclipse.jetty.util.thread.Invocable.Task

    Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

    org.eclipse.jetty.util.component.LifeCycle.Listener

    Nested classes/interfaces inherited from interface org.eclipse.jetty.server.Request.Handler

    org.eclipse.jetty.server.Request.Handler.AbortException

  • Field Summary

    Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

    FAILED, STARTED, STARTING, STOPPED, STOPPING

    Fields inherited from interface org.eclipse.jetty.util.component.Dumpable

    KEY

    Fields inherited from interface org.eclipse.jetty.util.thread.Invocable

    __nonBlocking, NOOP

  • Constructor Summary

    Constructors
    Constructor
    Description
    WebSocketUpgradeHandler(ServerWebSocketContainer container)
    Creates a new WebSocketUpgradeHandler with the given ServerWebSocketContainer.
    WebSocketUpgradeHandler(ServerWebSocketContainer container, Consumer<ServerWebSocketContainer> configurator)
    Creates a new WebSocketUpgradeHandler with the given ServerWebSocketContainer and the given configurator.

  • Method Summary

    Modifier and Type
    Method
    Description
    WebSocketUpgradeHandler
    configure(Consumer<ServerWebSocketContainer> configurator)
    Deprecated.
    use from(Server, ContextHandler, Consumer), from(Server, Consumer) or getServerWebSocketContainer()
    protected void
    doStart()
     
    static WebSocketUpgradeHandler
    from(org.eclipse.jetty.server.Server server)
    Creates a new WebSocketUpgradeHandler.
    static WebSocketUpgradeHandler
    from(org.eclipse.jetty.server.Server server, Consumer<ServerWebSocketContainer> configurator)
    Creates a new WebSocketUpgradeHandler.
    static WebSocketUpgradeHandler
    from(org.eclipse.jetty.server.Server server, org.eclipse.jetty.server.handler.ContextHandler context)
    Creates a new WebSocketUpgradeHandler.
    static WebSocketUpgradeHandler
    from(org.eclipse.jetty.server.Server server, org.eclipse.jetty.server.handler.ContextHandler context, Consumer<ServerWebSocketContainer> configurator)
    Creates a new WebSocketUpgradeHandler.
    org.eclipse.jetty.util.thread.Invocable.InvocationType
    getInvocationType()
     
    ServerWebSocketContainer
    getServerWebSocketContainer()
     
    boolean
    handle(org.eclipse.jetty.server.Request request, org.eclipse.jetty.server.Response response, org.eclipse.jetty.util.Callback callback)
     
    protected boolean
    handle(ServerWebSocketContainer container, org.eclipse.jetty.server.Request request, org.eclipse.jetty.server.Response response, org.eclipse.jetty.util.Callback callback)
     

    Methods inherited from class org.eclipse.jetty.server.Handler.Wrapper

    getHandler, setHandler

    Methods inherited from class org.eclipse.jetty.server.Handler.AbstractContainer

    findContainerOf, getDescendant, getDescendants, isDynamic, setDynamic, setServer

    Methods inherited from class org.eclipse.jetty.server.Handler.Abstract

    destroy, doStop, getServer

    Methods inherited from class org.eclipse.jetty.util.component.ContainerLifeCycle

    addBean, addBean, addEventListener, addManaged, contains, dump, dump, dump, dumpObjects, dumpStdErr, getBean, getBeans, getBeans, getContainedBeans, getContainedBeans, installBean, installBean, isAuto, isManaged, isUnmanaged, manage, removeBean, removeBeans, removeEventListener, setBeans, start, stop, unmanage, updateBean, updateBean, updateBeans, updateBeans

    Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

    getEventListeners, getState, getState, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, setEventListeners, start, stop, toString

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.eclipse.jetty.util.component.Container

    getCachedBeans, getEventListeners

    Methods inherited from interface org.eclipse.jetty.util.component.Destroyable

    destroy

    Methods inherited from interface org.eclipse.jetty.util.component.Dumpable

    dumpSelf

    Methods inherited from interface org.eclipse.jetty.util.component.Dumpable.DumpableContainer

    isDumpable

    Methods inherited from interface org.eclipse.jetty.server.Handler

    getServer, setServer

    Methods inherited from interface org.eclipse.jetty.server.Handler.Container

    getContainer, getDescendant, getDescendants, getDescendants

    Methods inherited from interface org.eclipse.jetty.server.Handler.Singleton

    getHandlers, getTail, insertHandler, setHandler

    Methods inherited from interface org.eclipse.jetty.util.component.LifeCycle

    addEventListener, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeEventListener, start, stop

  • Constructor Details

  • Method Details

    • from

      public static WebSocketUpgradeHandler from(org.eclipse.jetty.server.Server server, org.eclipse.jetty.server.handler.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(org.eclipse.jetty.server.Server server, org.eclipse.jetty.server.handler.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(org.eclipse.jetty.server.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(org.eclipse.jetty.server.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
      Overrides:
      doStart in class org.eclipse.jetty.server.Handler.Abstract
      Throws:
      Exception

    • handle

      public boolean handle(org.eclipse.jetty.server.Request request, org.eclipse.jetty.server.Response response, org.eclipse.jetty.util.Callback callback) throws Exception
      Specified by:
      handle in interface org.eclipse.jetty.server.Request.Handler
      Overrides:
      handle in class org.eclipse.jetty.server.Handler.Wrapper
      Throws:
      Exception

    • handle

      protected boolean handle(ServerWebSocketContainer container, org.eclipse.jetty.server.Request request, org.eclipse.jetty.server.Response response, org.eclipse.jetty.util.Callback callback)

    • getInvocationType

      public org.eclipse.jetty.util.thread.Invocable.InvocationType getInvocationType()
      Specified by:
      getInvocationType in interface org.eclipse.jetty.util.thread.Invocable
      Specified by:
      getInvocationType in interface org.eclipse.jetty.server.Request.Handler
      Overrides:
      getInvocationType in class org.eclipse.jetty.server.Handler.Wrapper