8267262: com/sun/net/httpserver/Filter improve API documentation of static methods

Reviewed-by: dfuchs, chegar

Author: Julia Boes

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

@@ -149,7 +149,8 @@ public abstract void doFilter (HttpExchange exchange, Chain chain)
      * <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.
      *
      * @apiNote
      * A beforeHandler filter is typically used to examine or modify the
@@ -197,7 +198,8 @@ public String description() {
      * <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
@@ -207,7 +209,8 @@ public String description() {
      * 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.
      *
      * <p> Example of adding a filter that logs the response code of all exchanges:
      * <pre>{@code

test/jdk/com/sun/net/httpserver/FilterTest.java

@@ -23,6 +23,7 @@
 
 /*
  * @test
+ * @bug 8267262
  * @summary Tests for Filter static factory methods
  * @run testng/othervm FilterTest
  */
@@ -47,13 +48,16 @@
 import com.sun.net.httpserver.HttpHandler;
 import com.sun.net.httpserver.HttpServer;
 import static java.net.http.HttpClient.Builder.NO_PROXY;
+import org.testng.annotations.DataProvider;
 import org.testng.annotations.Test;
 import org.testng.annotations.BeforeTest;
 import static org.testng.Assert.*;
 
 public class FilterTest {
 
     static final Class<NullPointerException> NPE = NullPointerException.class;
+    static final Class<IOException> IOE = IOException.class;
+
     static final InetAddress LOOPBACK_ADDR = InetAddress.getLoopbackAddress();
     static final boolean ENABLE_LOGGING = true;
     static final Logger logger = Logger.getLogger("com.sun.net.httpserver");
@@ -72,19 +76,56 @@ public void setup() {
     public void testNull() {
         expectThrows(NPE, () -> Filter.beforeHandler(null, e -> e.getResponseHeaders().set("X-Foo", "Bar")));
         expectThrows(NPE, () -> Filter.beforeHandler("Some description", null));
-        expectThrows(NPE, () -> Filter.afterHandler(null, HttpExchange::getResponseCode));
+
         expectThrows(NPE, () -> Filter.afterHandler("Some description", null));
+        expectThrows(NPE, () -> Filter.afterHandler(null, HttpExchange::getResponseCode));
     }
 
     @Test
     public void testDescription() {
         var desc = "Some description";
+
         var beforeFilter = Filter.beforeHandler(desc, HttpExchange::getRequestBody);
-        var afterFilter = Filter.afterHandler(desc, HttpExchange::getResponseCode);
         assertEquals(desc, beforeFilter.description());
+
+        var afterFilter = Filter.afterHandler(desc, HttpExchange::getResponseCode);
         assertEquals(desc, afterFilter.description());
     }
 
+    @DataProvider
+    public static Object[][] throwingFilters() {
+        return new Object[][] {
+            {Filter.beforeHandler("before RE", e -> { throw new RuntimeException(); }), IOE},
+            {Filter.beforeHandler("before AE", e -> { throw new AssertionError();   }), IOE},
+
+            {Filter.afterHandler( "after RE",  e -> { throw new RuntimeException(); }), null},
+            {Filter.afterHandler( "after AE",  e -> { throw new AssertionError();   }), null},
+        };
+    }
+
+    @Test(dataProvider = "throwingFilters")
+    public void testException(Filter filter, Class<Exception> exception)
+            throws Exception
+    {
+        var handler = new EchoHandler();
+        var server = HttpServer.create(new InetSocketAddress(LOOPBACK_ADDR,0), 10);
+        server.createContext("/", handler).getFilters().add(filter);
+        server.start();
+        try {
+            var client = HttpClient.newBuilder().proxy(NO_PROXY).build();
+            var request = HttpRequest.newBuilder(uri(server, "")).build();
+            if (exception != null) {
+                expectThrows(exception, () -> client.send(request, HttpResponse.BodyHandlers.ofString()));
+            } else {
+                var response = client.send(request, HttpResponse.BodyHandlers.ofString());
+                assertEquals(response.statusCode(), 200);
+                assertEquals(response.body(), "hello world");
+            }
+        } finally {
+            server.stop(0);
+        }
+    }
+
     @Test
     public void testBeforeHandler() throws Exception {
         var handler = new EchoHandler();