Package org.eclipse.jetty.websocket.server

Class ServerWebSocketContainer

java.lang.Object
org.eclipse.jetty.util.component.AbstractLifeCycle
org.eclipse.jetty.util.component.ContainerLifeCycle
org.eclipse.jetty.websocket.server.ServerWebSocketContainer
All Implemented Interfaces:
Request.Handler, Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle, Invocable, Configurable, WebSocketContainer
public class ServerWebSocketContainer extends ContainerLifeCycle implements WebSocketContainer, Configurable, Invocable, Request.Handler

A server-side WebSocket container that allows to map URI paths to WebSocket endpoints and configure WebSocket parameters such as idle timeouts, max WebSocket message sizes, etc.

Direct WebSocket upgrades not mapped to URI paths are possible via upgrade(WebSocketCreator, Request, Response, Callback).

  • Method Details

    • ensure

      public static ServerWebSocketContainer ensure(Server server, ContextHandler contextHandler)

      Returns the ServerWebSocketContainer, ensuring that it is available via get(Context).

      If the ServerWebSocketContainer is not already available, an instance is created, stored to be available via get(Context) and returned.

      This method should be invoked during the setup of the Handler hierarchy.

      Parameters:
      server - the Server object used to lookup common WebSocket components
      contextHandler - the ContextHandler used to store the ServerWebSocketContainer
      Returns:
      a non-null ServerWebSocketContainer

    • ensure

      public static ServerWebSocketContainer ensure(Server server)

      Returns the ServerWebSocketContainer, ensuring that it is available via get(Context).

      If the ServerWebSocketContainer is not already available, an instance is created, stored to be available via get(Context) and returned.

      This method should be invoked during the setup of the Handler hierarchy.

      Parameters:
      server - the Server object used to lookup common WebSocket components and store the ServerWebSocketContainer
      Returns:
      a non-null ServerWebSocketContainer

    • get

      public static ServerWebSocketContainer get(Context context)

      Returns the ServerWebSocketContainer present as the context attribute under the name corresponding to the full qualified name of class WebSocketContainer.

      Parameters:
      context - the Context to look for the attribute
      Returns:
      the ServerWebSocketContainer stored as an attribute, or null if no such attribute is present

    • getExecutor

      public Executor getExecutor()
      Description copied from interface: WebSocketContainer
      The Container provided Executor.
      Specified by:
      getExecutor in interface WebSocketContainer

    • getOpenSessions

      public Collection<Session> getOpenSessions()
      Description copied from interface: WebSocketContainer
      Get the collection of open Sessions being tracked by this container
      Specified by:
      getOpenSessions in interface WebSocketContainer
      Returns:
      the collection of open sessions

    • addSessionListener

      public void addSessionListener(WebSocketSessionListener listener)
      Description copied from interface: WebSocketContainer
      Register a WebSocketSessionListener with the container
      Specified by:
      addSessionListener in interface WebSocketContainer
      Parameters:
      listener - the listener

    • removeSessionListener

      public boolean removeSessionListener(WebSocketSessionListener listener)
      Description copied from interface: WebSocketContainer
      Remove a WebSocketSessionListener from the container
      Specified by:
      removeSessionListener in interface WebSocketContainer
      Parameters:
      listener - the listener
      Returns:
      true if listener was present and removed

    • notifySessionListeners

      public void notifySessionListeners(Consumer<WebSocketSessionListener> consumer)
      Description copied from interface: WebSocketContainer
      Notify the Session Listeners of an event.
      Specified by:
      notifySessionListeners in interface WebSocketContainer
      Parameters:
      consumer - the consumer to call for each tracked listener

    • getIdleTimeout

      public Duration getIdleTimeout()
      Description copied from interface: Configurable
      The duration that a websocket may be idle before being closed by the implementation
      Specified by:
      getIdleTimeout in interface Configurable
      Returns:
      the timeout duration

    • setIdleTimeout

      public void setIdleTimeout(Duration duration)
      Description copied from interface: Configurable
      The duration that a websocket may be idle before being closed by the implementation
      Specified by:
      setIdleTimeout in interface Configurable
      Parameters:
      duration - the timeout duration (may not be null or negative)

    • getInputBufferSize

      public int getInputBufferSize()
      Description copied from interface: Configurable
      The input (read from network layer) buffer size.

      This is the raw read operation buffer size, before the parsing of the websocket frames.

      Specified by:
      getInputBufferSize in interface Configurable
      Returns:
      the raw network buffer input size.

    • setInputBufferSize

      public void setInputBufferSize(int size)
      Description copied from interface: Configurable
      The input (read from network layer) buffer size.
      Specified by:
      setInputBufferSize in interface Configurable
      Parameters:
      size - the size in bytes

    • getOutputBufferSize

      public int getOutputBufferSize()
      Description copied from interface: Configurable
      The output (write to network layer) buffer size.

      This is the raw write operation buffer size and has no relationship to the websocket frame.

      Specified by:
      getOutputBufferSize in interface Configurable
      Returns:
      the raw network buffer output size.

    • setOutputBufferSize

      public void setOutputBufferSize(int size)
      Description copied from interface: Configurable
      The output (write to network layer) buffer size.
      Specified by:
      setOutputBufferSize in interface Configurable
      Parameters:
      size - the size in bytes

    • getMaxBinaryMessageSize

      public long getMaxBinaryMessageSize()
      Description copied from interface: Configurable
      Get the maximum size of a binary message during parsing.

      This is a memory conservation option, memory over this limit will not be allocated by Jetty for handling binary messages. This applies to individual frames, whole message handling, and partial message handling.

      Binary messages over this maximum will result in a close code 1009 StatusCode.MESSAGE_TOO_LARGE

      Specified by:
      getMaxBinaryMessageSize in interface Configurable
      Returns:
      the maximum size of a binary message

    • setMaxBinaryMessageSize

      public void setMaxBinaryMessageSize(long size)
      Description copied from interface: Configurable
      The maximum size of a binary message during parsing/generating.

      Binary messages over this maximum will result in a close code 1009 StatusCode.MESSAGE_TOO_LARGE

      Specified by:
      setMaxBinaryMessageSize in interface Configurable
      Parameters:
      size - the maximum allowed size of a binary message.

    • getMaxTextMessageSize

      public long getMaxTextMessageSize()
      Description copied from interface: Configurable
      Get the maximum size of a text message during parsing.

      This is a memory conservation option, memory over this limit will not be allocated by Jetty for handling text messages. This applies to individual frames, whole message handling, and partial message handling.

      Text messages over this maximum will result in a close code 1009 StatusCode.MESSAGE_TOO_LARGE

      Specified by:
      getMaxTextMessageSize in interface Configurable
      Returns:
      the maximum size of a text message.

    • setMaxTextMessageSize

      public void setMaxTextMessageSize(long size)
      Description copied from interface: Configurable
      The maximum size of a text message during parsing/generating.

      Text messages over this maximum will result in a close code 1009 StatusCode.MESSAGE_TOO_LARGE

      Specified by:
      setMaxTextMessageSize in interface Configurable
      Parameters:
      size - the maximum allowed size of a text message.

    • getMaxFrameSize

      public long getMaxFrameSize()
      Description copied from interface: Configurable
      The maximum payload size of any WebSocket Frame which can be received.
      Specified by:
      getMaxFrameSize in interface Configurable
      Returns:
      the maximum size of a WebSocket Frame.

    • setMaxFrameSize

      public void setMaxFrameSize(long maxFrameSize)
      Description copied from interface: Configurable
      The maximum payload size of any WebSocket Frame which can be received.

      WebSocket Frames over this maximum will result in a close code 1009 StatusCode.MESSAGE_TOO_LARGE

      Specified by:
      setMaxFrameSize in interface Configurable
      Parameters:
      maxFrameSize - the maximum allowed size of a WebSocket Frame.

    • isAutoFragment

      public boolean isAutoFragment()
      Description copied from interface: Configurable
      If true, frames are automatically fragmented to respect the maximum frame size.
      Specified by:
      isAutoFragment in interface Configurable
      Returns:
      whether to automatically fragment incoming WebSocket Frames.

    • setAutoFragment

      public void setAutoFragment(boolean autoFragment)
      Description copied from interface: Configurable
      If set to true, frames are automatically fragmented to respect the maximum frame size.
      Specified by:
      setAutoFragment in interface Configurable
      Parameters:
      autoFragment - whether to automatically fragment incoming WebSocket Frames.

    • getMaxOutgoingFrames

      public int getMaxOutgoingFrames()
      Description copied from interface: Configurable
      Get the maximum number of data frames allowed to be waiting to be sent at any one time. The default value is -1, this indicates there is no limit on how many frames can be queued to be sent by the implementation. If the limit is exceeded, subsequent frames sent are failed with a WritePendingException but the connection is not failed and will remain open.
      Specified by:
      getMaxOutgoingFrames in interface Configurable
      Returns:
      the max number of frames.

    • setMaxOutgoingFrames

      public void setMaxOutgoingFrames(int maxOutgoingFrames)
      Description copied from interface: Configurable
      Set the maximum number of data frames allowed to be waiting to be sent at any one time. The default value is -1, this indicates there is no limit on how many frames can be queued to be sent by the implementation. If the limit is exceeded, subsequent frames sent are failed with a WritePendingException but the connection is not failed and will remain open.
      Specified by:
      setMaxOutgoingFrames in interface Configurable
      Parameters:
      maxOutgoingFrames - the max number of frames.

    • addMapping

      public void addMapping(String pathSpec, WebSocketCreator creator)

      Maps the given pathSpec to the creator of WebSocket endpoints.

      The pathSpec format is that supported by WebSocketMappings.parsePathSpec(String).

      Parameters:
      pathSpec - the pathSpec to associate to the creator
      creator - the creator of WebSocket endpoints

    • addMapping

      public void addMapping(PathSpec pathSpec, WebSocketCreator creator)

      Maps the given pathSpec to the creator of WebSocket endpoints.

      Parameters:
      pathSpec - the pathSpec to associate to the creator
      creator - the creator of WebSocket endpoints

    • handle

      public boolean handle(Request request, Response response, Callback callback) throws WebSocketException

      Matches the given request against existing WebSocket mappings, upgrading to WebSocket if there is a match.

      Direct upgrades without using WebSocket mappings may be performed via upgrade(WebSocketCreator, Request, Response, Callback).

      When true is returned, a response has been sent to the client and the callback has been completed; either because of a successful WebSocket upgrade, or because an error has occurred.

      When false is returned, a response has not been sent to the client, and the callback has not been completed; typically because the request path does not match any existing WebSocket mappings, so that the request can be handled by other Handlers.

      Specified by:
      handle in interface Request.Handler
      Parameters:
      request - the request to handle, possibly a WebSocket upgrade request
      response - the response to handle
      callback - the callback to complete when the handling is complete
      Returns:
      true in case of WebSocket upgrades or failures, false if the request was not handled
      Throws:
      WebSocketException - there is an error during the upgrade
      See Also:

    • upgrade

      public boolean upgrade(WebSocketCreator creator, Request request, Response response, Callback callback) throws WebSocketException

      Upgrades the given request without matching against the WebSocket mappings.

      When true is returned, a response has been sent to the client and the callback has been completed; either because of a successful WebSocket upgrade, or because an error has occurred.

      When false is returned, a response has not been sent to the client, and the callback has not been completed; for example because the request is not a WebSocket upgrade; in this case the caller must arrange to send a response and complete the callback.

      Parameters:
      creator - the creator of the WebSocket endpoint
      request - the request to upgrade, possibly a WebSocket upgrade request
      response - the response
      callback - the callback to complete when the upgrade is complete
      Returns:
      true in case of WebSocket upgrades or failures, false if the request was not upgraded
      Throws:
      WebSocketException - there is an error during the upgrade
      See Also:

    • getInvocationType

      public Invocable.InvocationType getInvocationType()
      Specified by:
      getInvocationType in interface Invocable
      Specified by:
      getInvocationType in interface Request.Handler
      Returns:
      the invocation type, typically blocking or non-blocking, of this container
      See Also:

    • setInvocationType

      public void setInvocationType(Invocable.InvocationType invocationType)

      Sets the invocation type of this container.

      The invocation type may be set to Invocable.InvocationType.NON_BLOCKING when it is known that application code in the listener methods or annotated methods of the WebSocket endpoint does not use blocking APIs.

      Setting the invocation type to Invocable.InvocationType.NON_BLOCKING, but then using blocking APIs in the WebSocket endpoint may result in a server lockup.

      By default Invocable.InvocationType.BLOCKING is returned, assuming that application code in the WebSocket endpoint uses blocking APIs.

      Parameters:
      invocationType - the invocation type of this container