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

Access	Constructor and Description
protected	Filter() Constructor for subclasses to call.

Method Summary

Modifier and Type	Method and Description
public static Filter	Returns: a filter that adapts the request state before the exchange is handled adaptRequest(String the string to be returned from `description()` description, UnaryOperator<Request> the request operator requestOperator) Returns a pre-processing Filter that inspects and possibly adapts the request state.
public static Filter	Returns: a filter whose operation is invoked after the exchange is handled afterHandler(String the string to be returned from `description()` description, Consumer<HttpExchange> the operation of the returned filter operation) Returns a post-processing `Filter` with the given description and operation.
public static Filter	Returns: a filter whose operation is invoked before the exchange is handled beforeHandler(String the string to be returned from `description()` description, Consumer<HttpExchange> the operation of the returned filter operation) Returns a pre-processing `Filter` with the given description and operation.
public abstract String	Returns: a `String` describing the `Filter` description() Returns a short description of this `Filter`.
public abstract void	doFilter(HttpExchange the `HttpExchange` to be filtered exchange, Filter.Chain the `Chain` which allows the next filter to be invoked chain) Asks this filter to pre/post-process the given exchange.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

Filter	back to summary
protected Filter() Constructor for subclasses to call.

Method Detail

adaptRequest back to summary

adaptRequest	back to summary
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:String the string to be returned from `description()` requestOperator:UnaryOperator<Request> the request operator Returns:Filter a filter that adapts the request state before the exchange is handled Exceptions NullPointerException: if any argument is null Since 18

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:String: the string to be returned from description()
requestOperator:UnaryOperator<Request>: the request operator

Returns:Filter

a filter that adapts the request state before the exchange is handled

Exceptions

NullPointerException:: if any argument is null

Since

afterHandler back to summary

afterHandler	back to summary
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:String the string to be returned from `description()` operation:Consumer<HttpExchange> the operation of the returned filter Returns:Filter a filter whose operation is invoked after the exchange is handled Exceptions NullPointerException: if any argument is null Since 17

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:String: the string to be returned from description()
operation:Consumer<HttpExchange>: the operation of the returned filter

Returns:Filter

a filter whose operation is invoked after the exchange is handled

Exceptions

NullPointerException:: if any argument is null

Since

beforeHandler back to summary

beforeHandler	back to summary
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:String the string to be returned from `description()` operation:Consumer<HttpExchange> the operation of the returned filter Returns:Filter a filter whose operation is invoked before the exchange is handled Exceptions NullPointerException: if any argument is null Since 17

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:String: the string to be returned from description()
operation:Consumer<HttpExchange>: the operation of the returned filter

Returns:Filter

a filter whose operation is invoked before the exchange is handled

Exceptions

NullPointerException:: if any argument is null

Since

description back to summary

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

public abstract String description()

Returns a short description of this Filter.

Returns:String: a String describing the Filter

doFilter back to summary

doFilter	back to summary
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: Invoke the next filter in the chain, by calling `Filter.Chain#doFilter(HttpExchange)`. 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:HttpExchange the `HttpExchange` to be filtered chain:Filter.Chain the `Chain` which allows the next filter to be invoked Exceptions IOException: may be thrown by any filter module, and if caught, must be rethrown again NullPointerException: if either exchange or chain are `null`

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:HttpExchange: the HttpExchange to be filtered
chain:Filter.Chain: the Chain which allows the next filter to be invoked

Exceptions

IOException:: may be thrown by any filter module, and if caught, must be rethrown again
NullPointerException:: if either exchange or chain are null

com.sun.net.httpserver back to summary

public Class Filter.Chain

Class Inheritance

extends Object

java.lang.Object
com.sun.net.httpserver.Filter.Chain

A chain of filters associated with a HttpServer. Each filter in the chain is given one of these so it can invoke the next filter in the chain.

Field Summary

Modifier and Type	Field and Description
private HttpHandler	handler
private ListIterator<Filter>	iter The last element in the chain must invoke the user's handler.

Constructor Summary

Access	Constructor and Description
public	Chain(List<Filter> the filters that make up the `Chain` filters, HttpHandler the `HttpHandler` that will be invoked after the final `Filter` has finished handler) Creates a `Chain` instance with given filters and handler.

Method Summary

Modifier and Type	Method and Description
public void	doFilter(HttpExchange the `HttpExchange` exchange) Calls the next filter in the chain, or else the users exchange handler, if this is the final filter in the chain.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

handler	back to summary
private HttpHandler handler

iter	back to summary
private ListIterator<Filter> iter The last element in the chain must invoke the user's handler.

Constructor Detail

Chain back to summary

Chain	back to summary
public Chain(List<Filter> filters, HttpHandler handler) Creates a `Chain` instance with given filters and handler. Parameters filters:List<Filter> the filters that make up the `Chain` handler:HttpHandler the `HttpHandler` that will be invoked after the final `Filter` has finished

public Chain(List<Filter> filters, HttpHandler handler)

Creates a Chain instance with given filters and handler.

Parameters

filters:List<Filter>: the filters that make up the Chain
handler:HttpHandler: the HttpHandler that will be invoked after the final Filter has finished

Method Detail

doFilter back to summary

doFilter	back to summary
public void doFilter(HttpExchange exchange) throws IOException Calls the next filter in the chain, or else the users exchange handler, if this is the final filter in the chain. The `Filter` may decide to terminate the chain, by not calling this method. In this case, the filter must send the response to the request, because the application's exchange handler will not be invoked. Parameters exchange:HttpExchange the `HttpExchange` Exceptions IOException: if an I/O error occurs NullPointerException: if exchange is `null`

public void doFilter(HttpExchange exchange) throws IOException

Calls the next filter in the chain, or else the users exchange handler, if this is the final filter in the chain. The Filter may decide to terminate the chain, by not calling this method. In this case, the filter must send the response to the request, because the application's exchange handler will not be invoked.

Parameters

exchange:HttpExchange: the HttpExchange

Exceptions

IOException:: if an I/O error occurs
NullPointerException:: if exchange is null

public abstract Class Filter

Nested and Inner Type Summary

Constructor Summary

Method Summary

Constructor Detail

Method Detail

public Class Filter.Chain

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail