Summary

Filter::beforeHandler and Filter::afterHandler: Clarify the exception handling for the case in which the filter operation throws an unchecked exception.

Filter::afterHandler: Clarify the timely relation between the execution of the filter operation and the sending of the response.

Problem

The filter operation Consumer that is passed to the factory methods can throw an unchecked exception but the documentation does not describe the behaviour in this case.

In the case of Filter::afterHandler, the filter operation is commonly executed after the response has been sent. This is not spelled out in the documentation.

Solution

Add a sentence to the documentation of both factory methods that clarifies the exception handling, as well as a sentence on the order of the filter operation and the sending of the response to Filter::afterHandler.

Specification

src/jdk.httpserver/share/classes/com/sun/net/httpserver/Filter.java

      * <p>The {@link Consumer operation} is the effective implementation of the
      * filter. It is executed for each {@code HttpExchange} before invoking
      * either the next filter in the chain or the exchange handler (if this is
-     * the final filter in the chain).
+     * the final filter in the chain). Exceptions thrown by the
+     * {@code operation} are not handled by the filter.

...

      * <p>The {@link Consumer operation} is the effective implementation of the
      * filter. It is executed for each {@code HttpExchange} after invoking
      * either the next filter in the chain or the exchange handler (if this
-     * filter is the final filter in the chain).
+     * filter is the final filter in the chain). Exceptions thrown by the
+     * {@code operation} are not handled by the filter.
      *
      * @apiNote
      * An afterHandler filter is typically used to examine the exchange state
      * rather than modifying it. The filter {@code operation} is executed after
      * {@link Filter.Chain#doFilter(HttpExchange)} is invoked, this means any
      * subsequent filters in the chain and the exchange handler have been
      * executed. The filter {@code operation} is not expected to handle the
      * exchange or {@linkplain HttpExchange#sendResponseHeaders(int, long) send the response headers}.
      * Doing so is likely to fail, since the exchange has commonly been handled
-     * before the operation is invoked.
+     * before the {@code operation} is invoked. More specifically, the response
+     * may be sent before the filter {@code operation} is executed.