org.springframework.web.socket.sockjs.transport.session

## Class AbstractSockJsSession

- java.lang.Object
- - org.springframework.web.socket.sockjs.transport.session.AbstractSockJsSession

- All Implemented Interfaces:
    SockJsSession, WebSocketSession
  Direct Known Subclasses:
    AbstractHttpSockJsSession, WebSocketServerSockJsSession

      public abstract class AbstractSockJsSession
      extends Object
      implements SockJsSession

  An abstract base class for SockJS sessions implementing `SockJsSession`.
  Since:
    4.0
  Author:
    Rossen Stoyanchev, Sam Brannen

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DISCONNECTED_CLIENT_LOG_CATEGORY` Log category to use on network IO exceptions after a client has gone away.
    `protected static Log` | `disconnectedClientLogger` Separate logger to use on network IO failure after a client has gone away.
    `protected Log` | `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractSockJsSession(String id, SockJsServiceConfig config, WebSocketHandler handler, Map<String,Object> attributes)` Create a new instance.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `cancelHeartbeat()`
    `void` | `close()` Close the WebSocket connection with status 1000, i.e.
    `void` | `close(CloseStatus status)` Close the WebSocket connection with the given close status.
    `void` | `delegateConnectionClosed(CloseStatus status)` Invoked in reaction to the underlying connection being closed by the remote side (or the WebSocket container) in order to perform cleanup and notify the `WebSocketHandler`.
    `void` | `delegateConnectionEstablished()`
    `void` | `delegateError(Throwable ex)`
    `void` | `delegateMessages(String[] messages)`
    `void` | `disableHeartbeat()` Disable SockJS heartbeat, presumably because a higher level protocol has heartbeats enabled for the session.
    `protected abstract void` | `disconnect(CloseStatus status)` Actually close the underlying WebSocket session or in the case of HTTP transports complete the underlying request.
    `Map<String,Object>` | `getAttributes()` Return the map with attributes associated with the WebSocket session.
    `String` | `getId()` Return a unique session identifier.
    `SockJsServiceConfig` | `getSockJsServiceConfig()`
    `long` | `getTimeSinceLastActive()` Return the time (in ms) since the session was last active, or otherwise if the session is new, then the time since the session was created.
    `abstract boolean` | `isActive()` Polling and Streaming sessions periodically close the current HTTP request and wait for the next request to come through.
    `boolean` | `isClosed()`
    `boolean` | `isNew()`
    `boolean` | `isOpen()` Return whether the connection is still open.
    `protected void` | `scheduleHeartbeat()`
    `void` | `sendHeartbeat()`
    `void` | `sendMessage(WebSocketMessage<?> message)` Send a WebSocket message either `TextMessage` or `BinaryMessage`.
    `protected abstract void` | `sendMessageInternal(String message)`
    `String` | `toString()`
    `void` | `tryCloseWithSockJsTransportError(Throwable ex, CloseStatus closeStatus)` Close due to error arising from SockJS transport handling.
    `protected void` | `updateLastActiveTime()` Should be invoked whenever the session becomes inactive.
    `protected void` | `writeFrame(SockJsFrame frame)` For internal use within a TransportHandler and the (TransportHandler-specific) session class.
    `protected abstract void` | `writeFrameInternal(SockJsFrame frame)`

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

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

    - ### Methods inherited from interface org.springframework.web.socket.WebSocketSession

      `getAcceptedProtocol, getBinaryMessageSizeLimit, getExtensions, getHandshakeHeaders, getLocalAddress, getPrincipal, getRemoteAddress, getTextMessageSizeLimit, getUri, setBinaryMessageSizeLimit, setTextMessageSizeLimit`

- - ### Field Detail

    - #### logger

          protected final Log logger

    - #### DISCONNECTED_CLIENT_LOG_CATEGORY

          public static final String DISCONNECTED_CLIENT_LOG_CATEGORY

      Log category to use on network IO exceptions after a client has gone away.

      The Servlet API does not provide notifications when a client disconnects; see SERVLET_SPEC-44. Therefore network IO failures may occur simply because a client has gone away, and that can fill the logs with unnecessary stack traces.

      We make a best effort to identify such network failures, on a per-server basis, and log them under a separate log category. A simple one-line message is logged at DEBUG level, while a full stack trace is shown at TRACE level.

      See Also:
        `disconnectedClientLogger`, Constant Field Values

    - #### disconnectedClientLogger

          protected static final Log disconnectedClientLogger

      Separate logger to use on network IO failure after a client has gone away.
      See Also:
        `DISCONNECTED_CLIENT_LOG_CATEGORY`

  - ### Constructor Detail

    - #### AbstractSockJsSession

          public AbstractSockJsSession(String id,
                                       SockJsServiceConfig config,
                                       WebSocketHandler handler,
                                       Map<String,Object> attributes)

      Create a new instance.
      Parameters:
        `id` - the session ID
        `config` - SockJS service configuration options
        `handler` - the recipient of SockJS messages
        `attributes` - attributes from the HTTP handshake to associate with the WebSocket session; the provided attributes are copied, the original map is not used.

  - ### Method Detail

    - #### getId

          public String getId()

      Description copied from interface: `WebSocketSession`
      Return a unique session identifier.
      Specified by:
        `getId` in interface `WebSocketSession`

    - #### getSockJsServiceConfig

          public SockJsServiceConfig getSockJsServiceConfig()

    - #### getAttributes

          public Map<String,Object> getAttributes()

      Description copied from interface: `WebSocketSession`
      Return the map with attributes associated with the WebSocket session.

      When the WebSocketSession is created, on the server side, the map can be through a `HandshakeInterceptor`. On the client side, the map can be populated by passing attributes to the `WebSocketClient` handshake methods.

      Specified by:
        `getAttributes` in interface `WebSocketSession`

    - #### isNew

          public boolean isNew()

    - #### isOpen

          public boolean isOpen()

      Description copied from interface: `WebSocketSession`
      Return whether the connection is still open.
      Specified by:
        `isOpen` in interface `WebSocketSession`

    - #### isClosed

          public boolean isClosed()

    - #### isActive

          public abstract boolean isActive()

      Polling and Streaming sessions periodically close the current HTTP request and wait for the next request to come through. During this "downtime" the session is still open but inactive and unable to send messages and therefore has to buffer them temporarily. A WebSocket session by contrast is stateful and remain active until closed.

    - #### getTimeSinceLastActive

          public long getTimeSinceLastActive()

      Description copied from interface: `SockJsSession`
      Return the time (in ms) since the session was last active, or otherwise if the session is new, then the time since the session was created.
      Specified by:
        `getTimeSinceLastActive` in interface `SockJsSession`

    - #### updateLastActiveTime

          protected void updateLastActiveTime()

      Should be invoked whenever the session becomes inactive.

    - #### disableHeartbeat

          public void disableHeartbeat()

      Description copied from interface: `SockJsSession`
      Disable SockJS heartbeat, presumably because a higher level protocol has heartbeats enabled for the session. It is not recommended to disable this otherwise as it helps proxies to know the connection is not hanging.
      Specified by:
        `disableHeartbeat` in interface `SockJsSession`

    - #### delegateConnectionEstablished

          public void delegateConnectionEstablished()
                                             throws Exception

      Throws:
        `Exception`

    - #### delegateMessages

          public void delegateMessages(String[] messages)
                                throws SockJsMessageDeliveryException

      Throws:
        `SockJsMessageDeliveryException`

    - #### delegateConnectionClosed

          public final void delegateConnectionClosed(CloseStatus status)
                                              throws Exception

      Invoked in reaction to the underlying connection being closed by the remote side (or the WebSocket container) in order to perform cleanup and notify the `WebSocketHandler`. This is in contrast to `close()` that pro-actively closes the connection.
      Throws:
        `Exception`

    - #### delegateError

          public void delegateError(Throwable ex)
                             throws Exception

      Throws:
        `Exception`

    - #### sendMessage

          public final void sendMessage(WebSocketMessage<?> message)
                                 throws IOException

      Description copied from interface: `WebSocketSession`
      Send a WebSocket message either `TextMessage` or `BinaryMessage`.
      Specified by:
        `sendMessage` in interface `WebSocketSession`
      Throws:
        `IOException`

    - #### sendMessageInternal

          protected abstract void sendMessageInternal(String message)
                                               throws IOException

      Throws:
        `IOException`

    - #### close

          public final void close()
                           throws IOException

      Close the WebSocket connection with status 1000, i.e. equivalent to:

           session.close(CloseStatus.NORMAL);

      Performs cleanup and notifies the `WebSocketHandler`.

      Specified by:
        `close` in interface `WebSocketSession`
      Throws:
        `IOException`

    - #### close

          public final void close(CloseStatus status)
                           throws IOException

      Close the WebSocket connection with the given close status.

      Performs cleanup and notifies the `WebSocketHandler`.

      Specified by:
        `close` in interface `WebSocketSession`
      Throws:
        `IOException`

    - #### disconnect

          protected abstract void disconnect(CloseStatus status)
                                      throws IOException

      Actually close the underlying WebSocket session or in the case of HTTP transports complete the underlying request.
      Throws:
        `IOException`

    - #### tryCloseWithSockJsTransportError

          public void tryCloseWithSockJsTransportError(Throwable ex,
                                                       CloseStatus closeStatus)

      Close due to error arising from SockJS transport handling.

    - #### writeFrame

          protected void writeFrame(SockJsFrame frame)
                             throws SockJsTransportFailureException

      For internal use within a TransportHandler and the (TransportHandler-specific) session class.
      Throws:
        `SockJsTransportFailureException`

    - #### writeFrameInternal

          protected abstract void writeFrameInternal(SockJsFrame frame)
                                              throws IOException

      Throws:
        `IOException`

    - #### sendHeartbeat

          public void sendHeartbeat()
                             throws SockJsTransportFailureException

      Throws:
        `SockJsTransportFailureException`

    - #### scheduleHeartbeat

          protected void scheduleHeartbeat()

    - #### cancelHeartbeat

          protected void cancelHeartbeat()

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`