io.undertow

Class Handlers

java.lang.Object

io.undertow.Handlers

public class Handlers
extends Object

Utility class with convenience methods for dealing with handlers

Author:

Stuart Douglas

Method Summary

Modifier and Type	Method and Description
static AccessControlListHandler	acl(HttpHandler next, boolean defaultAllow, ExchangeAttribute attribute) Returns a new handler that can allow or deny access to a resource based an at attribute of the exchange
static DateHandler	date(HttpHandler next) Deprecated.
static HttpHandler	disableCache(HttpHandler next) Handler that sets the headers that disable caching of the response
static ExceptionHandler	exceptionHandler(HttpHandler next) Returns a handler that maps exceptions to additional handlers
static GracefulShutdownHandler	gracefulShutdown(HttpHandler next) Returns a new handler that can be used to wait for all requests to finish before shutting down the server gracefully.
static void	handlerNotNull(HttpHandler handler)
static SetHeaderHandler	header(HttpHandler next, String headerName, ExchangeAttribute headerValue) Returns a handler that sets a response header
static SetHeaderHandler	header(HttpHandler next, String headerName, String headerValue) Returns a handler that sets a response header
static HttpContinueAcceptingHandler	httpContinueAccepting(HttpHandler next) Returns a handler that sends back a HTTP 100 continue response to all requests.
static HttpContinueAcceptingHandler	httpContinueAccepting(HttpHandler next, Predicate accept) Returns a handler that sends back a HTTP 100 continue response if the given predicate resolves to true.
static HttpContinueReadHandler	httpContinueRead(HttpHandler next) A handler that automatically handles HTTP 100-continue responses, by sending a continue response when the first attempt is made to read from the request channel.
static IPAddressAccessControlHandler	ipAccessControl(HttpHandler next, boolean defaultAllow) Returns a new handler that can allow or deny access to a resource based on IP address
static JvmRouteHandler	jvmRoute(String sessionCookieName, String jvmRoute, HttpHandler next) Handler that appends the JVM route to the session cookie
static LearningPushHandler	learningPushHandler(int maxEntries, HttpHandler next) Creates a handler that automatically learns which resources to push based on the referer header
static LearningPushHandler	learningPushHandler(int maxEntries, int maxAge, HttpHandler next) Creates a handler that automatically learns which resources to push based on the referer header
static PathHandler	path() Creates a new path handler
static PathHandler	path(HttpHandler defaultHandler) Creates a new path handler, with the default handler specified
static PathTemplateHandler	pathTemplate()
static PathTemplateHandler	pathTemplate(boolean rewriteQueryParams)
static PredicateHandler	predicate(Predicate predicate, HttpHandler trueHandler, HttpHandler falseHandler) Returns a new predicate handler, that will delegate to one of the two provided handlers based on the value of the provided predicate.
static HttpHandler	predicateContext(HttpHandler next)
static PredicatesHandler	predicates(List<PredicatedHandler> handlers, HttpHandler next)
static ProxyHandler	proxyHandler(ProxyClient proxyClient) Returns a handler that can act as a load balancing reverse proxy.
static ProxyHandler	proxyHandler(ProxyClient proxyClient, HttpHandler next) Returns a handler that can act as a load balancing reverse proxy.
static ProxyHandler	proxyHandler(ProxyClient proxyClient, int maxRequestTime, HttpHandler next) Returns a handler that can act as a load balancing reverse proxy.
static ProxyPeerAddressHandler	proxyPeerAddress(HttpHandler next) Returns a new handler that sets the peer address based on the X-Forwarded-For and X-Forwarded-Proto header
static RedirectHandler	redirect(String location) Returns a new redirect handler
static HttpHandler	requestDump(HttpHandler next) Returns a handler that dumps requests to the log for debugging purposes.
static RequestLimitingHandler	requestLimitingHandler(int maxRequest, int queueSize, HttpHandler next) Returns a handler that limits the maximum number of requests that can run at a time.
static RequestLimitingHandler	requestLimitingHandler(RequestLimit requestLimit, HttpHandler next) Returns a handler that limits the maximum number of requests that can run at a time.
static ResourceHandler	resource(ResourceManager resourceManager) Return a new resource handler
static ResponseRateLimitingHandler	responseRateLimitingHandler(HttpHandler next, int bytes, long time, TimeUnit timeUnit) A handler that limits the download speed to a set number of bytes/period
static HttpHandler	rewrite(String condition, String target, ClassLoader classLoader, HttpHandler next) Creates the set of handlers that are required to perform a simple rewrite.
static RoutingHandler	routing()
static RoutingHandler	routing(boolean rewriteQueryParams)
static ServerSentEventHandler	serverSentEvents() A handler for server sent events
static ServerSentEventHandler	serverSentEvents(ServerSentEventConnectionCallback callback) A handler for server sent events
static SetAttributeHandler	setAttribute(HttpHandler next, String attribute, String value, ClassLoader classLoader) Returns an attribute setting handler that can be used to set an arbitrary attribute on the exchange.
static HttpTraceHandler	trace(HttpHandler next) Returns a new HTTP trace handler.
static URLDecodingHandler	urlDecoding(HttpHandler next, String charset) A handler that will decode the URL, query parameters and to the specified charset.
static HttpHandler	urlDecodingHandler(String charset, HttpHandler next) Returns a new handler that decodes the URL and query parameters into the specified charset, assuming it has not already been done by the connector.
static NameVirtualHostHandler	virtualHost() Creates a new virtual host handler
static NameVirtualHostHandler	virtualHost(HttpHandler defaultHandler) Creates a new virtual host handler using the provided default handler
static NameVirtualHostHandler	virtualHost(HttpHandler defaultHandler, HttpHandler hostHandler, String... hostnames) Creates a new virtual host handler that uses the provided handler as the root handler for the given hostnames.
static NameVirtualHostHandler	virtualHost(HttpHandler hostHandler, String... hostnames) Creates a new virtual host handler that uses the provided handler as the root handler for the given hostnames.
static WebSocketProtocolHandshakeHandler	websocket(WebSocketConnectionCallback sessionHandler)
static WebSocketProtocolHandshakeHandler	websocket(WebSocketConnectionCallback sessionHandler, HttpHandler next)

