Module jdk.httpserver
Package com.sun.net.httpserver

Class Filter

java.lang.Object
com.sun.net.httpserver.Filter
public abstract class Filter extends Object
A filter used to pre- and post-process incoming requests. Pre-processing occurs before the application's exchange handler is invoked, and post-processing occurs after the exchange handler returns. Filters are organised in chains, and are associated with HttpContext instances.

Each Filter in the chain, invokes the next filter within its own doFilter(HttpExchange, Chain) implementation. The final Filter in the chain invokes the applications exchange handler.

Since:
1.6

  • Constructor Details

    • Filter

      protected Filter()
      Constructor for subclasses to call.

  • Method Details

    • doFilter

      public abstract void doFilter(HttpExchange exchange, Filter.Chain chain) throws IOException
      Asks this filter to pre/post-process the given exchange. The filter can:
      • Examine or modify the request headers.
      • Filter the request body or the response body, by creating suitable filter streams and calling HttpExchange.setStreams(InputStream, OutputStream).
      • Set attribute objects in the exchange, which other filters or the exchange handler can access.
      • Decide to either:
        1. Invoke the next filter in the chain, by calling Filter.Chain.doFilter(HttpExchange).
        2. Terminate the chain of invocation, by not calling Filter.Chain.doFilter(HttpExchange).
      • If option 1. above is taken, then when doFilter() returns all subsequent filters in the Chain have been called, and the response headers can be examined or modified.
      • If option 2. above is taken, then this Filter must use the HttpExchange to send back an appropriate response.
      Parameters:
      exchange - the HttpExchange to be filtered
      chain - the Chain which allows the next filter to be invoked
      Throws:
      IOException - may be thrown by any filter module, and if caught, must be rethrown again
      NullPointerException - if either exchange or chain are null

    • description

      public abstract String description()
      Returns a short description of this Filter.
      Returns:
      a String describing the Filter

    • beforeHandler

      public static Filter beforeHandler(String description, Consumer<HttpExchange> operation)
      Returns a pre-processing Filter with the given description and operation.

      The operation is the effective implementation of the filter. It is executed for each HttpExchange before invoking either the next filter in the chain or the exchange handler (if this is the final filter in the chain). Exceptions thrown by the operation are not handled by the filter.

      Parameters:
      description - the string to be returned from description()
      operation - the operation of the returned filter
      Returns:
      a filter whose operation is invoked before the exchange is handled
      Throws:
      NullPointerException - if any argument is null
      Since:
      17

    • afterHandler

      public static Filter afterHandler(String description, Consumer<HttpExchange> operation)
      Returns a post-processing Filter with the given description and operation.

      The operation is the effective implementation of the filter. It is executed for each HttpExchange after invoking either the next filter in the chain or the exchange handler (if this filter is the final filter in the chain). Exceptions thrown by the operation are not handled by the filter.

      Parameters:
      description - the string to be returned from description()
      operation - the operation of the returned filter
      Returns:
      a filter whose operation is invoked after the exchange is handled
      Throws:
      NullPointerException - if any argument is null
      Since:
      17