Package org.apache.tomcat.websocket
Class WsSession
java.lang.Object
org.apache.tomcat.websocket.WsSession
- All Implemented Interfaces:
Closeable,AutoCloseable,Session
-
Constructor Summary
ConstructorsConstructorDescriptionWsSession(Endpoint localEndpoint, 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, EndpointConfig endpointConfig) Deprecated.Unused.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 TypeMethodDescription<T> voidaddMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler) Registers aMessageHandlerfor partial incoming messages.<T> voidaddMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler) Registers aMessageHandlerfor whole incoming messages.voidaddMessageHandler(MessageHandler listener) Registers aMessageHandlerfor incoming messages.protected static voidappendCloseReasonWithTruncation(ByteBuffer msg, String reason) Use protected so unit tests can access this method directly.protected voidvoidclose()Close the connection to the remote end point using the codeCloseReason.CloseCodes.NORMAL_CLOSUREand an empty reason phrase.voidclose(CloseReason closeReason) Close the connection to the remote end point using the specified code and reason phrase.voiddoClose(CloseReason closeReasonMessage, CloseReason closeReasonLocal) WebSocket 1.0.voiddoClose(CloseReason closeReasonMessage, CloseReason closeReasonLocal, boolean closeSocket) WebSocket 1.0.protected MessageHandlerGet the container that created this session.getId()Provides a unique identifier for the session.getLocal()intGet the current maximum buffer size for binary messages.longGet the idle timeout for this session.intGet the maximum buffer size for text messages.Obtain the set of open sessions associated with the same local endpoint as this session.protected MessageHandler.Whole<PongMessage>protected MessageHandlerbooleanisClosed()booleanisOpen()booleanisSecure()voidonClose(CloseReason closeReason) Called when a close message is received.protected voidregisterFuture(org.apache.tomcat.websocket.FutureToSendHandler f2sh) Make the session aware of aFutureToSendHandlerthat will need to be forcibly closed if the session closes before theFutureToSendHandlercompletes.voidremoveMessageHandler(MessageHandler listener) voidresume()Resumes the reading of the incoming messages.voidsetMaxBinaryMessageBufferSize(int max) Set the current maximum buffer size for binary messages.voidsetMaxIdleTimeout(long timeout) Set the idle timeout for this session.voidsetMaxTextMessageBufferSize(int max) Set the maximum buffer size for text messages.voidsuspend()Suspends the reading of the incoming messages.protected voidunregisterFuture(org.apache.tomcat.websocket.FutureToSendHandler f2sh) Remove aFutureToSendHandlerfrom the set of tracked instances.protected voidprotected void
-
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 DeploymentExceptionCreates a new WebSocket session for communication between the provided client and remote end points. The result ofThread.getContextClassLoader()at the time this constructor is called will be used when callingEndpoint.onClose(Session, CloseReason).- Parameters:
clientEndpointHolder- The end point managed by this codewsRemoteEndpoint- The other / remote end pointwsWebSocketContainer- The container that created this sessionnegotiatedExtensions- The agreed extensions to use for this sessionsubProtocol- The agreed sub-protocol to use for this sessionpathParameters- The path parameters associated with the request that initiated this session ornullif this is a client sessionsecure- 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, throws DeploymentExceptionString> pathParameters, boolean secure, ServerEndpointConfig serverEndpointConfig) Creates a new WebSocket session for communication between the provided server and remote end points. The result ofThread.getContextClassLoader()at the time this constructor is called will be used when callingEndpoint.onClose(Session, CloseReason).- Parameters:
wsRemoteEndpoint- The other / remote end pointwsWebSocketContainer- The container that created this sessionrequestUri- The URI used to connect to this end point ornullif this is a client sessionrequestParameterMap- The parameters associated with the request that initiated this session ornullif this is a client sessionqueryString- The query string associated with the request that initiated this session ornullif this is a client sessionuserPrincipal- The principal associated with the request that initiated this session ornullif this is a client sessionhttpSessionId- The HTTP session ID associated with the request that initiated this session ornullif this is a client sessionnegotiatedExtensions- The agreed extensions to use for this sessionsubProtocol- The agreed sub-protocol to use for this sessionpathParameters- The path parameters associated with the request that initiated this session ornullif this is a client sessionsecure- 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, URI requestUri, Map<String, List<String>> requestParameterMap, String queryString, Principal userPrincipal, String httpSessionId, List<Extension> negotiatedExtensions, String subProtocol, Map<String, throws DeploymentExceptionString> pathParameters, boolean secure, EndpointConfig endpointConfig) Deprecated.Unused. This will be removed in Tomcat 10.1Creates a new WebSocket session for communication between the two provided end points. The result ofThread.getContextClassLoader()at the time this constructor is called will be used when callingEndpoint.onClose(Session, CloseReason).- Parameters:
localEndpoint- The end point managed by this codewsRemoteEndpoint- The other / remote endpointwsWebSocketContainer- The container that created this sessionrequestUri- The URI used to connect to this endpoint ornullis this is a client sessionrequestParameterMap- The parameters associated with the request that initiated this session ornullif this is a client sessionqueryString- The query string associated with the request that initiated this session ornullif this is a client sessionuserPrincipal- The principal associated with the request that initiated this session ornullif this is a client sessionhttpSessionId- The HTTP session ID associated with the request that initiated this session ornullif this is a client sessionnegotiatedExtensions- The agreed extensions to use for this sessionsubProtocol- The agreed subprotocol to use for this sessionpathParameters- The path parameters associated with the request that initiated this session ornullif this is a client sessionsecure- Was this session initiated over a secure connection?endpointConfig- The configuration information for the endpoint- Throws:
DeploymentException- if an invalid encode is specified
-
-
Method Details
-
getInstanceManager
-
getContainer
Description copied from interface:javax.websocket.SessionGet the container that created this session.- Specified by:
getContainerin interfaceSession- Returns:
- the container that created this session.
-
addMessageHandler
Description copied from interface:javax.websocket.SessionRegisters aMessageHandlerfor incoming messages. Only oneMessageHandlermay be registered for each message type (text, binary, pong). The message type will be derived at runtime from the providedMessageHandlerinstance. It is not always possible to do this so it is better to useSession.addMessageHandler(Class, javax.websocket.MessageHandler.Partial)orSession.addMessageHandler(Class, javax.websocket.MessageHandler.Whole).- Specified by:
addMessageHandlerin interfaceSession- 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:javax.websocket.SessionRegisters aMessageHandlerfor partial incoming messages. Only oneMessageHandlermay be registered for each message type (text or binary, pong messages are never presented as partial messages).- Specified by:
addMessageHandlerin interfaceSession- Type Parameters:
T- The type of message that the given handler is intended for- Parameters:
clazz- The Class that implements Thandler- 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:javax.websocket.SessionRegisters aMessageHandlerfor whole incoming messages. Only oneMessageHandlermay be registered for each message type (text, binary, pong).- Specified by:
addMessageHandlerin interfaceSession- Type Parameters:
T- The type of message that the given handler is intended for- Parameters:
clazz- The Class that implements Thandler- The message handler for a incoming message- Throws:
IllegalStateException- If a message handler has already been registered for the associated message type
-
getMessageHandlers
- Specified by:
getMessageHandlersin interfaceSession
-
removeMessageHandler
- Specified by:
removeMessageHandlerin interfaceSession
-
getProtocolVersion
- Specified by:
getProtocolVersionin interfaceSession
-
getNegotiatedSubprotocol
- Specified by:
getNegotiatedSubprotocolin interfaceSession
-
getNegotiatedExtensions
- Specified by:
getNegotiatedExtensionsin interfaceSession
-
isSecure
public boolean isSecure() -
isOpen
public boolean isOpen() -
isClosed
public boolean isClosed() -
getMaxIdleTimeout
public long getMaxIdleTimeout()Description copied from interface:javax.websocket.SessionGet the idle timeout for this session.- Specified by:
getMaxIdleTimeoutin interfaceSession- 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.SessionSet the idle timeout for this session.- Specified by:
setMaxIdleTimeoutin interfaceSession- 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.SessionSet the current maximum buffer size for binary messages.- Specified by:
setMaxBinaryMessageBufferSizein interfaceSession- Parameters:
max- The new maximum buffer size in bytes
-
getMaxBinaryMessageBufferSize
public int getMaxBinaryMessageBufferSize()Description copied from interface:javax.websocket.SessionGet the current maximum buffer size for binary messages.- Specified by:
getMaxBinaryMessageBufferSizein interfaceSession- Returns:
- The current maximum buffer size in bytes
-
setMaxTextMessageBufferSize
public void setMaxTextMessageBufferSize(int max) Description copied from interface:javax.websocket.SessionSet the maximum buffer size for text messages.- Specified by:
setMaxTextMessageBufferSizein interfaceSession- Parameters:
max- The new maximum buffer size in characters.
-
getMaxTextMessageBufferSize
public int getMaxTextMessageBufferSize()Description copied from interface:javax.websocket.SessionGet the maximum buffer size for text messages.- Specified by:
getMaxTextMessageBufferSizein interfaceSession- Returns:
- The maximum buffer size in characters.
-
getOpenSessions
Description copied from interface:javax.websocket.SessionObtain the set of open sessions associated with the same local endpoint as this session.- Specified by:
getOpenSessionsin interfaceSession- Returns:
- The set of currently open sessions for the local endpoint that this session is associated with.
-
getAsyncRemote
- Specified by:
getAsyncRemotein interfaceSession
-
getBasicRemote
- Specified by:
getBasicRemotein interfaceSession
-
close
Description copied from interface:javax.websocket.SessionClose the connection to the remote end point using the codeCloseReason.CloseCodes.NORMAL_CLOSUREand an empty reason phrase.- Specified by:
closein interfaceAutoCloseable- Specified by:
closein interfaceCloseable- Specified by:
closein interfaceSession- Throws:
IOException- if an I/O error occurs while the WebSocket session is being closed.
-
close
Description copied from interface:javax.websocket.SessionClose the connection to the remote end point using the specified code and reason phrase.- Specified by:
closein interfaceSession- 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
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 endpointcloseReasonLocal- 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 endpointcloseReasonLocal- The close reason to pass to the local endpointcloseSocket- Should the socket be closed immediately rather than waiting for the server to respond
-
onClose
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
Use protected so unit tests can access this method directly.- Parameters:
msg- The messagereason- The reason
-
registerFuture
protected void registerFuture(org.apache.tomcat.websocket.FutureToSendHandler f2sh) Make the session aware of aFutureToSendHandlerthat will need to be forcibly closed if the session closes before theFutureToSendHandlercompletes.- Parameters:
f2sh- The handler
-
unregisterFuture
protected void unregisterFuture(org.apache.tomcat.websocket.FutureToSendHandler f2sh) Remove aFutureToSendHandlerfrom the set of tracked instances.- Parameters:
f2sh- The handler
-
getRequestURI
- Specified by:
getRequestURIin interfaceSession
-
getRequestParameterMap
- Specified by:
getRequestParameterMapin interfaceSession
-
getQueryString
- Specified by:
getQueryStringin interfaceSession
-
getUserPrincipal
- Specified by:
getUserPrincipalin interfaceSession
-
getPathParameters
- Specified by:
getPathParametersin interfaceSession
-
getId
Description copied from interface:javax.websocket.SessionProvides a unique identifier for the session. This identifier should not be relied upon to be generated from a secure random source. -
getUserProperties
- Specified by:
getUserPropertiesin interfaceSession
-
getLocal
-
getHttpSessionId
-
getTextMessageHandler
-
getBinaryMessageHandler
-
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.
-