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

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Filter.Chain
    A chain of filters associated with a HttpServer.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Filter()
    Constructor for subclasses to call.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Filter
    adaptRequest(String description, UnaryOperator<Request> requestOperator)
    Returns a pre-processing Filter that inspects and possibly adapts the request state.
    static Filter
    afterHandler(String description, Consumer<HttpExchange> operation)
    Returns a post-processing Filter with the given description and operation.
    static Filter
    beforeHandler(String description, Consumer<HttpExchange> operation)
    Returns a pre-processing Filter with the given description and operation.
    abstract String
    description()
    Returns a short description of this Filter.
    abstract void
    doFilter(HttpExchange exchange, Filter.Chain chain)
    Asks this filter to pre/post-process the given exchange.

    Methods declared in class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    Modifier and Type
    Method
    Description
    protected Object
    clone()
    Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
    boolean
    equals(Object o)
    Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
    protected void
    finalize()
    Deprecated, for removal: This API element is subject to removal in a future version.
    May cause performance issues, deadlocks and hangs.
    final Class<? extends Object>
    getClass()
    Answers the unique instance of java.lang.Class which represents the class of the receiver.
    int
    hashCode()
    Answers an integer hash code for the receiver.
    final void
    notify()
    Causes one thread which is waiting on the receiver to be made ready to run.
    final void
    notifyAll()
    Causes all threads which are waiting on the receiver to be made ready to run.
    String
    toString()
    Answers a string containing a concise, human-readable description of the receiver.
    final void
    wait()
    Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by notify or notifyAll).
    final void
    wait(long time)
    Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.
    final void
    wait(long time, int frac)
    Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.

  • 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.

      API Note:
      A beforeHandler filter is typically used to examine or modify the exchange state before it is handled. The filter operation is executed before Filter.Chain.doFilter(HttpExchange) is invoked, so before any subsequent filters in the chain and the exchange handler are executed. The filter operation is not expected to handle the request or send response headers, since this is commonly done by the exchange handler.

      Example of adding the "Foo" response header to all responses: 

          var filter = Filter.beforeHandler("Add response header Foo",
                e -> e.getResponseHeaders().set("Foo", "Bar"));
    httpContext.getFilters().add(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.

      API Note:
      An afterHandler filter is typically used to examine the exchange state rather than modifying it. The filter operation is executed after Filter.Chain.doFilter(HttpExchange) is invoked, this means any subsequent filters in the chain and the exchange handler have been executed. The filter operation is not expected to handle the exchange or send the response headers. Doing so is likely to fail, since the exchange has commonly been handled before the operation is invoked. More specifically, the response may be sent before the filter operation is executed.

      Example of adding a filter that logs the response code of all exchanges: 

          var filter = Filter.afterHandler("Log response code", e -> log(e.getResponseCode());
    httpContext.getFilters().add(filter);

      Example of adding a sequence of afterHandler filters to a context:
      The order in which the filter operations are invoked is reverse to the order in which the filters are added to the context's filter-list. 

          var a1Set = Filter.afterHandler("Set a1", e -> e.setAttribute("a1", "some value"));
    var a1Get = Filter.afterHandler("Get a1", e -> doSomething(e.getAttribute("a1")));
    httpContext.getFilters().addAll(List.of(a1Get, a1Set));

      The operation of a1Get will be invoked after the operation of a1Set because a1Get was added before a1Set.

      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

    • adaptRequest

      public static Filter adaptRequest(String description, UnaryOperator<Request> requestOperator)
      Returns a pre-processing Filter that inspects and possibly adapts the request state. The Request returned by the requestOperator will be the effective request state of the exchange. 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 requestOperator are not handled by the filter.
      API Note:
      When the returned filter is invoked, it first invokes the requestOperator with the given exchange, ex, in order to retrieve the adapted request state. It then invokes the next filter in the chain or the exchange handler, passing an exchange equivalent to ex with the adapted request state set as the effective request state.

      Example of adding the "Foo" request header to all requests: 

          var filter = Filter.adaptRequest("Add Foo header", r -> r.with("Foo", List.of("Bar")));
    httpContext.getFilters().add(filter);
      Parameters:
      description - the string to be returned from description()
      requestOperator - the request operator
      Returns:
      a filter that adapts the request state before the exchange is handled
      Throws:
      NullPointerException - if any argument is null
      Since:
      18