Filter

protected Filter()

doFilter

public abstract void doFilter(HttpExchange exchange, Filter.Chain chain) throws IOException

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 String describing the Filter

beforeHandler

public static Filter beforeHandler(String description, Consumer<HttpExchange> operation)

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)

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)

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