org.springframework.web.socket.messaging

## Class SubProtocolWebSocketHandler

- java.lang.Object
- - org.springframework.web.socket.messaging.SubProtocolWebSocketHandler

All Implemented Interfaces:
  org.springframework.context.Lifecycle, org.springframework.context.Phased, org.springframework.context.SmartLifecycle, org.springframework.messaging.MessageHandler, SubProtocolCapable, WebSocketHandler

    public class SubProtocolWebSocketHandler
    extends Object
    implements WebSocketHandler, SubProtocolCapable, org.springframework.messaging.MessageHandler, org.springframework.context.SmartLifecycle

An implementation of `WebSocketHandler` that delegates incoming WebSocket messages to a `SubProtocolHandler` along with a `MessageChannel` to which the sub-protocol handler can send messages from WebSocket clients to the application.

Also an implementation of `MessageHandler` that finds the WebSocket session associated with the `Message` and passes it, along with the message, to the sub-protocol handler to send messages from the application back to the client.

Since:
  4.0
Author:
  Rossen Stoyanchev, Juergen Hoeller, Andy Wilkinson, Artem Bilan

### Nested Class Summary

Nested Classes
`static interface` `SubProtocolWebSocketHandler.Stats` Contract for access to session counters.

### Field Summary

### Fields inherited from interface org.springframework.context.SmartLifecycle

`DEFAULT_PHASE`

### Constructor Summary

