Handlers (Undertow 1.3.0.CR1 API)

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

Class Handlers

Method Summary

Methods inherited from class java.lang.Object

Method Detail

path

path

pathTemplate

routing

routing

pathTemplate

virtualHost

virtualHost

virtualHost

virtualHost

websocket

websocket

serverSentEvents

serverSentEvents

resource

redirect

trace

date

predicate

predicateContext

predicates

header

header

ipAccessControl

acl

httpContinueRead

httpContinueAccepting

httpContinueAccepting

urlDecoding

setAttribute

rewrite

urlDecodingHandler

gracefulShutdown

proxyPeerAddress

jvmRoute

requestLimitingHandler

requestLimitingHandler

proxyHandler

proxyHandler

proxyHandler

disableCache

requestDump

exceptionHandler

responseRateLimitingHandler

learningPushHandler

learningPushHandler

handlerNotNull