Package org.eclipse.jetty.websocket.server

Class ServerWebSocketContainer

java.lang.Object

org.eclipse.jetty.util.component.AbstractLifeCycle

org.eclipse.jetty.util.component.ContainerLifeCycle

org.eclipse.jetty.websocket.server.ServerWebSocketContainer

All Implemented Interfaces:

Request.Handler, Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle, Invocable, Configurable, WebSocketContainer

public class ServerWebSocketContainer
extends ContainerLifeCycle
implements WebSocketContainer, Configurable, Invocable, Request.Handler

A server-side WebSocket container that allows to map URI paths to WebSocket endpoints and configure WebSocket parameters such as idle timeouts, max WebSocket message sizes, etc.

Direct WebSocket upgrades not mapped to URI paths are possible via upgrade(WebSocketCreator, Request, Response, Callback).

Nested Class Summary

Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

AbstractLifeCycle.AbstractLifeCycleListener, AbstractLifeCycle.StopException

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.Container

Container.InheritedListener, Container.Listener

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.Dumpable

Dumpable.DumpableContainer

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.thread.Invocable

Invocable.Callable, Invocable.InvocationType, Invocable.ReadyTask, Invocable.Task

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

LifeCycle.Listener

Nested classes/interfaces inherited from interface org.eclipse.jetty.server.Request.Handler

Request.Handler.AbortException

Field Summary

Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

FAILED, STARTED, STARTING, STOPPED, STOPPING

Fields inherited from interface org.eclipse.jetty.util.component.Dumpable

KEY

Fields inherited from interface org.eclipse.jetty.util.thread.Invocable

__nonBlocking, NOOP

Method Summary

Modifier and Type	Method	Description
void	addMapping(String pathSpec, WebSocketCreator creator)	Maps the given pathSpec to the creator of WebSocket endpoints.
void	addMapping(PathSpec pathSpec, WebSocketCreator creator)	Maps the given pathSpec to the creator of WebSocket endpoints.
void	addSessionListener(WebSocketSessionListener listener)	Register a WebSocketSessionListener with the container
static ServerWebSocketContainer	ensure(Server server)	Returns the ServerWebSocketContainer, ensuring that it is available via get(Context).
static ServerWebSocketContainer	ensure(Server server, ContextHandler contextHandler)	Returns the ServerWebSocketContainer, ensuring that it is available via get(Context).
static ServerWebSocketContainer	get(Context context)	Returns the ServerWebSocketContainer present as the context attribute under the name corresponding to the full qualified name of class WebSocketContainer.
Executor	getExecutor()	The Container provided Executor.
Duration	getIdleTimeout()	The duration that a websocket may be idle before being closed by the implementation
int	getInputBufferSize()	The input (read from network layer) buffer size.
Invocable.InvocationType	getInvocationType()
long	getMaxBinaryMessageSize()	Get the maximum size of a binary message during parsing.
long	getMaxFrameSize()	The maximum payload size of any WebSocket Frame which can be received.
int	getMaxOutgoingFrames()	Get the maximum number of data frames allowed to be waiting to be sent at any one time.
long	getMaxTextMessageSize()	Get the maximum size of a text message during parsing.
Collection<Session>	getOpenSessions()	Get the collection of open Sessions being tracked by this container
int	getOutputBufferSize()	The output (write to network layer) buffer size.
boolean	handle(Request request, Response response, Callback callback)	Matches the given request against existing WebSocket mappings, upgrading to WebSocket if there is a match.
boolean	isAutoFragment()	If true, frames are automatically fragmented to respect the maximum frame size.
void	notifySessionListeners(Consumer<WebSocketSessionListener> consumer)	Notify the Session Listeners of an event.
boolean	removeSessionListener(WebSocketSessionListener listener)	Remove a WebSocketSessionListener from the container
void	setAutoFragment(boolean autoFragment)	If set to true, frames are automatically fragmented to respect the maximum frame size.
void	setIdleTimeout(Duration duration)	The duration that a websocket may be idle before being closed by the implementation
void	setInputBufferSize(int size)	The input (read from network layer) buffer size.
void	setInvocationType(Invocable.InvocationType invocationType)	Sets the invocation type of this container.
void	setMaxBinaryMessageSize(long size)	The maximum size of a binary message during parsing/generating.
void	setMaxFrameSize(long maxFrameSize)	The maximum payload size of any WebSocket Frame which can be received.
void	setMaxOutgoingFrames(int maxOutgoingFrames)	Set the maximum number of data frames allowed to be waiting to be sent at any one time.
void	setMaxTextMessageSize(long size)	The maximum size of a text message during parsing/generating.
void	setOutputBufferSize(int size)	The output (write to network layer) buffer size.
boolean	upgrade(WebSocketCreator creator, Request request, Response response, Callback callback)	Upgrades the given request without matching against the WebSocket mappings.

