Top Description Inners Fields Constructors Methods
org.springframework.web.socket.server.support

public abstract Class AbstractHandshakeHandler

extends Object
implements HandshakeHandler, Lifecycle
Class Inheritance
All Implemented Interfaces
org.springframework.context.Lifecycle, org.springframework.web.socket.server.HandshakeHandler
Known Direct Subclasses
org.springframework.web.socket.server.support.DefaultHandshakeHandler
Imports
java.io.IOException, java.nio.charset.StandardCharsets, java.security.Principal, java.util.ArrayList, .Arrays, .Collections, .List, .Map, org.apache.commons.logging.Log, .LogFactory, org.springframework.context.Lifecycle, org.springframework.core.log.LogFormatUtils, org.springframework.http.HttpMethod, .HttpStatus, org.springframework.http.server.ServerHttpRequest, .ServerHttpResponse, org.springframework.lang.Nullable, org.springframework.util.Assert, .ClassUtils, .StringUtils, org.springframework.web.socket.SubProtocolCapable, .WebSocketExtension, .WebSocketHandler, .WebSocketHttpHeaders, org.springframework.web.socket.handler.WebSocketHandlerDecorator, org.springframework.web.socket.server.HandshakeFailureException, .HandshakeHandler, .RequestUpgradeStrategy, org.springframework.web.socket.server.jetty.JettyRequestUpgradeStrategy, org.springframework.web.socket.server.standard.GlassFishRequestUpgradeStrategy, .StandardWebSocketUpgradeStrategy, .TomcatRequestUpgradeStrategy, .UndertowRequestUpgradeStrategy, .WebLogicRequestUpgradeStrategy, .WebSphereRequestUpgradeStrategy
A base class for HandshakeHandler implementations, independent of 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 org.springframework.web.socket.server.RequestUpgradeStrategy, which will update the response as necessary and initialize the WebSocket.

Authors
Rossen Stoyanchev, Juergen Hoeller
Since
4.2
See Also
org.springframework.web.socket.server.jetty.JettyRequestUpgradeStrategy, org.springframework.web.socket.server.standard.TomcatRequestUpgradeStrategy, org.springframework.web.socket.server.standard.UndertowRequestUpgradeStrategy, org.springframework.web.socket.server.standard.GlassFishRequestUpgradeStrategy

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
AbstractHandshakeHandler.TyrusStrategyDelegate

Inner class to avoid a reachable dependency on Tyrus API.

Field Summary

Modifier and TypeField and Description
private static final boolean
glassfishWsPresent

private static final boolean
jettyWsPresent

protected final Log
logger

private final RequestUpgradeStrategy
requestUpgradeStrategy

private volatile boolean
running

private final List<String>
supportedProtocols

private static final boolean
tomcatWsPresent

private static final boolean
undertowWsPresent

private static final boolean
weblogicWsPresent

private static final boolean
websphereWsPresent

Constructor Summary

AccessConstructor and Description
protected
AbstractHandshakeHandler()

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

protected
AbstractHandshakeHandler(RequestUpgradeStrategy
the upgrade strategy to use
requestUpgradeStrategy)

A constructor that accepts a runtime-specific RequestUpgradeStrategy.

Method Summary

Modifier and TypeMethod and Description
protected final List<String>

Returns:

a list of supported protocols, or an empty list if none available
determineHandlerSupportedProtocols(WebSocketHandler
the handler to check
handler)

Determine the sub-protocols supported by the given WebSocketHandler by checking whether it is an instance of SubProtocolCapable.

protected Principal

Returns:

the user for the WebSocket session, or null if not available
determineUser(ServerHttpRequest
the handshake request
request, WebSocketHandler
the WebSocket handler that will handle messages
wsHandler, Map<String, Object>
handshake attributes to pass to the WebSocket session
attributes)

A method that can be used to associate a user with the WebSocket session in the process of being established.

