Package org.apache.tomcat.websocket

## Class WsSession

- java.lang.Object
- - org.apache.tomcat.websocket.WsSession

- All Implemented Interfaces:
    `java.io.Closeable`, `java.lang.AutoCloseable`, `Session`

      public class WsSession
      extends java.lang.Object
      implements Session

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `WsSession​(Endpoint localEndpoint, WsRemoteEndpointImplBase wsRemoteEndpoint, WsWebSocketContainer wsWebSocketContainer, java.net.URI requestUri, java.util.Map<java.lang.String,​java.util.List<java.lang.String>> requestParameterMap, java.lang.String queryString, java.security.Principal userPrincipal, java.lang.String httpSessionId, java.util.List<Extension> negotiatedExtensions, java.lang.String subProtocol, java.util.Map<java.lang.String,​java.lang.String> pathParameters, boolean secure, EndpointConfig endpointConfig)` | Deprecated. Unused.
    `WsSession​(ClientEndpointHolder clientEndpointHolder, WsRemoteEndpointImplBase wsRemoteEndpoint, WsWebSocketContainer wsWebSocketContainer, java.util.List<Extension> negotiatedExtensions, java.lang.String subProtocol, java.util.Map<java.lang.String,​java.lang.String> pathParameters, boolean secure, ClientEndpointConfig clientEndpointConfig)` | Creates a new WebSocket session for communication between the provided client and remote end points.
    `WsSession​(WsRemoteEndpointImplBase wsRemoteEndpoint, WsWebSocketContainer wsWebSocketContainer, java.net.URI requestUri, java.util.Map<java.lang.String,​java.util.List<java.lang.String>> requestParameterMap, java.lang.String queryString, java.security.Principal userPrincipal, java.lang.String httpSessionId, java.util.List<Extension> negotiatedExtensions, java.lang.String subProtocol, java.util.Map<java.lang.String,​java.lang.String> pathParameters, boolean secure, ServerEndpointConfig serverEndpointConfig)` | Creates a new WebSocket session for communication between the provided server and remote end points.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `<T> void` | `addMessageHandler​(java.lang.Class<T> clazz, MessageHandler.Partial<T> handler)` | Registers a `MessageHandler` for partial incoming messages.
    `<T> void` | `addMessageHandler​(java.lang.Class<T> clazz, MessageHandler.Whole<T> handler)` | Registers a `MessageHandler` for whole incoming messages.
    `void` | `addMessageHandler​(MessageHandler listener)` | Registers a `MessageHandler` for incoming messages.
    `protected static void` | `appendCloseReasonWithTruncation​(java.nio.ByteBuffer msg, java.lang.String reason)` | Use protected so unit tests can access this method directly.
    `protected void` | `checkExpiration()` |
    `void` | `close()` | Close the connection to the remote end point using the code `CloseReason.CloseCodes.NORMAL_CLOSURE` and an empty reason phrase.
    `void` | `close​(CloseReason closeReason)` | Close the connection to the remote end point using the specified code and reason phrase.
    `void` | `doClose​(CloseReason closeReasonMessage, CloseReason closeReasonLocal)` | WebSocket 1.0.
    `void` | `doClose​(CloseReason closeReasonMessage, CloseReason closeReasonLocal, boolean closeSocket)` | WebSocket 1.0.
    `RemoteEndpoint.Async` | `getAsyncRemote()` |
    `RemoteEndpoint.Basic` | `getBasicRemote()` |
    `protected MessageHandler` | `getBinaryMessageHandler()` |
    `WebSocketContainer` | `getContainer()` | Get the container that created this session.
    `java.lang.String` | `getHttpSessionId()` |
    `java.lang.String` | `getId()` | Provides a unique identifier for the session.
    `InstanceManager` | `getInstanceManager()` |
    `Endpoint` | `getLocal()` |
    `int` | `getMaxBinaryMessageBufferSize()` | Get the current maximum buffer size for binary messages.
    `long` | `getMaxIdleTimeout()` | Get the idle timeout for this session.
    `int` | `getMaxTextMessageBufferSize()` | Get the maximum buffer size for text messages.
    `java.util.Set<MessageHandler>` | `getMessageHandlers()` |
    `java.util.List<Extension>` | `getNegotiatedExtensions()` |
    `java.lang.String` | `getNegotiatedSubprotocol()` |
    `java.util.Set<Session>` | `getOpenSessions()` | Obtain the set of open sessions associated with the same local endpoint as this session.
    `java.util.Map<java.lang.String,​java.lang.String>` | `getPathParameters()` |
    `protected MessageHandler.Whole<PongMessage>` | `getPongMessageHandler()` |
    `java.lang.String` | `getProtocolVersion()` |
    `java.lang.String` | `getQueryString()` |
    `java.util.Map<java.lang.String,​java.util.List<java.lang.String>>` | `getRequestParameterMap()` |
    `java.net.URI` | `getRequestURI()` |
    `protected MessageHandler` | `getTextMessageHandler()` |
    `java.security.Principal` | `getUserPrincipal()` |
    `java.util.Map<java.lang.String,​java.lang.Object>` | `getUserProperties()` |
    `boolean` | `isOpen()` |
    `boolean` | `isSecure()` |
    `void` | `onClose​(CloseReason closeReason)` | Called when a close message is received.
    `protected void` | `registerFuture​(org.apache.tomcat.websocket.FutureToSendHandler f2sh)` | Make the session aware of a `FutureToSendHandler` that will need to be forcibly closed if the session closes before the `FutureToSendHandler` completes.
    `void` | `removeMessageHandler​(MessageHandler listener)` |
    `void` | `resume()` | Resumes the reading of the incoming messages.
    `void` | `setMaxBinaryMessageBufferSize​(int max)` | Set the current maximum buffer size for binary messages.
    `void` | `setMaxIdleTimeout​(long timeout)` | Set the idle timeout for this session.
    `void` | `setMaxTextMessageBufferSize​(int max)` | Set the maximum buffer size for text messages.
    `void` | `suspend()` | Suspends the reading of the incoming messages.
    `protected void` | `unregisterFuture​(org.apache.tomcat.websocket.FutureToSendHandler f2sh)` | Remove a `FutureToSendHandler` from the set of tracked instances.
    `protected void` | `updateLastActiveRead()` |
    `protected void` | `updateLastActiveWrite()` |

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### WsSession

          public WsSession​(ClientEndpointHolder clientEndpointHolder,
                           WsRemoteEndpointImplBase wsRemoteEndpoint,
                           WsWebSocketContainer wsWebSocketContainer,
                           java.util.List<Extension> negotiatedExtensions,
                           java.lang.String subProtocol,
                           java.util.Map<java.lang.String,​java.lang.String> pathParameters,
                           boolean secure,
                           ClientEndpointConfig clientEndpointConfig)
                    throws DeploymentException

      Creates a new WebSocket session for communication between the provided client and remote end points. The result of `Thread.getContextClassLoader()` at the time this constructor is called will be used when calling `Endpoint.onClose(Session, CloseReason)`.
      Parameters:
        `clientEndpointHolder` - The end point managed by this code
        `wsRemoteEndpoint` - The other / remote end point
        `wsWebSocketContainer` - The container that created this session
        `negotiatedExtensions` - The agreed extensions to use for this session
        `subProtocol` - The agreed sub-protocol to use for this session
        `pathParameters` - The path parameters associated with the request that initiated this session or `null` if this is a client session
        `secure` - Was this session initiated over a secure connection?
        `clientEndpointConfig` - The configuration information for the client end point
      Throws:
        `DeploymentException` - if an invalid encode is specified

    - #### WsSession

          public WsSession​(WsRemoteEndpointImplBase wsRemoteEndpoint,
                           WsWebSocketContainer wsWebSocketContainer,
                           java.net.URI requestUri,
                           java.util.Map<java.lang.String,​java.util.List<java.lang.String>> requestParameterMap,
                           java.lang.String queryString,
                           java.security.Principal userPrincipal,
                           java.lang.String httpSessionId,
                           java.util.List<Extension> negotiatedExtensions,
                           java.lang.String subProtocol,
                           java.util.Map<java.lang.String,​java.lang.String> pathParameters,
                           boolean secure,
                           ServerEndpointConfig serverEndpointConfig)
                    throws DeploymentException

      Creates a new WebSocket session for communication between the provided server and remote end points. The result of `Thread.getContextClassLoader()` at the time this constructor is called will be used when calling `Endpoint.onClose(Session, CloseReason)`.
      Parameters:
        `wsRemoteEndpoint` - The other / remote end point
        `wsWebSocketContainer` - The container that created this session
        `requestUri` - The URI used to connect to this end point or `null` if this is a client session
        `requestParameterMap` - The parameters associated with the request that initiated this session or `null` if this is a client session
        `queryString` - The query string associated with the request that initiated this session or `null` if this is a client session
        `userPrincipal` - The principal associated with the request that initiated this session or `null` if this is a client session
        `httpSessionId` - The HTTP session ID associated with the request that initiated this session or `null` if this is a client session
        `negotiatedExtensions` - The agreed extensions to use for this session
        `subProtocol` - The agreed sub-protocol to use for this session
        `pathParameters` - The path parameters associated with the request that initiated this session or `null` if this is a client session
        `secure` - Was this session initiated over a secure connection?
        `serverEndpointConfig` - The configuration information for the server end point
      Throws:
        `DeploymentException` - if an invalid encode is specified

    - #### WsSession

          @Deprecated
          public WsSession​(Endpoint localEndpoint,
                           WsRemoteEndpointImplBase wsRemoteEndpoint,
                           WsWebSocketContainer wsWebSocketContainer,
                           java.net.URI requestUri,
                           java.util.Map<java.lang.String,​java.util.List<java.lang.String>> requestParameterMap,
                           java.lang.String queryString,
                           java.security.Principal userPrincipal,
                           java.lang.String httpSessionId,
                           java.util.List<Extension> negotiatedExtensions,
                           java.lang.String subProtocol,
                           java.util.Map<java.lang.String,​java.lang.String> pathParameters,
                           boolean secure,
                           EndpointConfig endpointConfig)
                    throws DeploymentException

      Deprecated.
      Unused. This will be removed in Tomcat 10.1
      Creates a new WebSocket session for communication between the two provided end points. The result of `Thread.getContextClassLoader()` at the time this constructor is called will be used when calling `Endpoint.onClose(Session, CloseReason)`.
      Parameters:
        `localEndpoint` - The end point managed by this code
        `wsRemoteEndpoint` - The other / remote endpoint
        `wsWebSocketContainer` - The container that created this session
        `requestUri` - The URI used to connect to this endpoint or `null` is this is a client session
        `requestParameterMap` - The parameters associated with the request that initiated this session or `null` if this is a client session
        `queryString` - The query string associated with the request that initiated this session or `null` if this is a client session
        `userPrincipal` - The principal associated with the request that initiated this session or `null` if this is a client session
        `httpSessionId` - The HTTP session ID associated with the request that initiated this session or `null` if this is a client session
        `negotiatedExtensions` - The agreed extensions to use for this session
        `subProtocol` - The agreed subprotocol to use for this session
        `pathParameters` - The path parameters associated with the request that initiated this session or `null` if this is a client session
        `secure` - Was this session initiated over a secure connection?
        `endpointConfig` - The configuration information for the endpoint
      Throws:
        `DeploymentException` - if an invalid encode is specified

  - ### Method Detail

    - #### getInstanceManager

          public InstanceManager getInstanceManager()

    - #### getContainer

          public WebSocketContainer getContainer()

      Description copied from interface: `javax.websocket.Session`
      Get the container that created this session.
      Specified by:
        `getContainer` in interface `Session`
      Returns:
        the container that created this session.

    - #### addMessageHandler

          public void addMessageHandler​(MessageHandler listener)

      Description copied from interface: `javax.websocket.Session`
      Registers a `MessageHandler` for incoming messages. Only one `MessageHandler` may be registered for each message type (text, binary, pong). The message type will be derived at runtime from the provided `MessageHandler` instance. It is not always possible to do this so it is better to use `Session.addMessageHandler(Class, javax.websocket.MessageHandler.Partial)` or `Session.addMessageHandler(Class, javax.websocket.MessageHandler.Whole)`.
      Specified by:
        `addMessageHandler` in interface `Session`
      Parameters:
        `listener` - The message handler for a incoming message

    - #### addMessageHandler

          public <T> void addMessageHandler​(java.lang.Class<T> clazz,
                                            MessageHandler.Partial<T> handler)
                                     throws java.lang.IllegalStateException

      Description copied from interface: `javax.websocket.Session`
      Registers a `MessageHandler` for partial incoming messages. Only one `MessageHandler` may be registered for each message type (text or binary, pong messages are never presented as partial messages).
      Specified by:
        `addMessageHandler` in interface `Session`
      Type Parameters:
        `T` - The type of message that the given handler is intended for
      Parameters:
        `clazz` - The Class that implements T
        `handler` - The message handler for a incoming message
      Throws:
        `java.lang.IllegalStateException` - If a message handler has already been registered for the associated message type

    - #### addMessageHandler

          public <T> void addMessageHandler​(java.lang.Class<T> clazz,
                                            MessageHandler.Whole<T> handler)
                                     throws java.lang.IllegalStateException

      Description copied from interface: `javax.websocket.Session`
      Registers a `MessageHandler` for whole incoming messages. Only one `MessageHandler` may be registered for each message type (text, binary, pong).
      Specified by:
        `addMessageHandler` in interface `Session`
      Type Parameters:
        `T` - The type of message that the given handler is intended for
      Parameters:
        `clazz` - The Class that implements T
        `handler` - The message handler for a incoming message
      Throws:
        `java.lang.IllegalStateException` - If a message handler has already been registered for the associated message type

    - #### getMessageHandlers

          public java.util.Set<MessageHandler> getMessageHandlers()

      Specified by:
        `getMessageHandlers` in interface `Session`

    - #### removeMessageHandler

          public void removeMessageHandler​(MessageHandler listener)

      Specified by:
        `removeMessageHandler` in interface `Session`

    - #### getProtocolVersion

          public java.lang.String getProtocolVersion()

      Specified by:
        `getProtocolVersion` in interface `Session`

    - #### getNegotiatedSubprotocol

          public java.lang.String getNegotiatedSubprotocol()

      Specified by:
        `getNegotiatedSubprotocol` in interface `Session`

    - #### getNegotiatedExtensions

          public java.util.List<Extension> getNegotiatedExtensions()

      Specified by:
        `getNegotiatedExtensions` in interface `Session`

    - #### isSecure

          public boolean isSecure()

      Specified by:
        `isSecure` in interface `Session`

    - #### isOpen

          public boolean isOpen()

      Specified by:
        `isOpen` in interface `Session`

    - #### getMaxIdleTimeout

          public long getMaxIdleTimeout()

      Description copied from interface: `javax.websocket.Session`
      Get the idle timeout for this session.
      Specified by:
        `getMaxIdleTimeout` in interface `Session`
      Returns:
        The current idle timeout for this session in milliseconds. Zero or negative values indicate an infinite timeout.

    - #### setMaxIdleTimeout

          public void setMaxIdleTimeout​(long timeout)

      Description copied from interface: `javax.websocket.Session`
      Set the idle timeout for this session.
      Specified by:
        `setMaxIdleTimeout` in interface `Session`
      Parameters:
        `timeout` - The new idle timeout for this session in milliseconds. Zero or negative values indicate an infinite timeout.

    - #### setMaxBinaryMessageBufferSize

          public void setMaxBinaryMessageBufferSize​(int max)

      Description copied from interface: `javax.websocket.Session`
      Set the current maximum buffer size for binary messages.
      Specified by:
        `setMaxBinaryMessageBufferSize` in interface `Session`
      Parameters:
        `max` - The new maximum buffer size in bytes

    - #### getMaxBinaryMessageBufferSize

          public int getMaxBinaryMessageBufferSize()

      Description copied from interface: `javax.websocket.Session`
      Get the current maximum buffer size for binary messages.
      Specified by:
        `getMaxBinaryMessageBufferSize` in interface `Session`
      Returns:
        The current maximum buffer size in bytes

    - #### setMaxTextMessageBufferSize

          public void setMaxTextMessageBufferSize​(int max)

      Description copied from interface: `javax.websocket.Session`
      Set the maximum buffer size for text messages.
      Specified by:
        `setMaxTextMessageBufferSize` in interface `Session`
      Parameters:
        `max` - The new maximum buffer size in characters.

    - #### getMaxTextMessageBufferSize

          public int getMaxTextMessageBufferSize()

      Description copied from interface: `javax.websocket.Session`
      Get the maximum buffer size for text messages.
      Specified by:
        `getMaxTextMessageBufferSize` in interface `Session`
      Returns:
        The maximum buffer size in characters.

    - #### getOpenSessions

          public java.util.Set<Session> getOpenSessions()

      Description copied from interface: `javax.websocket.Session`
      Obtain the set of open sessions associated with the same local endpoint as this session.
      Specified by:
        `getOpenSessions` in interface `Session`
      Returns:
        The set of currently open sessions for the local endpoint that this session is associated with.

    - #### getAsyncRemote

          public RemoteEndpoint.Async getAsyncRemote()

      Specified by:
        `getAsyncRemote` in interface `Session`

    - #### getBasicRemote

          public RemoteEndpoint.Basic getBasicRemote()

      Specified by:
        `getBasicRemote` in interface `Session`

    - #### close

          public void close()
                     throws java.io.IOException

      Description copied from interface: `javax.websocket.Session`
      Close the connection to the remote end point using the code `CloseReason.CloseCodes.NORMAL_CLOSURE` and an empty reason phrase.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `Session`
      Throws:
        `java.io.IOException` - if an I/O error occurs while the WebSocket session is being closed.

    - #### close

          public void close​(CloseReason closeReason)
                     throws java.io.IOException

      Description copied from interface: `javax.websocket.Session`
      Close the connection to the remote end point using the specified code and reason phrase.
      Specified by:
        `close` in interface `Session`
      Parameters:
        `closeReason` - The reason the WebSocket session is being closed.
      Throws:
        `java.io.IOException` - if an I/O error occurs while the WebSocket session is being closed.

    - #### doClose

          public void doClose​(CloseReason closeReasonMessage,
                              CloseReason closeReasonLocal)

      WebSocket 1.0. Section 2.1.5. Need internal close method as spec requires that the local endpoint receives a 1006 on timeout.
      Parameters:
        `closeReasonMessage` - The close reason to pass to the remote endpoint
        `closeReasonLocal` - The close reason to pass to the local endpoint

    - #### doClose

          public void doClose​(CloseReason closeReasonMessage,
                              CloseReason closeReasonLocal,
                              boolean closeSocket)

      WebSocket 1.0. Section 2.1.5. Need internal close method as spec requires that the local endpoint receives a 1006 on timeout.
      Parameters:
        `closeReasonMessage` - The close reason to pass to the remote endpoint
        `closeReasonLocal` - The close reason to pass to the local endpoint
        `closeSocket` - Should the socket be closed immediately rather than waiting for the server to respond

    - #### onClose

          public void onClose​(CloseReason closeReason)

      Called when a close message is received. Should only ever happen once. Also called after a protocol error when the ProtocolHandler needs to force the closing of the connection.
      Parameters:
        `closeReason` - The reason contained within the received close message.

    - #### appendCloseReasonWithTruncation

          protected static void appendCloseReasonWithTruncation​(java.nio.ByteBuffer msg,
                                                                java.lang.String reason)

      Use protected so unit tests can access this method directly.
      Parameters:
        `msg` - The message
        `reason` - The reason

    - #### registerFuture

          protected void registerFuture​(org.apache.tomcat.websocket.FutureToSendHandler f2sh)

      Make the session aware of a `FutureToSendHandler` that will need to be forcibly closed if the session closes before the `FutureToSendHandler` completes.
      Parameters:
        `f2sh` - The handler

    - #### unregisterFuture

          protected void unregisterFuture​(org.apache.tomcat.websocket.FutureToSendHandler f2sh)

      Remove a `FutureToSendHandler` from the set of tracked instances.
      Parameters:
        `f2sh` - The handler

    - #### getRequestURI

          public java.net.URI getRequestURI()

      Specified by:
        `getRequestURI` in interface `Session`

    - #### getRequestParameterMap

          public java.util.Map<java.lang.String,​java.util.List<java.lang.String>> getRequestParameterMap()

      Specified by:
        `getRequestParameterMap` in interface `Session`

    - #### getQueryString

          public java.lang.String getQueryString()

      Specified by:
        `getQueryString` in interface `Session`

    - #### getUserPrincipal

          public java.security.Principal getUserPrincipal()

      Specified by:
        `getUserPrincipal` in interface `Session`

    - #### getPathParameters

          public java.util.Map<java.lang.String,​java.lang.String> getPathParameters()

      Specified by:
        `getPathParameters` in interface `Session`

    - #### getId

          public java.lang.String getId()

      Description copied from interface: `javax.websocket.Session`
      Provides a unique identifier for the session. This identifier should not be relied upon to be generated from a secure random source.
      Specified by:
        `getId` in interface `Session`
      Returns:
        A unique identifier for the session.

    - #### getUserProperties

          public java.util.Map<java.lang.String,​java.lang.Object> getUserProperties()

      Specified by:
        `getUserProperties` in interface `Session`

    - #### getLocal

          public Endpoint getLocal()

    - #### getHttpSessionId

          public java.lang.String getHttpSessionId()

    - #### getTextMessageHandler

          protected MessageHandler getTextMessageHandler()

    - #### getBinaryMessageHandler

          protected MessageHandler getBinaryMessageHandler()

    - #### getPongMessageHandler

          protected MessageHandler.Whole<PongMessage> getPongMessageHandler()

    - #### updateLastActiveRead

          protected void updateLastActiveRead()

    - #### updateLastActiveWrite

          protected void updateLastActiveWrite()

    - #### checkExpiration

          protected void checkExpiration()

    - #### suspend

          public void suspend()

      Suspends the reading of the incoming messages.

    - #### resume

          public void resume()

      Resumes the reading of the incoming messages.