# 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
Constructor
Description
`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

Modifier and Type
Method
Description
`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`
`checkCloseTimeout()`
`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 long`
`getSessionCloseTimeout()`
`protected MessageHandler`
`getTextMessageHandler()`
`Principal`
`getUserPrincipal()`
`Principal`
`getUserPrincipalInternal()`
`Map<String,Object>`
`getUserProperties()`
`boolean`
`isClosed()`
`boolean`
`isOpen()`
`boolean`
`isSecure()`
`void`
`onClose(CloseReason closeReason)`
Called when a close message is received.
`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`
`updateLastActiveRead()`
`protected void`
`updateLastActiveWrite()`

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

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

## Constructor Details

### 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 Details

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

### getSessionCloseTimeout

protected long getSessionCloseTimeout()

### checkCloseTimeout

protected void checkCloseTimeout()

### 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

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

### getUserPrincipalInternal

public Principal getUserPrincipalInternal()

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