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

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

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

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.