org.springframework.web.socket.server.support

## Class DefaultHandshakeHandler

- java.lang.Object
- - org.springframework.web.socket.server.support.DefaultHandshakeHandler

- All Implemented Interfaces:
    HandshakeHandler

      public class DefaultHandshakeHandler
      extends Object
      implements HandshakeHandler

  A default `HandshakeHandler` implementation. Performs initial validation of the WebSocket handshake request -- possibly rejecting it through the appropriate HTTP status code -- while also allowing sub-classes to override various parts of the negotiation process (e.g. origin validation, sub-protocol negotiation, extensions negotiation, etc).

  If the negotiation succeeds, the actual upgrade is delegated to a server-specific `RequestUpgradeStrategy`, which will update the response as necessary and initialize the WebSocket. Currently supported servers are Tomcat 7 and 8, Jetty 9, and GlassFish 4.

  Since:
    4.0
  Author:
    Rossen Stoyanchev

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Log` | `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DefaultHandshakeHandler()` Default constructor that autodetects and instantiates a `RequestUpgradeStrategy` suitable for the runtime container.
    `DefaultHandshakeHandler(RequestUpgradeStrategy requestUpgradeStrategy)` A constructor that accepts a runtime-specific `RequestUpgradeStrategy`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected List<String>` | `determineHandlerSupportedProtocols(WebSocketHandler handler)` Determine the sub-protocols supported by the given WebSocketHandler by checking whether it is an instance of `SubProtocolCapable`.
    `protected Principal` | `determineUser(ServerHttpRequest request, WebSocketHandler wsHandler, Map<String,Object> attributes)` A method that can be used to associate a user with the WebSocket session in the process of being established.
    `boolean` | `doHandshake(ServerHttpRequest request, ServerHttpResponse response, WebSocketHandler wsHandler, Map<String,Object> attributes)` Initiate the handshake.
    `protected List<WebSocketExtension>` | `filterRequestedExtensions(ServerHttpRequest request, List<WebSocketExtension> requested, List<WebSocketExtension> supported)` Filter the list of requested WebSocket extensions.
    `String[]` | `getSupportedProtocols()` Return the list of supported sub-protocols.
    `protected String[]` | `getSupportedVersions()`
    `protected void` | `handleInvalidConnectHeader(ServerHttpRequest request, ServerHttpResponse response)`
    `protected void` | `handleInvalidUpgradeHeader(ServerHttpRequest request, ServerHttpResponse response)`
    `protected void` | `handleWebSocketVersionNotSupported(ServerHttpRequest request, ServerHttpResponse response)`
    `protected boolean` | `isValidOrigin(ServerHttpRequest request)`
    `protected boolean` | `isWebSocketVersionSupported(WebSocketHttpHeaders httpHeaders)`
    `protected String` | `selectProtocol(List<String> requestedProtocols, WebSocketHandler webSocketHandler)` Perform the sub-protocol negotiation based on requested and supported sub-protocols.
    `void` | `setSupportedProtocols(String... protocols)` Use this property to configure the list of supported sub-protocols.

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

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

