Summary

Clarification to apidoc for com.sun.net.httpserver.HttpServer.createContext. No behavior change.

Problem

Due to an oversight, the two createContext methods were not required to have the path parameter end with a '/' character. This can result in surprising behavior if the path does not end with '/'. Rather than 'fix' this behavior we just propose to document it.

Solution

An apiNote to clarify the behavior.

Specification

Add an apiNote to both createContext methods of com.sun.net.httpserver.HttpServer.

+++ b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpServer.java   Thu Jul 04 12:09:58 2019 +0100
@@ -206,6 +206,10 @@
      * '/'. <p>
      * The class overview describes how incoming request URIs are <a href="#mapping_description">mapped</a>
      * to HttpContext instances.
+     * @apiNote The path should generally, but is not required to, end with '/'. If the path does not
+     * end with '/', eg such as with {@code "/foo"} then this would match requests with a path of
+     * {@code "/foobar"} or {@code "/foo/bar"}.
+     *
      * @param path the root URI path to associate the context with
      * @param handler the handler to invoke for incoming requests.
      * @throws IllegalArgumentException if path is invalid, or if a context
@@ -227,6 +231,10 @@
      * '/'. <p>
      * The class overview describes how incoming request URIs are <a href="#mapping_description">mapped</a>
      * to HttpContext instances.
+     * @apiNote The path should generally, but is not required to, end with '/'. If the path does not
+     * end with '/', eg such as with {@code "/foo"} then this would match requests with a path of
+     * {@code "/foobar"} or {@code "/foo/bar"}.
+     *
      * @param path the root URI path to associate the context with
      * @throws IllegalArgumentException if path is invalid, or if a context
      *          already exists for this path