Methods inherited from class org.eclipse.jetty.util.component.ContainerLifeCycle

addBean, addBean, addEventListener, addManaged, contains, destroy, doStart, doStop, dump, dump, dump, dumpObjects, dumpStdErr, getBean, getBeans, getBeans, getContainedBeans, getContainedBeans, installBean, installBean, isAuto, isManaged, isUnmanaged, manage, removeBean, removeBeans, removeEventListener, setBeans, start, stop, unmanage, updateBean, updateBean, updateBeans, updateBeans

Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

getEventListeners, getState, getState, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, setEventListeners, start, stop, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.eclipse.jetty.util.component.Container

getCachedBeans, getEventListeners

Methods inherited from interface org.eclipse.jetty.util.component.Dumpable

dumpSelf

Methods inherited from interface org.eclipse.jetty.util.component.Dumpable.DumpableContainer

isDumpable

Method Details

ensure

public static ServerWebSocketContainer ensure(Server server,
 ContextHandler contextHandler)

Returns the ServerWebSocketContainer, ensuring that it is available via get(Context).

If the ServerWebSocketContainer is not already available, an instance is created, stored to be available via get(Context) and returned.

This method should be invoked during the setup of the Handler hierarchy.

Parameters:

server - the Server object used to lookup common WebSocket components

contextHandler - the ContextHandler used to store the ServerWebSocketContainer

Returns:

a non-null ServerWebSocketContainer

ensure

public static ServerWebSocketContainer ensure(Server server)

Returns the ServerWebSocketContainer, ensuring that it is available via get(Context).

If the ServerWebSocketContainer is not already available, an instance is created, stored to be available via get(Context) and returned.

This method should be invoked during the setup of the Handler hierarchy.

Parameters:

server - the Server object used to lookup common WebSocket components and store the ServerWebSocketContainer

Returns:

a non-null ServerWebSocketContainer

get

public static ServerWebSocketContainer get(Context context)

Returns the ServerWebSocketContainer present as the context attribute under the name corresponding to the full qualified name of class WebSocketContainer.

Parameters:

context - the Context to look for the attribute

Returns:

the ServerWebSocketContainer stored as an attribute, or null if no such attribute is present

getExecutor

public Executor getExecutor()

Description copied from interface: WebSocketContainer

The Container provided Executor.

Specified by:

getExecutor in interface WebSocketContainer

getOpenSessions

public Collection<Session> getOpenSessions()

Description copied from interface: WebSocketContainer

Get the collection of open Sessions being tracked by this container

Specified by:

getOpenSessions in interface WebSocketContainer

Returns:

the collection of open sessions

addSessionListener

public void addSessionListener(WebSocketSessionListener listener)

Description copied from interface: WebSocketContainer

Register a WebSocketSessionListener with the container

Specified by:

addSessionListener in interface WebSocketContainer

Parameters:

listener - the listener

removeSessionListener

public boolean removeSessionListener(WebSocketSessionListener listener)

Description copied from interface: WebSocketContainer

Remove a WebSocketSessionListener from the container

Specified by:

removeSessionListener in interface WebSocketContainer

Parameters:

listener - the listener

Returns:

true if listener was present and removed

notifySessionListeners

public void notifySessionListeners(Consumer<WebSocketSessionListener> consumer)

Description copied from interface: WebSocketContainer

Notify the Session Listeners of an event.

Specified by:

notifySessionListeners in interface WebSocketContainer

Parameters:

consumer - the consumer to call for each tracked listener

getIdleTimeout

public Duration getIdleTimeout()

Description copied from interface: Configurable

The duration that a websocket may be idle before being closed by the implementation

Specified by:

getIdleTimeout in interface Configurable

Returns:

the timeout duration

setIdleTimeout

public void setIdleTimeout(Duration duration)

Description copied from interface: Configurable