- - ### Field Detail

    - #### logger

          protected Log logger

  - ### Constructor Detail

    - #### DefaultHandshakeHandler

          public DefaultHandshakeHandler()

      Default constructor that autodetects and instantiates a `RequestUpgradeStrategy` suitable for the runtime container.
      Throws:
        `IllegalStateException` - if no `RequestUpgradeStrategy` can be found.

    - #### DefaultHandshakeHandler

          public DefaultHandshakeHandler(RequestUpgradeStrategy requestUpgradeStrategy)

      A constructor that accepts a runtime-specific `RequestUpgradeStrategy`.
      Parameters:
        `requestUpgradeStrategy` - the upgrade strategy to use

  - ### Method Detail

    - #### setSupportedProtocols

          public void setSupportedProtocols(String... protocols)

      Use this property to configure the list of supported sub-protocols. The first configured sub-protocol that matches a client-requested sub-protocol is accepted. If there are no matches the response will not contain a Sec-WebSocket-Protocol header.

      Note that if the WebSocketHandler passed in at runtime is an instance of `SubProtocolCapable` then there is not need to explicitly configure this property. That is certainly the case with the built-in STOMP over WebSocket support. Therefore this property should be configured explicitly only if the WebSocketHandler does not implement `SubProtocolCapable`.

    - #### getSupportedProtocols

          public String[] getSupportedProtocols()

      Return the list of supported sub-protocols.

    - #### doHandshake

          public final boolean doHandshake(ServerHttpRequest request,
                                           ServerHttpResponse response,
                                           WebSocketHandler wsHandler,
                                           Map<String,Object> attributes)
                                    throws HandshakeFailureException

      Description copied from interface: `HandshakeHandler`
      Initiate the handshake.
      Specified by:
        `doHandshake` in interface `HandshakeHandler`
      Parameters:
        `request` - the current request
        `response` - the current response
        `wsHandler` - the handler to process WebSocket messages; see `PerConnectionWebSocketHandler` for providing a handler with per-connection lifecycle.
        `attributes` - attributes from the HTTP handshake to associate with the WebSocket session; the provided attributes are copied, the original map is not used.
      Returns:
        whether the handshake negotiation was successful or not. In either case the response status, headers, and body will have been updated to reflect the result of the negotiation
      Throws:
        `HandshakeFailureException` - thrown when handshake processing failed to complete due to an internal, unrecoverable error, i.e. a server error as opposed to a failure to successfully negotiate the handshake.

    - #### handleInvalidUpgradeHeader

          protected void handleInvalidUpgradeHeader(ServerHttpRequest request,
                                                    ServerHttpResponse response)
                                             throws IOException

      Throws:
        `IOException`

    - #### handleInvalidConnectHeader

          protected void handleInvalidConnectHeader(ServerHttpRequest request,
                                                    ServerHttpResponse response)
                                             throws IOException

      Throws:
        `IOException`

    - #### isWebSocketVersionSupported

          protected boolean isWebSocketVersionSupported(WebSocketHttpHeaders httpHeaders)

    - #### getSupportedVersions

          protected String[] getSupportedVersions()

    - #### handleWebSocketVersionNotSupported

          protected void handleWebSocketVersionNotSupported(ServerHttpRequest request,
                                                            ServerHttpResponse response)

    - #### isValidOrigin

          protected boolean isValidOrigin(ServerHttpRequest request)

    - #### selectProtocol

          protected String selectProtocol(List<String> requestedProtocols,
                                          WebSocketHandler webSocketHandler)

      Perform the sub-protocol negotiation based on requested and supported sub-protocols. For the list of supported sub-protocols, this method first checks if the target WebSocketHandler is a `SubProtocolCapable` and then also checks if any sub-protocols have been explicitly configured with `setSupportedProtocols(String...)`.
      Parameters:
        `requestedProtocols` - the requested sub-protocols
        `webSocketHandler` - the WebSocketHandler that will be used
      Returns:
        the selected protocols or `null`
      See Also:
        `determineHandlerSupportedProtocols(org.springframework.web.socket.WebSocketHandler)`

    - #### determineHandlerSupportedProtocols

          protected final List<String> determineHandlerSupportedProtocols(WebSocketHandler handler)

      Determine the sub-protocols supported by the given WebSocketHandler by checking whether it is an instance of `SubProtocolCapable`.
      Parameters:
        `handler` - the handler to check
      Returns:
        a list of supported protocols or an empty list

    - #### filterRequestedExtensions

          protected List<WebSocketExtension> filterRequestedExtensions(ServerHttpRequest request,
                                                                       List<WebSocketExtension> requested,
                                                                       List<WebSocketExtension> supported)

      Filter the list of requested WebSocket extensions.

      By default all request extensions are returned. The WebSocket server will further compare the requested extensions against the list of supported extensions and return only the ones that are both requested and supported.

      Parameters:
        `request` - the current request
        `requested` - the list of extensions requested by the client
        `supported` - the list of extensions supported by the server
      Returns:
        the selected extensions or an empty list

    - #### determineUser

          protected Principal determineUser(ServerHttpRequest request,
                                            WebSocketHandler wsHandler,
                                            Map<String,Object> attributes)

      A method that can be used to associate a user with the WebSocket session in the process of being established. The default implementation calls `ServerHttpRequest.getPrincipal()`

      Sub-classes can provide custom logic for associating a user with a session, for example for assigning a name to anonymous users (i.e. not fully authenticated).

      Parameters:
        `request` - the handshake request
        `wsHandler` - the WebSocket handler that will handle messages
        `attributes` - handshake attributes to pass to the WebSocket session
      Returns:
        the user for the WebSocket session or `null`