public final boolean
doHandshake(ServerHttpRequest
the current request
request, ServerHttpResponse
the current response
response, WebSocketHandler
the handler to process WebSocket messages; see PerConnectionWebSocketHandler for providing a handler with per-connection lifecycle.
wsHandler, Map<String, Object>
the attributes from the HTTP handshake to associate with the WebSocket session; the provided attributes are copied, the original map is not used.
attributes)

Implements org.springframework.web.socket.server.HandshakeHandler.doHandshake.

Initiate the handshake.

protected void
doStart()

protected void
doStop()

protected List<WebSocketExtension>

Returns:

the selected extensions or an empty list
filterRequestedExtensions(ServerHttpRequest
the current request
request, List<WebSocketExtension>
the list of extensions requested by the client
requestedExtensions, List<WebSocketExtension>
the list of extensions supported by the server
supportedExtensions)

Filter the list of requested WebSocket extensions.

public RequestUpgradeStrategy
getRequestUpgradeStrategy()

Return the RequestUpgradeStrategy for WebSocket requests.

public 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)

private static RequestUpgradeStrategy
initRequestUpgradeStrategy()

public boolean
isRunning()

Implements org.springframework.context.Lifecycle.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 String

Returns:

the selected protocols or null
selectProtocol(List<String>
the requested sub-protocols
requestedProtocols, WebSocketHandler
the WebSocketHandler that will be used
webSocketHandler)

Perform the sub-protocol negotiation based on requested and supported sub-protocols.

public void
setSupportedProtocols(String... protocols)

Use this property to configure the list of supported sub-protocols.

public void
start()

Implements org.springframework.context.Lifecycle.start.

Start this component.

public void
stop()

Implements org.springframework.context.Lifecycle.stop.

Stop this component, typically in a synchronous fashion, such that the component is fully stopped upon return of this method.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

glassfishWsPresentback to summary
private static final boolean glassfishWsPresent
jettyWsPresentback to summary
private static final boolean jettyWsPresent
loggerback to summary
protected final Log logger
requestUpgradeStrategyback to summary
private final RequestUpgradeStrategy requestUpgradeStrategy
runningback to summary
private volatile boolean running
supportedProtocolsback to summary
private final List<String> supportedProtocols
tomcatWsPresentback to summary
private static final boolean tomcatWsPresent
undertowWsPresentback to summary
private static final boolean undertowWsPresent
weblogicWsPresentback to summary
private static final boolean weblogicWsPresent
websphereWsPresentback to summary
private static final boolean websphereWsPresent

Constructor Detail

AbstractHandshakeHandlerback to summary
protected AbstractHandshakeHandler()

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

Exceptions
IllegalStateException:
if no RequestUpgradeStrategy can be found.
AbstractHandshakeHandlerback to summary
protected AbstractHandshakeHandler(RequestUpgradeStrategy requestUpgradeStrategy)

A constructor that accepts a runtime-specific RequestUpgradeStrategy.

Parameters
requestUpgradeStrategy:RequestUpgradeStrategy

the upgrade strategy to use

Method Detail

determineHandlerSupportedProtocolsback to summary
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:WebSocketHandler

the handler to check

Returns:List<String>

a list of supported protocols, or an empty list if none available

determineUserback to summary
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()

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:ServerHttpRequest

the handshake request

wsHandler:WebSocketHandler

the WebSocket handler that will handle messages

attributes:Map<String, Object>

handshake attributes to pass to the WebSocket session

Returns:Principal

the user for the WebSocket session, or null if not available

Annotations
@Nullable
doHandshakeback to summary
public final boolean doHandshake(ServerHttpRequest request, ServerHttpResponse response, WebSocketHandler wsHandler, Map<String, Object> attributes) throws HandshakeFailureException

Implements org.springframework.web.socket.server.HandshakeHandler.doHandshake.

Doc from org.springframework.web.socket.server.HandshakeHandler.doHandshake.

Initiate the handshake.

Parameters
request:ServerHttpRequest

