Package 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 Details

    • 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:
    • 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)