Constructors
Constructor and Description
`SubProtocolWebSocketHandler(org.springframework.messaging.MessageChannel clientInboundChannel, org.springframework.messaging.SubscribableChannel clientOutboundChannel)` Create a new `SubProtocolWebSocketHandler` for the given inbound and outbound channels.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addProtocolHandler(SubProtocolHandler handler)` Register a sub-protocol handler.
`void` `afterConnectionClosed(WebSocketSession session, CloseStatus closeStatus)` Invoked after the WebSocket connection has been closed by either side, or after a transport error has occurred.
`void` `afterConnectionEstablished(WebSocketSession session)` Invoked after WebSocket negotiation has succeeded and the WebSocket connection is opened and ready for use.
`protected WebSocketSession` `decorateSession(WebSocketSession session)` Decorate the given `WebSocketSession`, if desired.
`protected SubProtocolHandler` `findProtocolHandler(WebSocketSession session)` Find a `SubProtocolHandler` for the given session.
`SubProtocolHandler` `getDefaultProtocolHandler()` Return the default sub-protocol handler to use.
`Map<String,SubProtocolHandler>` `getProtocolHandlerMap()` Return the sub-protocols keyed by protocol name.
`List<SubProtocolHandler>` `getProtocolHandlers()`
`int` `getSendBufferSizeLimit()` Return the buffer-size limit (number of bytes).
`int` `getSendTimeLimit()` Return the send-time limit (milliseconds).
`SubProtocolWebSocketHandler.Stats` `getStats()` Return a structured object with various session counters.
`String` `getStatsInfo()` Return a String describing internal state and counters.
`List<String>` `getSubProtocols()` Return all supported protocols.
`int` `getTimeToFirstMessage()` Return the maximum time allowed after the WebSocket connection is established and before the first sub-protocol message.
`void` `handleMessage(org.springframework.messaging.Message<?> message)` Handle an outbound Spring Message to a WebSocket client.
`void` `handleMessage(WebSocketSession session, WebSocketMessage<?> message)` Handle an inbound message from a WebSocket client.
`void` `handleTransportError(WebSocketSession session, Throwable exception)` Handle an error from the underlying WebSocket message transport.
`boolean` `isRunning()`
`void` `setDefaultProtocolHandler(SubProtocolHandler defaultProtocolHandler)` Set the `SubProtocolHandler` to use when the client did not request a sub-protocol.
`void` `setProtocolHandlers(List<SubProtocolHandler> protocolHandlers)` Configure one or more handlers to use depending on the sub-protocol requested by the client in the WebSocket handshake request.
`void` `setSendBufferSizeLimit(int sendBufferSizeLimit)` Specify the buffer-size limit (number of bytes).
`void` `setSendTimeLimit(int sendTimeLimit)` Specify the send-time limit (milliseconds).
`void` `setTimeToFirstMessage(int timeToFirstMessage)` Set the maximum time allowed in milliseconds after the WebSocket connection is established and before the first sub-protocol message is received.
`void` `start()`
`void` `stop()`
`void` `stop(Runnable callback)`
`boolean` `supportsPartialMessages()` Whether the WebSocketHandler handles partial messages.
`String` `toString()`

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

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

### Methods inherited from interface org.springframework.context.SmartLifecycle

`getPhase, isAutoStartup`

### Constructor Detail

#### SubProtocolWebSocketHandler

    public SubProtocolWebSocketHandler(org.springframework.messaging.MessageChannel clientInboundChannel,
                                       org.springframework.messaging.SubscribableChannel clientOutboundChannel)

Create a new `SubProtocolWebSocketHandler` for the given inbound and outbound channels.

Parameters:
  `clientInboundChannel` - the inbound `MessageChannel`
  `clientOutboundChannel` - the outbound `MessageChannel`

### Method Detail

#### setProtocolHandlers

    public void setProtocolHandlers(List<SubProtocolHandler> protocolHandlers)

Configure one or more handlers to use depending on the sub-protocol requested by the client in the WebSocket handshake request.

Parameters:
  `protocolHandlers` - the sub-protocol handlers to use

#### getProtocolHandlers

    public List<SubProtocolHandler> getProtocolHandlers()

#### addProtocolHandler

    public void addProtocolHandler(SubProtocolHandler handler)

Register a sub-protocol handler.

#### getProtocolHandlerMap

    public Map<String,SubProtocolHandler> getProtocolHandlerMap()

Return the sub-protocols keyed by protocol name.

#### setDefaultProtocolHandler

    public void setDefaultProtocolHandler(@Nullable
                                          SubProtocolHandler defaultProtocolHandler)

Set the `SubProtocolHandler` to use when the client did not request a sub-protocol.

Parameters:
  `defaultProtocolHandler` - the default handler

#### getDefaultProtocolHandler

    @Nullable
    public SubProtocolHandler getDefaultProtocolHandler()

Return the default sub-protocol handler to use.

#### getSubProtocols

    public List<String> getSubProtocols()

Return all supported protocols.

Specified by:
  `getSubProtocols` in interface `SubProtocolCapable`

#### setSendTimeLimit

    public void setSendTimeLimit(int sendTimeLimit)

Specify the send-time limit (milliseconds).

See Also:
  `ConcurrentWebSocketSessionDecorator`

#### getSendTimeLimit

    public int getSendTimeLimit()

Return the send-time limit (milliseconds).

#### setSendBufferSizeLimit

    public void setSendBufferSizeLimit(int sendBufferSizeLimit)

Specify the buffer-size limit (number of bytes).

See Also:
  `ConcurrentWebSocketSessionDecorator`

#### getSendBufferSizeLimit

    public int getSendBufferSizeLimit()

Return the buffer-size limit (number of bytes).

#### setTimeToFirstMessage

    public void setTimeToFirstMessage(int timeToFirstMessage)

Set the maximum time allowed in milliseconds after the WebSocket connection is established and before the first sub-protocol message is received.

This handler is for WebSocket connections that use a sub-protocol. Therefore, we expect the client to send at least one sub-protocol message in the beginning, or else we assume the connection isn't doing well, e.g. proxy issue, slow network, and can be closed.

By default this is set to `60,000` (1 minute).

Parameters:
  `timeToFirstMessage` - the maximum time allowed in milliseconds
Since:
  5.1
See Also:
  `checkSessions()`

#### getTimeToFirstMessage

    public int getTimeToFirstMessage()

Return the maximum time allowed after the WebSocket connection is established and before the first sub-protocol message.

Since:
  5.1

#### getStatsInfo

    public String getStatsInfo()

Return a String describing internal state and counters. Effectively `toString()` on `getStats()`.

#### getStats

    public SubProtocolWebSocketHandler.Stats getStats()

Return a structured object with various session counters.

Since:
  5.2

#### start

    public final void start()

Specified by:
  `start` in interface `org.springframework.context.Lifecycle`

#### stop

    public final void stop()

Specified by:
  `stop` in interface `org.springframework.context.Lifecycle`

#### stop

    public final void stop(Runnable callback)

Specified by:
  `stop` in interface `org.springframework.context.SmartLifecycle`

#### isRunning

    public final boolean isRunning()

Specified by:
  `isRunning` in interface `org.springframework.context.Lifecycle`

#### afterConnectionEstablished

    public void afterConnectionEstablished(WebSocketSession session)
                                    throws Exception

Description copied from interface: `WebSocketHandler`
Invoked after WebSocket negotiation has succeeded and the WebSocket connection is opened and ready for use.

Specified by:
  `afterConnectionEstablished` in interface `WebSocketHandler`
Throws:
  `Exception` - this method can handle or propagate exceptions; see class-level Javadoc for details.

#### handleMessage

    public void handleMessage(WebSocketSession session,
                              WebSocketMessage<?> message)
                       throws Exception

Handle an inbound message from a WebSocket client.

Specified by:
  `handleMessage` in interface `WebSocketHandler`
Throws:
  `Exception` - this method can handle or propagate exceptions; see class-level Javadoc for details.

#### handleMessage

    public void handleMessage(org.springframework.messaging.Message<?> message)
                       throws org.springframework.messaging.MessagingException

Handle an outbound Spring Message to a WebSocket client.

Specified by:
  `handleMessage` in interface `org.springframework.messaging.MessageHandler`
Throws:
  `org.springframework.messaging.MessagingException`

#### handleTransportError

    public void handleTransportError(WebSocketSession session,
                                     Throwable exception)
                              throws Exception

Description copied from interface: `WebSocketHandler`
Handle an error from the underlying WebSocket message transport.

Specified by:
  `handleTransportError` in interface `WebSocketHandler`
Throws:
  `Exception` - this method can handle or propagate exceptions; see class-level Javadoc for details.

#### afterConnectionClosed

    public void afterConnectionClosed(WebSocketSession session,
                                      CloseStatus closeStatus)
                               throws Exception

Description copied from interface: `WebSocketHandler`
Invoked after the WebSocket connection has been closed by either side, or after a transport error has occurred. Although the session may technically still be open, depending on the underlying implementation, sending messages at this point is discouraged and most likely will not succeed.

Specified by:
  `afterConnectionClosed` in interface `WebSocketHandler`
Throws:
  `Exception` - this method can handle or propagate exceptions; see class-level Javadoc for details.

#### supportsPartialMessages

    public boolean supportsPartialMessages()

Description copied from interface: `WebSocketHandler`
Whether the WebSocketHandler handles partial messages. If this flag is set to `true` and the underlying WebSocket server supports partial messages, then a large WebSocket message, or one of an unknown size may be split and maybe received over multiple calls to `WebSocketHandler.handleMessage(WebSocketSession, WebSocketMessage)`. The flag `WebSocketMessage.isLast()` indicates if the message is partial and whether it is the last part.

Specified by:
  `supportsPartialMessages` in interface `WebSocketHandler`

#### decorateSession

    protected WebSocketSession decorateSession(WebSocketSession session)

Decorate the given `WebSocketSession`, if desired.

The default implementation builds a `ConcurrentWebSocketSessionDecorator` with the configured `send-time limit` and `buffer-size limit`.

Parameters:
  `session` - the original `WebSocketSession`
Returns:
  the decorated `WebSocketSession`, or potentially the given session as-is
Since:
  4.3.13

#### findProtocolHandler

    protected final SubProtocolHandler findProtocolHandler(WebSocketSession session)

Find a `SubProtocolHandler` for the given session.

Parameters:
  `session` - the `WebSocketSession` to find a handler for

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`