Package org.apache.tomcat.websocket

Class WsSession

  • All Implemented Interfaces:
    Session, java.io.Closeable, java.lang.AutoCloseable
    public class WsSession
extends java.lang.Object
implements Session

    • 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

      • addMessageHandler

        public <T> void addMessageHandler​(java.lang.Class<T> clazz,
                                  MessageHandler.Partial<T> handler)
                           throws java.lang.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:
        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: 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:
        java.lang.IllegalStateException - If a message handler has already been registered for the associated message type

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

      • getOpenSessions

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

      • close

        public void close()
           throws java.io.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 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: 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:
        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: 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 java.util.Map<java.lang.String,​java.lang.Object> getUserProperties()
        Specified by:
        getUserProperties in interface Session

      • getHttpSessionId

        public java.lang.String getHttpSessionId()

      • getTextMessageHandler

        protected MessageHandler getTextMessageHandler()

      • getBinaryMessageHandler

        protected MessageHandler getBinaryMessageHandler()

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