Methods inherited from class java.lang.Object

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

Method Detail

path

public static PathHandler path(HttpHandler defaultHandler)

Creates a new path handler, with the default handler specified

Parameters:

defaultHandler - The default handler

Returns:

A new path handler

path

public static PathHandler path()

Creates a new path handler

Returns:

A new path handler

pathTemplate

public static PathTemplateHandler pathTemplate()

Returns:

a new path template handler

routing

public static RoutingHandler routing(boolean rewriteQueryParams)

Parameters:

rewriteQueryParams - If the query params should be rewritten

Returns:

The routing handler

routing

public static RoutingHandler routing()

Returns:

a new routing handler

pathTemplate

public static PathTemplateHandler pathTemplate(boolean rewriteQueryParams)

Parameters:

rewriteQueryParams - If the query params should be rewritten

Returns:

The path template handler

virtualHost

public static NameVirtualHostHandler virtualHost()

Creates a new virtual host handler

Returns:

A new virtual host handler

virtualHost

public static NameVirtualHostHandler virtualHost(HttpHandler defaultHandler)

Creates a new virtual host handler using the provided default handler

Returns:

A new virtual host handler

virtualHost

public static NameVirtualHostHandler virtualHost(HttpHandler hostHandler,
                                                 String... hostnames)

Creates a new virtual host handler that uses the provided handler as the root handler for the given hostnames.

Parameters:

hostHandler - The host handler

hostnames - The host names

Returns:

A new virtual host handler

virtualHost

public static NameVirtualHostHandler virtualHost(HttpHandler defaultHandler,
                                                 HttpHandler hostHandler,
                                                 String... hostnames)

Creates a new virtual host handler that uses the provided handler as the root handler for the given hostnames.

Parameters:

defaultHandler - The default handler

hostHandler - The host handler

hostnames - The host names

Returns:

A new virtual host handler

websocket

public static WebSocketProtocolHandshakeHandler websocket(WebSocketConnectionCallback sessionHandler)

Parameters:

sessionHandler - The web socket session handler

Returns:

The web socket handler

websocket

public static WebSocketProtocolHandshakeHandler websocket(WebSocketConnectionCallback sessionHandler,
                                                          HttpHandler next)

Parameters:

sessionHandler - The web socket session handler

next - The handler to invoke if the web socket connection fails

Returns:

The web socket handler

serverSentEvents

public static ServerSentEventHandler serverSentEvents(ServerSentEventConnectionCallback callback)

A handler for server sent events

Parameters:

callback - The server sent events callback

Returns:

A new server sent events handler

serverSentEvents

public static ServerSentEventHandler serverSentEvents()

A handler for server sent events

Returns:

A new server sent events handler

resource

public static ResourceHandler resource(ResourceManager resourceManager)

Return a new resource handler

Parameters:

resourceManager - The resource manager to use

Returns:

A new resource handler

redirect

public static RedirectHandler redirect(String location)

Returns a new redirect handler

Parameters:

location - The redirect location

Returns:

A new redirect handler

trace

public static HttpTraceHandler trace(HttpHandler next)

Returns a new HTTP trace handler. This handler will handle HTTP TRACE requests as per the RFC.

WARNING: enabling trace requests may leak information, in general it is recommended that these be disabled for security reasons.

Parameters:

