Add jwebserver tool

Summary

Provide a dedicated command-line tool for the Simple Web Server, to improve convenience and approachability.

Problem

The Simple Web Server, introduced in JEP 408 [1], is run via the command java -m jdk.httpserver. Unfortunately, the command focuses users' attention on an implementation detail, namely that the Simple Web Server is the main class of a module. This is undesirable given the intended low-ceremony, high-approachability nature of the Simple Web Server.

Solution

Add a dedicated command-line tool for the Simple Web Server, so that it can be run via the command:

$ jwebserver

A wrapper binary is added to the JDK which calls the same implementation class as java -m jdk.httpserver. This hides the implementation detail of the module entry point. A man page is added for the jwebserver tool. The module and package summary are consolidated to reflect the change.

It is still possible to run the Simple Web Server via the java -m ... command. The Simple Web Server's options are the same regardless of how it is run.

Additional advantages include:

• Improved documentation: The Simple Web Server is a feature that targets beginners, so tutorial-like documentation is needed. A man page is a natural, easily-found place for such documentation. We can expand on the minimal documentation that is currently squeezed into the summary of the jdk.httpserver module [2].

• Streamlined experience: A dedicated tool steers developers away from the complexities of the java command, such as the ability to set system properties or enable experimental features.

• Increased observability: A jwebserver process is much easier to identify in process monitoring output than one of many java processes.

[1] https://openjdk.java.net/jeps/408
[2] https://download.java.net/java/early_access/jdk18/docs/api/jdk.httpserver/module-summary.html

Specification

See the attached jwebserver_man for the man page.

jdk.httpserver/share/classes/module-info.java

/**
- * Defines the JDK-specific HTTP server API.
- * <p>
- * A basic high-level API for building embedded servers. Both HTTP and
- * HTTPS are supported.
- * <p>
- * The main components are:
- * <ul>
- * <li>the {@link com.sun.net.httpserver.HttpExchange} class that describes a
- * request and response pair,</li>
- * <li>the {@link com.sun.net.httpserver.HttpHandler} interface to handle
- * incoming requests, plus the {@link com.sun.net.httpserver.HttpHandlers} class
- * that provides useful handler implementations,</li>
- * <li>the {@link com.sun.net.httpserver.HttpContext} class that maps a URI path
- * to a {@code HttpHandler},</li>
- * <li>the {@link com.sun.net.httpserver.HttpServer} class to listen for
- * connections and dispatch requests to handlers,</li>
- * <li>the {@link com.sun.net.httpserver.Filter} class that allows pre- and post-
- * processing of requests.</li></ul>
- * <p>
- * The {@link com.sun.net.httpserver.SimpleFileServer} class offers a simple
- * HTTP file server (intended for testing, development and debugging purposes
- * only). A default implementation is provided via the <a id="entry-point"></a>
- * main entry point of the {@code jdk.httpserver} module, which can be used on
- * the command line as such:
- * <pre>{@code
- *    Usage: java -m jdk.httpserver [-b bind address] [-p port] [-d directory]
- *                                  [-o none|info|verbose] [-h to show options]
- *    Options:
- *    -b, --bind-address    - Address to bind to. Default: 127.0.0.1 or ::1 (loopback).
- *                            For all interfaces use "-b 0.0.0.0" or "-b ::".
- *    -d, --directory       - Directory to serve. Default: current directory.
- *    -o, --output          - Output format. none|info|verbose. Default: info.
- *    -p, --port            - Port to listen on. Default: 8000.
- *    -h, -?, --help        - Print this help message.
- * }</pre>
+ * Defines the JDK-specific HTTP server API, and provides the jwebserver tool
+ * for running a minimal HTTP server.
+ *
+ * <p>The {@link com.sun.net.httpserver} package defines a high-level API for
+ * building servers that support HTTP and HTTPS. The SimpleFileServer class
+ * implements a simple HTTP-only file server intended for testing, development
+ * and debugging purposes. A default implementation is provided via the
+ * {@code jwebserver} tool and the main entry point of the module, which can
+ * also be invoked with {@code java -m jdk.httpserver}.
+ *
+ * <p>The {@link com.sun.net.httpserver.spi} package specifies a Service Provider
+ * Interface (SPI) for locating HTTP server implementations based on the
+ * {@code com.sun.net.httpserver} API.
+ *
+ * @toolGuide jwebserver
  *
  * @uses com.sun.net.httpserver.spi.HttpServerProvider
  *

jdk.httpserver/share/classes/com/sun/net/httpserver/package-info.java

Any HTTP functionality not provided by this API can be implemented by application code
    using the API.
    <p>
+ * The main components are:
+ * <ul>
+ * <li>the {@link com.sun.net.httpserver.HttpExchange} class that describes a
+ * request and response pair,</li>
+ * <li>the {@link com.sun.net.httpserver.HttpHandler} interface to handle
+ * incoming requests, plus the {@link com.sun.net.httpserver.HttpHandlers} class
+ * that provides useful handler implementations,</li>
+ * <li>the {@link com.sun.net.httpserver.HttpContext} class that maps a URI path
+ * to a {@code HttpHandler},</li>
+ * <li>the {@link com.sun.net.httpserver.HttpServer} class to listen for
+ * connections and dispatch requests to handlers,</li>
+ * <li>the {@link com.sun.net.httpserver.Filter} class that allows pre- and post-
+ * processing of requests.</li></ul>
+ * <p>
+ * The {@link com.sun.net.httpserver.SimpleFileServer} class offers a simple
+ * HTTP-only file server (intended for testing, development and debugging purposes
+ * only). A default implementation is provided via the {@code jwebserver} tool.
+   <p>
    Programmers must implement the {@link com.sun.net.httpserver.HttpHandler} interface.

   ...

- * <p>
- * The {@link com.sun.net.httpserver.SimpleFileServer} class offers a simple
- * HTTP file server (intended for testing, development and debugging purposes
- * only). A default implementation is provided via the
- * <a href="{@docRoot}/jdk.httpserver/module-summary.html#entry-point">main entry point</a>
- * of the {@code jdk.httpserver} module.

jdk.httpserver/share/classes/com/sun/net/httpserver/SimpleFileServer.java

- * <h2>Main entry point</h2>
+ * <h2>jwebserver Tool</h2>
  *
- * <p>A <a id="server-impl">simple HTTP file server implementation</a> is
- * provided via the
- * <a href="{@docRoot}/jdk.httpserver/module-summary.html#entry-point">main entry point</a>
- * of the {@code jdk.httpserver} module.
+ * <p>A simple HTTP file server implementation is provided via the
+ * {@code jwebserver} tool.
+ *
+ * @toolGuide jwebserver