Package org.apache.tomcat.websocket

## Class WsSession

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

All Implemented Interfaces:
  `Session`, `Closeable`, `AutoCloseable`

    public class WsSession
    extends Object
    implements Session

### Constructor Summary

Constructors
`WsSession​(ClientEndpointHolder clientEndpointHolder, WsRemoteEndpointImplBase wsRemoteEndpoint, WsWebSocketContainer wsWebSocketContainer, List<Extension> negotiatedExtensions, String subProtocol, Map<String,​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, URI requestUri, Map<String,​List<String>> requestParameterMap, String queryString, Principal userPrincipal, String httpSessionId, List<Extension> negotiatedExtensions, String subProtocol, Map<String,​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
`void` `addMessageHandler​(MessageHandler listener)` Registers a `MessageHandler` for incoming messages.
`<T> void` `addMessageHandler​(Class<T> clazz, MessageHandler.Partial<T> handler)` Registers a `MessageHandler` for partial incoming messages.
`<T> void` `addMessageHandler​(Class<T> clazz, MessageHandler.Whole<T> handler)` Registers a `MessageHandler` for whole incoming messages.
`protected static void` `appendCloseReasonWithTruncation​(ByteBuffer msg, 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.
`String` `getHttpSessionId()`
`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.
`Set<MessageHandler>` `getMessageHandlers()`
`List<Extension>` `getNegotiatedExtensions()`
`String` `getNegotiatedSubprotocol()`
`Set<Session>` `getOpenSessions()` Obtain the set of open sessions associated with the same local endpoint as this session.
`Map<String,​String>` `getPathParameters()`
`protected MessageHandler.Whole<PongMessage>` `getPongMessageHandler()`
`String` `getProtocolVersion()`
`String` `getQueryString()`
`Map<String,​List<String>>` `getRequestParameterMap()`
`URI` `getRequestURI()`
`protected MessageHandler` `getTextMessageHandler()`
`Principal` `getUserPrincipal()`
`Map<String,​Object>` `getUserProperties()`
`boolean` `isClosed()`
`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,
                     List<Extension> negotiatedExtensions,
                     String subProtocol,
                     Map<String,​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,
                     URI requestUri,
                     Map<String,​List<String>> requestParameterMap,
                     String queryString,
                     Principal userPrincipal,
                     String httpSessionId,
                     List<Extension> negotiatedExtensions,
                     String subProtocol,
                     Map<String,​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

### Method Detail

#### getInstanceManager

    public InstanceManager getInstanceManager()

#### getContainer

    public WebSocketContainer getContainer()

Description copied from interface: `jakarta.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: `jakarta.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, jakarta.websocket.MessageHandler.Partial)` or `Session.addMessageHandler(Class, jakarta.websocket.MessageHandler.Whole)`.

Specified by:
  `addMessageHandler` in interface `Session`
Parameters:
  `listener` - The message handler for a incoming message

#### addMessageHandler

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

Description copied from interface: `jakarta.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:
  `IllegalStateException` - If a message handler has already been registered for the associated message type

#### addMessageHandler

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

Description copied from interface: `jakarta.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:
  `IllegalStateException` - If a message handler has already been registered for the associated message type

#### getMessageHandlers

    public Set<MessageHandler> getMessageHandlers()

Specified by:
  `getMessageHandlers` in interface `Session`

#### removeMessageHandler

    public void removeMessageHandler​(MessageHandler listener)

Specified by:
  `removeMessageHandler` in interface `Session`

#### getProtocolVersion

    public String getProtocolVersion()

Specified by:
  `getProtocolVersion` in interface `Session`

#### getNegotiatedSubprotocol

    public String getNegotiatedSubprotocol()

Specified by:
  `getNegotiatedSubprotocol` in interface `Session`

#### getNegotiatedExtensions

    public 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`

#### isClosed

    public boolean isClosed()

#### getMaxIdleTimeout

    public long getMaxIdleTimeout()

Description copied from interface: `jakarta.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: `jakarta.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: `jakarta.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: `jakarta.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: `jakarta.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: `jakarta.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 Set<Session> getOpenSessions()

Description copied from interface: `jakarta.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 IOException

Description copied from interface: `jakarta.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 `AutoCloseable`
Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in interface `Session`
Throws:
  `IOException` - if an I/O error occurs while the WebSocket session is being closed.

#### close

    public void close​(CloseReason closeReason)
               throws IOException

Description copied from interface: `jakarta.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:
  `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​(ByteBuffer msg,
                                                          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 URI getRequestURI()

Specified by:
  `getRequestURI` in interface `Session`

#### getRequestParameterMap

    public Map<String,​List<String>> getRequestParameterMap()

Specified by:
  `getRequestParameterMap` in interface `Session`

#### getQueryString

    public String getQueryString()

Specified by:
  `getQueryString` in interface `Session`

#### getUserPrincipal

    public Principal getUserPrincipal()

Specified by:
  `getUserPrincipal` in interface `Session`

#### getPathParameters

    public Map<String,​String> getPathParameters()

Specified by:
  `getPathParameters` in interface `Session`

#### getId

    public String getId()

Description copied from interface: `jakarta.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 Map<String,​Object> getUserProperties()

Specified by:
  `getUserProperties` in interface `Session`

#### getLocal

    public Endpoint getLocal()

#### getHttpSessionId

    public 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.