Package org.eclipse.jetty.websocket.server

Class WebSocketUpgradeFilter

java.lang.Object

org.eclipse.jetty.websocket.server.WebSocketUpgradeFilter

All Implemented Interfaces:

javax.servlet.Filter, Dumpable, MappedWebSocketCreator

@ManagedObject("WebSocket Upgrade Filter")
public class WebSocketUpgradeFilter
extends java.lang.Object
implements javax.servlet.Filter, MappedWebSocketCreator, Dumpable

Inline Servlet Filter to capture WebSocket upgrade requests and perform path mappings to WebSocketCreator objects.

Embedded Jetty Users should initialize this filter using the configure(ServletContextHandler) method. If you also want to establish some mappings of PathSpec to WebSocketCreator against this WebSocketUpgradeFilter then these actions must occur during the Servlet Initialization Phase. A convenience method is provided with NativeWebSocketServletContainerInitializer.configure(ServletContextHandler, NativeWebSocketServletContainerInitializer.Configurator) to create a lambda that will execute during the appropriate Servlet Initialization Phase.

     ServletContextHandler contextHandler = new ServletContextHandler(...);
     WebSocketUpgradeFilter.configure(contextHandler);
     NativeWebSocketServletContainerInitializer.configure(contextHandler, (context, container) -> {
         container.getPolicy().setMaxTextMessageBufferSize(65535);
         container.getPolicy().setInputBufferSize(16384);
         container.addMapping("/echo", ServerEchoSocket.class);
         container.addMapping(new ServletPathSpec("/api"), (req, resp) -> new ServerApiSocket());
     });
 

Nested Class Summary

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

Dumpable.DumpableContainer

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	ATTR_KEY
static java.lang.String	CONFIG_ATTRIBUTE_KEY
static java.lang.String	CONTEXT_ATTRIBUTE_KEY

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

KEY

Constructor Summary

Constructors

Constructor	Description
WebSocketUpgradeFilter()
WebSocketUpgradeFilter(NativeWebSocketConfiguration configuration)	Deprecated.
WebSocketUpgradeFilter(WebSocketServerFactory factory)	Deprecated.

Method Summary