The duration that a websocket may be idle before being closed by the implementation

Specified by:

setIdleTimeout in interface Configurable

Parameters:

duration - the timeout duration (may not be null or negative)

getInputBufferSize

public int getInputBufferSize()

Description copied from interface: Configurable

The input (read from network layer) buffer size.

This is the raw read operation buffer size, before the parsing of the websocket frames.

Specified by:

getInputBufferSize in interface Configurable

Returns:

the raw network buffer input size.

setInputBufferSize

public void setInputBufferSize(int size)

Description copied from interface: Configurable

The input (read from network layer) buffer size.

Specified by:

setInputBufferSize in interface Configurable

Parameters:

size - the size in bytes

getOutputBufferSize

public int getOutputBufferSize()

Description copied from interface: Configurable

The output (write to network layer) buffer size.

This is the raw write operation buffer size and has no relationship to the websocket frame.

Specified by:

getOutputBufferSize in interface Configurable

Returns:

the raw network buffer output size.

setOutputBufferSize

public void setOutputBufferSize(int size)

Description copied from interface: Configurable

The output (write to network layer) buffer size.

Specified by:

setOutputBufferSize in interface Configurable

Parameters:

size - the size in bytes

getMaxBinaryMessageSize

public long getMaxBinaryMessageSize()

Description copied from interface: Configurable

Get the maximum size of a binary message during parsing.

This is a memory conservation option, memory over this limit will not be allocated by Jetty for handling binary messages. This applies to individual frames, whole message handling, and partial message handling.

Binary messages over this maximum will result in a close code 1009 StatusCode.MESSAGE_TOO_LARGE

Specified by:

getMaxBinaryMessageSize in interface Configurable

Returns:

the maximum size of a binary message

setMaxBinaryMessageSize

public void setMaxBinaryMessageSize(long size)

Description copied from interface: Configurable

The maximum size of a binary message during parsing/generating.

Binary messages over this maximum will result in a close code 1009 StatusCode.MESSAGE_TOO_LARGE

Specified by:

setMaxBinaryMessageSize in interface Configurable

Parameters:

size - the maximum allowed size of a binary message.

getMaxTextMessageSize

public long getMaxTextMessageSize()

Description copied from interface: Configurable

Get the maximum size of a text message during parsing.

This is a memory conservation option, memory over this limit will not be allocated by Jetty for handling text messages. This applies to individual frames, whole message handling, and partial message handling.

Text messages over this maximum will result in a close code 1009 StatusCode.MESSAGE_TOO_LARGE

Specified by:

getMaxTextMessageSize in interface Configurable

Returns:

the maximum size of a text message.

setMaxTextMessageSize

public void setMaxTextMessageSize(long size)

Description copied from interface: Configurable

The maximum size of a text message during parsing/generating.

Text messages over this maximum will result in a close code 1009 StatusCode.MESSAGE_TOO_LARGE

Specified by:

setMaxTextMessageSize in interface Configurable

Parameters:

size - the maximum allowed size of a text message.

getMaxFrameSize

public long getMaxFrameSize()

Description copied from interface: Configurable

The maximum payload size of any WebSocket Frame which can be received.

Specified by:

getMaxFrameSize in interface Configurable

Returns:

the maximum size of a WebSocket Frame.

setMaxFrameSize

public void setMaxFrameSize(long maxFrameSize)

Description copied from interface: Configurable

The maximum payload size of any WebSocket Frame which can be received.

WebSocket Frames over this maximum will result in a close code 1009 StatusCode.MESSAGE_TOO_LARGE

Specified by:

setMaxFrameSize in interface Configurable

Parameters:

maxFrameSize - the maximum allowed size of a WebSocket Frame.

isAutoFragment

public boolean isAutoFragment()

Description copied from interface: Configurable

If true, frames are automatically fragmented to respect the maximum frame size.

Specified by:

isAutoFragment in interface Configurable

Returns:

whether to automatically fragment incoming WebSocket Frames.

setAutoFragment

public void setAutoFragment(boolean autoFragment)

Description copied from interface: Configurable

If set to true, frames are automatically fragmented to respect the maximum frame size.

Specified by:

setAutoFragment in interface Configurable

Parameters:

autoFragment - whether to automatically fragment incoming WebSocket Frames.

getMaxOutgoingFrames