next - The next handler in the chain

Returns:

A HTTP trace handler

date

@Deprecated
public static DateHandler date(HttpHandler next)

Deprecated.

Returns a new HTTP handler that sets the Date: header. This is no longer necessary, as it is handled by the connectors directly.

Parameters:

next - The next handler in the chain

Returns:

A new date handler

predicate

public static PredicateHandler predicate(Predicate predicate,
                                         HttpHandler trueHandler,
                                         HttpHandler falseHandler)

Returns a new predicate handler, that will delegate to one of the two provided handlers based on the value of the provided predicate.

Parameters:

predicate - The predicate

trueHandler - The handler that will be executed if the predicate is true

falseHandler - The handler that will be exected if the predicate is false

Returns:

A new predicate handler

See Also:

Predicate, Predicates

predicateContext

public static HttpHandler predicateContext(HttpHandler next)

Parameters:

next - The next handler

Returns:

a handler that sets up a new predicate context

predicates

public static PredicatesHandler predicates(List<PredicatedHandler> handlers,
                                           HttpHandler next)

header

public static SetHeaderHandler header(HttpHandler next,
                                      String headerName,
                                      String headerValue)

Returns a handler that sets a response header

Parameters:

next - The next handler in the chain

headerName - The name of the header

headerValue - The header value

Returns:

A new set header handler

header

public static SetHeaderHandler header(HttpHandler next,
                                      String headerName,
                                      ExchangeAttribute headerValue)

Returns a handler that sets a response header

Parameters:

next - The next handler in the chain

headerName - The name of the header

headerValue - The header value

Returns:

A new set header handler

ipAccessControl

public static final IPAddressAccessControlHandler ipAccessControl(HttpHandler next,
                                                                  boolean defaultAllow)

Returns a new handler that can allow or deny access to a resource based on IP address

Parameters:

next - The next handler in the chain

defaultAllow - Determine if a non-matching address will be allowed by default

Returns:

A new IP access control handler

acl

public static final AccessControlListHandler acl(HttpHandler next,
                                                 boolean defaultAllow,
                                                 ExchangeAttribute attribute)

Returns a new handler that can allow or deny access to a resource based an at attribute of the exchange

Parameters:

next - The next handler in the chain

defaultAllow - Determine if a non-matching user agent will be allowed by default

Returns:

A new user agent access control handler

httpContinueRead

public static final HttpContinueReadHandler httpContinueRead(HttpHandler next)

A handler that automatically handles HTTP 100-continue responses, by sending a continue response when the first attempt is made to read from the request channel.

Parameters:

next - The next handler in the chain

Returns:

A new continue handler

httpContinueAccepting

public static final HttpContinueAcceptingHandler httpContinueAccepting(HttpHandler next,
                                                                       Predicate accept)

Returns a handler that sends back a HTTP 100 continue response if the given predicate resolves to true. This handler differs from the one returned by httpContinueRead(io.undertow.server.HttpHandler) in that it will eagerly send the response, and not wait for the first read attempt.

Parameters:

next - The next handler

accept - The predicate used to determine if the request should be accepted

Returns:

The accepting handler

httpContinueAccepting

public static final HttpContinueAcceptingHandler httpContinueAccepting(HttpHandler next)

Returns a handler that sends back a HTTP 100 continue response to all requests. This handler differs from the one returned by httpContinueRead(io.undertow.server.HttpHandler) in that it will eagerly send the response, and not wait for the first read attempt.

Parameters:

next - The next handler

Returns:

The accepting handler

urlDecoding

public static final URLDecodingHandler urlDecoding(HttpHandler next,
                                                   String charset)

A handler that will decode the URL, query parameters and to the specified charset.

If you are using this handler you must set the UndertowOptions.DECODE_URL parameter to false.

This is not as efficient as using the parsers built in UTF-8 decoder. Unless you need to decode to something other than UTF-8 you should rely on the parsers decoding instead.

Parameters:

next - The next handler in the chain

charset - The charset to decode to

Returns:

a new url decoding handler

setAttribute

public static SetAttributeHandler setAttribute(HttpHandler next,
                                               String attribute,
                                               String value,
                                               ClassLoader classLoader)

Returns an attribute setting handler that can be used to set an arbitrary attribute on the exchange. This includes functions such as adding and removing headers etc.

Parameters:

next - The next handler

attribute - The attribute to set, specified as a string presentation of an ExchangeAttribute

value - The value to set, specified an a string representation of an ExchangeAttribute

classLoader - The class loader to use to parser the exchange attributes

Returns:

The handler

rewrite

public static HttpHandler rewrite(String condition,
                                  String target,
                                  ClassLoader classLoader,
                                  HttpHandler next)

Creates the set of handlers that are required to perform a simple rewrite.

Parameters:

condition - The rewrite condition

target - The rewrite target if the condition matches

next - The next handler

Returns:

urlDecodingHandler

public static HttpHandler urlDecodingHandler(String charset,
                                             HttpHandler next)

Returns a new handler that decodes the URL and query parameters into the specified charset, assuming it has not already been done by the connector. For this handler to take effect the parameter UndertowOptions.DECODE_URL must have been set to false.

Parameters:

charset - The charset to decode

next - The next handler

Returns:

A handler that decodes the URL

gracefulShutdown

public static GracefulShutdownHandler gracefulShutdown(HttpHandler next)

Returns a new handler that can be used to wait for all requests to finish before shutting down the server gracefully.

Parameters:

next - The next http handler

Returns:

The graceful shutdown handler

proxyPeerAddress

public static ProxyPeerAddressHandler proxyPeerAddress(HttpHandler next)

Returns a new handler that sets the peer address based on the X-Forwarded-For and X-Forwarded-Proto header

Parameters:

next - The next http handler

Returns:

The handler

jvmRoute

public static JvmRouteHandler jvmRoute(String sessionCookieName,
                                       String jvmRoute,
                                       HttpHandler next)

Handler that appends the JVM route to the session cookie

Parameters:

sessionCookieName - The session cookie name

jvmRoute - The JVM route to append

next - The next handler

Returns:

The handler

requestLimitingHandler

public static RequestLimitingHandler requestLimitingHandler(int maxRequest,
                                                            int queueSize,
                                                            HttpHandler next)

Returns a handler that limits the maximum number of requests that can run at a time.

Parameters:

maxRequest - The maximum number of requests

queueSize - The maximum number of queued requests

next - The next handler

Returns:

The handler

requestLimitingHandler

public static RequestLimitingHandler requestLimitingHandler(RequestLimit requestLimit,
                                                            HttpHandler next)

Returns a handler that limits the maximum number of requests that can run at a time.

Parameters:

requestLimit - The request limit object that can be shared between handlers, to apply the same limits across multiple handlers

next - The next handler

Returns:

The handler

proxyHandler

public static ProxyHandler proxyHandler(ProxyClient proxyClient,
                                        int maxRequestTime,
                                        HttpHandler next)

Returns a handler that can act as a load balancing reverse proxy.

Parameters:

proxyClient - The proxy client to use to connect to the remote server

maxRequestTime - The maximum amount of time a request can be in progress before it is forcibly closed

next - The next handler to invoke if the proxy client does not know how to proxy the request

Returns:

The proxy handler

proxyHandler

public static ProxyHandler proxyHandler(ProxyClient proxyClient,
                                        HttpHandler next)

Returns a handler that can act as a load balancing reverse proxy.

Parameters:

proxyClient - The proxy client to use to connect to the remote server

next - The next handler to invoke if the proxy client does not know how to proxy the request

Returns:

The proxy handler

proxyHandler

public static ProxyHandler proxyHandler(ProxyClient proxyClient)

Returns a handler that can act as a load balancing reverse proxy.

Parameters:

proxyClient - The proxy client to use to connect to the remote server

Returns:

The proxy handler

disableCache

public static HttpHandler disableCache(HttpHandler next)

Handler that sets the headers that disable caching of the response

Parameters:

next - The next handler

Returns:

The handler

requestDump

public static HttpHandler requestDump(HttpHandler next)

Returns a handler that dumps requests to the log for debugging purposes.

Parameters:

next - The next handler

Returns:

The request dumping handler

exceptionHandler

public static ExceptionHandler exceptionHandler(HttpHandler next)

Returns a handler that maps exceptions to additional handlers

Parameters:

next - The next handler

Returns:

The exception handler

responseRateLimitingHandler

public static ResponseRateLimitingHandler responseRateLimitingHandler(HttpHandler next,
                                                                      int bytes,
                                                                      long time,
                                                                      TimeUnit timeUnit)

A handler that limits the download speed to a set number of bytes/period

Parameters:

next - The next handler

bytes - The number of bytes per time period

time - The time period

timeUnit - The units of the time period

learningPushHandler

public static LearningPushHandler learningPushHandler(int maxEntries,
                                                      int maxAge,
                                                      HttpHandler next)

Creates a handler that automatically learns which resources to push based on the referer header

Parameters:

maxEntries - The maximum number of entries to store

maxAge - The maximum age of the entries

next - The next handler

Returns:

A caching push handler

learningPushHandler

public static LearningPushHandler learningPushHandler(int maxEntries,
                                                      HttpHandler next)

Creates a handler that automatically learns which resources to push based on the referer header

Parameters:

maxEntries - The maximum number of entries to store

next - The next handler

Returns:

A caching push handler

handlerNotNull

public static void handlerNotNull(HttpHandler handler)