Modifier and Type	Method	Description
void	addMapping(java.lang.String spec, WebSocketCreator creator)	Add Mapping to underlying NativeWebSocketConfiguration
void	addMapping(PathSpec spec, WebSocketCreator creator)	Add Mapping to underlying NativeWebSocketConfiguration
void	addMapping(PathSpec spec, WebSocketCreator creator)	Deprecated. use new addMapping(org.eclipse.jetty.http.pathmap.PathSpec, WebSocketCreator) instead
static WebSocketUpgradeFilter	configure(ServletContextHandler context)	Configure the default WebSocketUpgradeFilter.
static WebSocketUpgradeFilter	configureContext(javax.servlet.ServletContext context)	Deprecated. use configureContext(ServletContextHandler) instead
static WebSocketUpgradeFilter	configureContext(ServletContextHandler context)	Deprecated. use configure(ServletContextHandler) instead
void	destroy()
void	doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain)
java.lang.String	dump()
void	dump(java.lang.Appendable out, java.lang.String indent)	Dump this object (and children) into an Appendable using the provided indent after any new lines.
NativeWebSocketConfiguration	getConfiguration()
WebSocketServletFactory	getFactory()
WebSocketCreator	getMapping(java.lang.String target)	/** Returns the creator for the given path spec.
void	init(javax.servlet.FilterConfig config)
boolean	removeMapping(java.lang.String spec)	Remove Mapping to underlying NativeWebSocketConfiguration
void	setToAttribute(javax.servlet.ServletContext context, java.lang.String key)
java.lang.String	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.Dumpable

dumpSelf

Field Detail

CONTEXT_ATTRIBUTE_KEY

public static final java.lang.String CONTEXT_ATTRIBUTE_KEY

See Also:

Constant Field Values

CONFIG_ATTRIBUTE_KEY

public static final java.lang.String CONFIG_ATTRIBUTE_KEY

See Also:

Constant Field Values

ATTR_KEY

public static final java.lang.String ATTR_KEY

Constructor Detail

WebSocketUpgradeFilter

public WebSocketUpgradeFilter()

WebSocketUpgradeFilter

@Deprecated
public WebSocketUpgradeFilter(WebSocketServerFactory factory)

Deprecated.

WebSocketUpgradeFilter

@Deprecated
public WebSocketUpgradeFilter(NativeWebSocketConfiguration configuration)

Deprecated.

Method Detail

configure

public static WebSocketUpgradeFilter configure(ServletContextHandler context)
                                        throws javax.servlet.ServletException

Configure the default WebSocketUpgradeFilter.

This will return the default WebSocketUpgradeFilter on the provided ServletContextHandler, creating the filter if necessary.

The default WebSocketUpgradeFilter is also available via the ServletContext attribute named org.eclipse.jetty.websocket.server.WebSocketUpgradeFilter

Parameters:

context - the ServletContextHandler to use

Returns:

the configured default WebSocketUpgradeFilter instance, use this reference later in your Servlet Initialization Phase to establish mappings of websockets.

Throws:

javax.servlet.ServletException - if the filer cannot be configured

configureContext

@Deprecated
public static WebSocketUpgradeFilter configureContext(ServletContextHandler context)
                                               throws javax.servlet.ServletException

Deprecated.

use configure(ServletContextHandler) instead

Parameters:

context - the ServletContextHandler to use

Returns:

a configured WebSocketUpgradeFilter instance

Throws:

javax.servlet.ServletException - if the filer cannot be configured

configureContext

@Deprecated
public static WebSocketUpgradeFilter configureContext(javax.servlet.ServletContext context)
                                               throws javax.servlet.ServletException

Deprecated.

use configureContext(ServletContextHandler) instead

Parameters:

context - the ServletContext to use

Returns:

a configured WebSocketUpgradeFilter instance

Throws:

javax.servlet.ServletException - if the filer cannot be configured

addMapping

public void addMapping(PathSpec spec,
                       WebSocketCreator creator)

Add Mapping to underlying NativeWebSocketConfiguration

IMPORTANT: Can only be used during Servlet Initialization phase.

Embedded Jetty users, consider using NativeWebSocketServletContainerInitializer.configure(ServletContextHandler, NativeWebSocketServletContainerInitializer.Configurator) instead to define mappings early that happen during the Servlet Initialization phase.

Specified by:

addMapping in interface MappedWebSocketCreator

Parameters:

spec - the path spec to use

creator - the creator for the mapping

See Also:

NativeWebSocketConfiguration.addMapping(PathSpec, WebSocketCreator)

addMapping

@Deprecated
public void addMapping(PathSpec spec,
                       WebSocketCreator creator)

Deprecated.

use new addMapping(org.eclipse.jetty.http.pathmap.PathSpec, WebSocketCreator) instead

Description copied from interface: MappedWebSocketCreator

Add a mapping.

Specified by:

addMapping in interface MappedWebSocketCreator

Parameters:

spec - the path spec to use

creator - the creator for the mapping

addMapping

public void addMapping(java.lang.String spec,
                       WebSocketCreator creator)

Add Mapping to underlying NativeWebSocketConfiguration

IMPORTANT: Can only be used during Servlet Initialization phase.

Embedded Jetty users, consider using NativeWebSocketServletContainerInitializer.configure(ServletContextHandler, NativeWebSocketServletContainerInitializer.Configurator) instead to define mappings early that happen during the Servlet Initialization phase.

Specified by:

addMapping in interface MappedWebSocketCreator

Parameters:

spec - the path spec to use.

creator - the websocket creator for this specific mapping

See Also:

NativeWebSocketConfiguration.addMapping(String, WebSocketCreator)

removeMapping

public boolean removeMapping(java.lang.String spec)

Remove Mapping to underlying NativeWebSocketConfiguration

IMPORTANT: Can only be used during Servlet Initialization phase.

Specified by:

removeMapping in interface MappedWebSocketCreator

Parameters:

spec - the path spec to remove (using the same spec syntax as seen in MappedWebSocketCreator.addMapping(String, WebSocketCreator))

Returns:

true if underlying mapping were altered, false otherwise

See Also:

NativeWebSocketConfiguration.removeMapping(String)

destroy

public void destroy()

Specified by:

destroy in interface javax.servlet.Filter

doFilter

public void doFilter(javax.servlet.ServletRequest request,
                     javax.servlet.ServletResponse response,
                     javax.servlet.FilterChain chain)
              throws java.io.IOException,
                     javax.servlet.ServletException

Specified by:

doFilter in interface javax.servlet.Filter

Throws:

java.io.IOException

javax.servlet.ServletException

dump

public java.lang.String dump()

Specified by:

dump in interface Dumpable

dump

public void dump(java.lang.Appendable out,
                 java.lang.String indent)
          throws java.io.IOException

Description copied from interface: Dumpable

Dump this object (and children) into an Appendable using the provided indent after any new lines. The indent should not be applied to the first object dumped.

Specified by:

dump in interface Dumpable

Parameters:

out - The appendable to dump to

indent - The indent to apply after any new lines.

Throws:

java.io.IOException - if unable to write to Appendable

getFactory

public WebSocketServletFactory getFactory()

getConfiguration

@ManagedAttribute(value="configuration",
                  readonly=true)
public NativeWebSocketConfiguration getConfiguration()

getMapping

public WebSocketCreator getMapping(java.lang.String target)

Description copied from interface: MappedWebSocketCreator

/** Returns the creator for the given path spec.

Specified by:

getMapping in interface MappedWebSocketCreator

Parameters:

target - the spec to test for (using the same spec syntax as seen in MappedWebSocketCreator.addMapping(String, WebSocketCreator))

Returns:

the websocket creator if path spec exists, or null

init

public void init(javax.servlet.FilterConfig config)
          throws javax.servlet.ServletException

Specified by:

init in interface javax.servlet.Filter

Throws:

javax.servlet.ServletException

setToAttribute

public void setToAttribute(javax.servlet.ServletContext context,
                           java.lang.String key)
                    throws javax.servlet.ServletException

Throws:

javax.servlet.ServletException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object