public int getMaxOutgoingFrames()

Description copied from interface: Configurable

Get the maximum number of data frames allowed to be waiting to be sent at any one time. The default value is -1, this indicates there is no limit on how many frames can be queued to be sent by the implementation. If the limit is exceeded, subsequent frames sent are failed with a WritePendingException but the connection is not failed and will remain open.

Specified by:

getMaxOutgoingFrames in interface Configurable

Returns:

the max number of frames.

setMaxOutgoingFrames

public void setMaxOutgoingFrames(int maxOutgoingFrames)

Description copied from interface: Configurable

Set the maximum number of data frames allowed to be waiting to be sent at any one time. The default value is -1, this indicates there is no limit on how many frames can be queued to be sent by the implementation. If the limit is exceeded, subsequent frames sent are failed with a WritePendingException but the connection is not failed and will remain open.

Specified by:

setMaxOutgoingFrames in interface Configurable

Parameters:

maxOutgoingFrames - the max number of frames.

addMapping

public void addMapping(String pathSpec,
 WebSocketCreator creator)

Maps the given pathSpec to the creator of WebSocket endpoints.

The pathSpec format is that supported by WebSocketMappings.parsePathSpec(String).

Parameters:

pathSpec - the pathSpec to associate to the creator

creator - the creator of WebSocket endpoints

addMapping

public void addMapping(PathSpec pathSpec,
 WebSocketCreator creator)

Maps the given pathSpec to the creator of WebSocket endpoints.

Parameters:

pathSpec - the pathSpec to associate to the creator

creator - the creator of WebSocket endpoints

handle

public boolean handle(Request request,
 Response response,
 Callback callback)

Matches the given request against existing WebSocket mappings, upgrading to WebSocket if there is a match.

Direct upgrades without using WebSocket mappings may be performed via upgrade(WebSocketCreator, Request, Response, Callback).

When true is returned, a response has been sent to the client and the callback has been completed; either because of a successful WebSocket upgrade, or because an error has occurred.

When false is returned, a response has not been sent to the client, and the callback has not been completed; typically because the request path does not match any existing WebSocket mappings, so that the request can be handled by other Handlers.

Specified by:

handle in interface Request.Handler

Parameters:

request - the request to handle, possibly a WebSocket upgrade request

response - the response to handle

callback - the callback to complete when the handling is complete

Returns:

true in case of WebSocket upgrades or failures, false if the request was not handled

Throws:

WebSocketException - there is an error during the upgrade

See Also:

• addMapping(PathSpec, WebSocketCreator)
• upgrade(WebSocketCreator, Request, Response, Callback)

upgrade

public boolean upgrade(WebSocketCreator creator,
 Request request,
 Response response,
 Callback callback)

Upgrades the given request without matching against the WebSocket mappings.

When true is returned, a response has been sent to the client and the callback has been completed; either because of a successful WebSocket upgrade, or because an error has occurred.

When false is returned, a response has not been sent to the client, and the callback has not been completed; for example because the request is not a WebSocket upgrade; in this case the caller must arrange to send a response and complete the callback.

Parameters:

creator - the creator of the WebSocket endpoint

request - the request to upgrade, possibly a WebSocket upgrade request

response - the response

callback - the callback to complete when the upgrade is complete

Returns:

true in case of WebSocket upgrades or failures, false if the request was not upgraded

Throws:

WebSocketException - there is an error during the upgrade

See Also:

• handle(Request, Response, Callback)

getInvocationType

public Invocable.InvocationType getInvocationType()

Specified by:

getInvocationType in interface Invocable

Specified by:

getInvocationType in interface Request.Handler

Returns:

the invocation type, typically blocking or non-blocking, of this container

See Also:

• setInvocationType(InvocationType)

setInvocationType

public void setInvocationType(Invocable.InvocationType invocationType)

Sets the invocation type of this container.

The invocation type may be set to Invocable.InvocationType.NON_BLOCKING when it is known that application code in the listener methods or annotated methods of the WebSocket endpoint does not use blocking APIs.

Setting the invocation type to Invocable.InvocationType.NON_BLOCKING, but then using blocking APIs in the WebSocket endpoint may result in a server lockup.

By default Invocable.InvocationType.BLOCKING is returned, assuming that application code in the WebSocket endpoint uses blocking APIs.

Parameters:

invocationType - the invocation type of this container