the current request

response:ServerHttpResponse

the current response

wsHandler:WebSocketHandler

the handler to process WebSocket messages; see PerConnectionWebSocketHandler for providing a handler with per-connection lifecycle.

attributes:Map<String, Object>

the attributes from the HTTP handshake to associate with the WebSocket session; the provided attributes are copied, the original map is not used.

Returns:boolean

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

Annotations
@Override
Exceptions
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.
doStartback to summary
protected void doStart()
doStopback to summary
protected void doStop()
filterRequestedExtensionsback to summary
protected List<WebSocketExtension> filterRequestedExtensions(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:ServerHttpRequest

the current request

requestedExtensions:List<WebSocketExtension>

the list of extensions requested by the client

supportedExtensions:List<WebSocketExtension>

the list of extensions supported by the server

Returns:List<WebSocketExtension>

the selected extensions or an empty list

getRequestUpgradeStrategyback to summary
public RequestUpgradeStrategy getRequestUpgradeStrategy()

Return the RequestUpgradeStrategy for WebSocket requests.

getSupportedProtocolsback to summary
public String[] getSupportedProtocols()

Return the list of supported sub-protocols.

getSupportedVersionsback to summary
protected String[] getSupportedVersions()
handleInvalidConnectHeaderback to summary
protected void handleInvalidConnectHeader(ServerHttpRequest request, ServerHttpResponse response) throws IOException
handleInvalidUpgradeHeaderback to summary
protected void handleInvalidUpgradeHeader(ServerHttpRequest request, ServerHttpResponse response) throws IOException
handleWebSocketVersionNotSupportedback to summary
protected void handleWebSocketVersionNotSupported(ServerHttpRequest request, ServerHttpResponse response)
initRequestUpgradeStrategyback to summary
private static RequestUpgradeStrategy initRequestUpgradeStrategy()
isRunningback to summary
public boolean isRunning()

Implements org.springframework.context.Lifecycle.isRunning.

Doc from org.springframework.context.Lifecycle.isRunning.

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.

Returns:boolean

whether the component is currently running

Annotations
@Override
isValidOriginback to summary
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.

isWebSocketVersionSupportedback to summary
protected boolean isWebSocketVersionSupported(WebSocketHttpHeaders httpHeaders)
selectProtocolback to summary
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:List<String>

the requested sub-protocols

webSocketHandler:WebSocketHandler

the WebSocketHandler that will be used

Returns:String

the selected protocols or null

Annotations
@Nullable
See Also
determineHandlerSupportedProtocols(WebSocketHandler)
setSupportedProtocolsback to summary
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 no 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.

startback to summary
public void start()

Implements org.springframework.context.Lifecycle.start.

Doc from org.springframework.context.Lifecycle.start.

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.

Annotations
@Override
stopback to summary
public void stop()

Implements org.springframework.context.Lifecycle.stop.

Doc from org.springframework.context.Lifecycle.stop.

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, a given bean's destroy method will be called without any consideration of stop signals upfront.

Should not throw an exception if the component is not running (not started yet).

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

Annotations
@Override
org.springframework.web.socket.server.support back to summary

private Class AbstractHandshakeHandler.TyrusStrategyDelegate

extends Object
Class Inheritance
  • java.lang.Object
  • org.springframework.web.socket.server.support.AbstractHandshakeHandler.TyrusStrategyDelegate
Inner class to avoid a reachable dependency on Tyrus API.

Constructor Summary

AccessConstructor and Description
private
TyrusStrategyDelegate()

Method Summary

Modifier and TypeMethod and Description
public static RequestUpgradeStrategy
forGlassFish()

public static RequestUpgradeStrategy
forWebLogic()

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

TyrusStrategyDelegateback to summary
private TyrusStrategyDelegate()

Method Detail

forGlassFishback to summary
public static RequestUpgradeStrategy forGlassFish()
forWebLogicback to summary
public static RequestUpgradeStrategy forWebLogic()