org.springframework.web.socket.server.support

## Class AbstractHandshakeHandler

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

All Implemented Interfaces:
  org.springframework.context.Lifecycle, HandshakeHandler

Direct Known Subclasses:
  DefaultHandshakeHandler

    public abstract class AbstractHandshakeHandler
    extends Object
    implements HandshakeHandler, org.springframework.context.Lifecycle

A base class for `HandshakeHandler` implementations, independent from the Servlet API.

Performs initial validation of the WebSocket handshake request - possibly rejecting it through the appropriate HTTP status code - while also allowing its subclasses 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 Jetty 9.0-9.3, Tomcat 7.0.47+ and 8.x, Undertow 1.0-1.3, GlassFish 4.1+, WebLogic 12.1.3+.

Since:
  4.2
Author:
  Rossen Stoyanchev, Juergen Hoeller
See Also:
  `JettyRequestUpgradeStrategy`, `TomcatRequestUpgradeStrategy`, `UndertowRequestUpgradeStrategy`, `GlassFishRequestUpgradeStrategy`, `WebLogicRequestUpgradeStrategy`

### Field Summary

Fields
`protected Log` `logger`

### Constructor Summary

Constructors
`protected` `AbstractHandshakeHandler()` Default constructor that auto-detects and instantiates a `RequestUpgradeStrategy` suitable for the runtime container.
`protected` `AbstractHandshakeHandler(RequestUpgradeStrategy requestUpgradeStrategy)` A constructor that accepts a runtime-specific `RequestUpgradeStrategy`.

### Method Summary

All Methods Instance Methods Concrete Methods
`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(org.springframework.http.server.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(org.springframework.http.server.ServerHttpRequest request, org.springframework.http.server.ServerHttpResponse response, WebSocketHandler wsHandler, Map<String,Object> attributes)` Initiate the handshake.
`protected void` `doStart()`
`protected void` `doStop()`
`protected List<WebSocketExtension>` `filterRequestedExtensions(org.springframework.http.server.ServerHttpRequest request, List<WebSocketExtension> requestedExtensions, List<WebSocketExtension> supportedExtensions)` Filter the list of requested WebSocket extensions.
`RequestUpgradeStrategy` `getRequestUpgradeStrategy()` Return the `RequestUpgradeStrategy` for WebSocket requests.
`String[]` `getSupportedProtocols()` Return the list of supported sub-protocols.
`protected String[]` `getSupportedVersions()`
`protected void` `handleInvalidConnectHeader(org.springframework.http.server.ServerHttpRequest request, org.springframework.http.server.ServerHttpResponse response)`
`protected void` `handleInvalidUpgradeHeader(org.springframework.http.server.ServerHttpRequest request, org.springframework.http.server.ServerHttpResponse response)`
`protected void` `handleWebSocketVersionNotSupported(org.springframework.http.server.ServerHttpRequest request, org.springframework.http.server.ServerHttpResponse response)`
`boolean` `isRunning()`
`protected boolean` `isValidOrigin(org.springframework.http.server.ServerHttpRequest request)` Return whether the request `Origin` header value is valid or not.
`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.
`void` `start()`
`void` `stop()`

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

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

### Field Detail

#### logger

    protected final Log logger

### Constructor Detail

#### AbstractHandshakeHandler

    protected AbstractHandshakeHandler()

Default constructor that auto-detects and instantiates a `RequestUpgradeStrategy` suitable for the runtime container.

Throws:
  `IllegalStateException` - if no `RequestUpgradeStrategy` can be found.

#### AbstractHandshakeHandler

    protected AbstractHandshakeHandler(RequestUpgradeStrategy requestUpgradeStrategy)

A constructor that accepts a runtime-specific `RequestUpgradeStrategy`.

Parameters:
  `requestUpgradeStrategy` - the upgrade strategy to use

### Method Detail

#### getRequestUpgradeStrategy

    public RequestUpgradeStrategy getRequestUpgradeStrategy()

Return the `RequestUpgradeStrategy` for WebSocket requests.

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

#### start

    public void start()

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

#### doStart

    protected void doStart()

#### stop

    public void stop()

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

#### doStop

    protected void doStop()

#### isRunning

    public boolean isRunning()

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

#### doHandshake

    public final boolean doHandshake(org.springframework.http.server.ServerHttpRequest request,
                                     org.springframework.http.server.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` - the 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(org.springframework.http.server.ServerHttpRequest request,
                                              org.springframework.http.server.ServerHttpResponse response)
                                       throws IOException

Throws:
  `IOException`

#### handleInvalidConnectHeader

    protected void handleInvalidConnectHeader(org.springframework.http.server.ServerHttpRequest request,
                                              org.springframework.http.server.ServerHttpResponse response)
                                       throws IOException

Throws:
  `IOException`

#### isWebSocketVersionSupported

    protected boolean isWebSocketVersionSupported(WebSocketHttpHeaders httpHeaders)

#### getSupportedVersions

    protected String[] getSupportedVersions()

#### handleWebSocketVersionNotSupported

    protected void handleWebSocketVersionNotSupported(org.springframework.http.server.ServerHttpRequest request,
                                                      org.springframework.http.server.ServerHttpResponse response)

#### isValidOrigin

    protected boolean isValidOrigin(org.springframework.http.server.ServerHttpRequest request)

Return whether the request `Origin` header value is valid or not. By default, all origins as considered as valid. Consider using an `OriginHandshakeInterceptor` for filtering origins if needed.

#### selectProtocol

    @Nullable
    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(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 if none available

#### filterRequestedExtensions

    protected List<WebSocketExtension> filterRequestedExtensions(org.springframework.http.server.ServerHttpRequest request,
                                                                 List<WebSocketExtension> requestedExtensions,
                                                                 List<WebSocketExtension> supportedExtensions)

Filter the list of requested WebSocket extensions.

As of 4.1, the default implementation of this method filters the list to leave only extensions that are both requested and supported.

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

#### determineUser

    @Nullable
    protected Principal determineUser(org.springframework.http.server.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()`

Subclasses 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` if not available