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

All Methods Static Methods Concrete Methods Deprecated Methods
`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 SetErrorHandler` `setErrorHandler(int responseCode, HttpHandler next)` A handler that sets response code but continues the exchange so the servlet's error page can be returned.
`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

#### setErrorHandler

    public static SetErrorHandler setErrorHandler(int responseCode,
                                                  HttpHandler next)

A handler that sets response code but continues the exchange so the servlet's error page can be returned.

Parameters:
  `responseCode` - The response code to set
  `next` - The next handler
Returns:
  A Set Error 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)