org.springframework.web.socket.server.support

Class AbstractHandshakeHandler

java.lang.Object

org.springframework.web.socket.server.support.AbstractHandshakeHandler

All Implemented Interfaces:

Lifecycle, HandshakeHandler

Direct Known Subclasses:

DefaultHandshakeHandler

public abstract class AbstractHandshakeHandler
extends java.lang.Object
implements HandshakeHandler, 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

Modifier and Type	Field and Description
private static java.lang.ClassLoader	classLoader
private static boolean	glassfishWsPresent
private static boolean	jettyWsPresent
protected Log	logger
private RequestUpgradeStrategy	requestUpgradeStrategy
private boolean	running
private java.util.List<java.lang.String>	supportedProtocols
private static boolean	tomcatWsPresent
private static boolean	undertowWsPresent
private static java.nio.charset.Charset	UTF8_CHARSET
private static boolean	weblogicWsPresent
private static boolean	websphereWsPresent

Constructor Summary

Constructors

Modifier	Constructor and Description
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

Modifier and Type	Method and Description
protected java.util.List<java.lang.String>	determineHandlerSupportedProtocols(WebSocketHandler handler) Determine the sub-protocols supported by the given WebSocketHandler by checking whether it is an instance of SubProtocolCapable.
protected java.security.Principal	determineUser(ServerHttpRequest request, WebSocketHandler wsHandler, java.util.Map<java.lang.String,java.lang.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, java.util.Map<java.lang.String,java.lang.Object> attributes) Initiate the handshake.
protected void	doStart()
protected void	doStop()
protected java.util.List<WebSocketExtension>	filterRequestedExtensions(ServerHttpRequest request, java.util.List<WebSocketExtension> requestedExtensions, java.util.List<WebSocketExtension> supportedExtensions) Filter the list of requested WebSocket extensions.
RequestUpgradeStrategy	getRequestUpgradeStrategy() Return the RequestUpgradeStrategy for WebSocket requests.
java.lang.String[]	getSupportedProtocols() Return the list of supported sub-protocols.
protected java.lang.String[]	getSupportedVersions()
protected void	handleInvalidConnectHeader(ServerHttpRequest request, ServerHttpResponse response)
protected void	handleInvalidUpgradeHeader(ServerHttpRequest request, ServerHttpResponse response)
protected void	handleWebSocketVersionNotSupported(ServerHttpRequest request, ServerHttpResponse response)
private static RequestUpgradeStrategy	initRequestUpgradeStrategy()
boolean	isRunning() Check whether this component is currently running.
protected boolean	isValidOrigin(ServerHttpRequest request) Return whether the request Origin header value is valid or not.
protected boolean	isWebSocketVersionSupported(WebSocketHttpHeaders httpHeaders)
protected java.lang.String	selectProtocol(java.util.List<java.lang.String> requestedProtocols, WebSocketHandler webSocketHandler) Perform the sub-protocol negotiation based on requested and supported sub-protocols.
void	setSupportedProtocols(java.lang.String... protocols) Use this property to configure the list of supported sub-protocols.
void	start() Start this component.
void	stop() Stop this component, typically in a synchronous fashion, such that the component is fully stopped upon return of this method.

Methods inherited from class java.lang.Object

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

Field Detail

UTF8_CHARSET

private static final java.nio.charset.Charset UTF8_CHARSET

classLoader

private static final java.lang.ClassLoader classLoader

jettyWsPresent

private static final boolean jettyWsPresent

tomcatWsPresent

private static final boolean tomcatWsPresent

undertowWsPresent

private static final boolean undertowWsPresent

glassfishWsPresent

private static final boolean glassfishWsPresent

weblogicWsPresent

private static final boolean weblogicWsPresent

websphereWsPresent

private static final boolean websphereWsPresent

logger

protected final Log logger

requestUpgradeStrategy

private final RequestUpgradeStrategy requestUpgradeStrategy

supportedProtocols

private final java.util.List<java.lang.String> supportedProtocols

running

private volatile boolean running

Constructor Detail

AbstractHandshakeHandler

protected AbstractHandshakeHandler()

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

Throws:

java.lang.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

initRequestUpgradeStrategy

private static RequestUpgradeStrategy initRequestUpgradeStrategy()

getRequestUpgradeStrategy

public RequestUpgradeStrategy getRequestUpgradeStrategy()

Return the RequestUpgradeStrategy for WebSocket requests.

setSupportedProtocols

public void setSupportedProtocols(java.lang.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 java.lang.String[] getSupportedProtocols()

Return the list of supported sub-protocols.

isRunning

public boolean isRunning()

Description copied from interface: Lifecycle

Check whether this component is currently running.

In the case of a container, this will return true only if all components that apply are currently running.

Specified by:

isRunning in interface Lifecycle

Returns:

whether the component is currently running

start

public void start()

Description copied from interface: Lifecycle

Start this component.

Should not throw an exception if the component is already running.

In the case of a container, this will propagate the start signal to all components that apply.

Specified by:

start in interface Lifecycle

See Also:

SmartLifecycle.isAutoStartup()

doStart

protected void doStart()

stop

public void stop()

Description copied from interface: Lifecycle

Stop this component, typically in a synchronous fashion, such that the component is fully stopped upon return of this method. Consider implementing SmartLifecycle and its stop(Runnable) variant when asynchronous stop behavior is necessary.

Note that this stop notification is not guaranteed to come before destruction: On regular shutdown, Lifecycle beans will first receive a stop notification before the general destruction callbacks are being propagated; however, on hot refresh during a context's lifetime or on aborted refresh attempts, only destroy methods will be called.

Should not throw an exception if the component isn't started yet.

In the case of a container, this will propagate the stop signal to all components that apply.

Specified by:

stop in interface Lifecycle

See Also:

SmartLifecycle.stop(Runnable), DisposableBean.destroy()

doStop

protected void doStop()

doHandshake

public final boolean doHandshake(ServerHttpRequest request,
                                 ServerHttpResponse response,
                                 WebSocketHandler wsHandler,
                                 java.util.Map<java.lang.String,java.lang.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 java.io.IOException

Throws:

java.io.IOException

handleInvalidConnectHeader

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

Throws:

java.io.IOException

isWebSocketVersionSupported

protected boolean isWebSocketVersionSupported(WebSocketHttpHeaders httpHeaders)

getSupportedVersions

protected java.lang.String[] getSupportedVersions()

handleWebSocketVersionNotSupported

protected void handleWebSocketVersionNotSupported(ServerHttpRequest request,
                                                  ServerHttpResponse response)

isValidOrigin

protected boolean isValidOrigin(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

protected java.lang.String selectProtocol(java.util.List<java.lang.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 java.util.List<java.lang.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 java.util.List<WebSocketExtension> filterRequestedExtensions(ServerHttpRequest request,
                                                                       java.util.List<WebSocketExtension> requestedExtensions,
                                                                       java.util.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

protected java.security.Principal determineUser(ServerHttpRequest request,
                                                WebSocketHandler wsHandler,
                                                java.util.Map<java.lang.String,java.lang.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