Summary
-------

There is no easy way to cancel a request sent through the `java.net.http.HttpClient`. This change proposes to handle thread interruption (when in synchronous mode) and `CompletableFuture.cancel(true)` (when in asynchronous mode) to release resources associated with an inflight request when the caller is no longer interested in the response.

Problem
-------

There is no easy way to cancel a request sent through the `java.net.http.HttpClient`. A natural way may seem to call `Thread.interrupt()` on the thread waiting for the response, or to cancel the `CompletableFuture` returned by the `HttpClient`, but although both will cause an exception to be thrown, the actual request will typically continue in the background as if nothing had happened. This is typically an issue when using virtual threads, as  `HttpClient::send` will throw an `InterruptedException` when interrupted but will not cancel the request. 

Solution
--------

This change proposes to handle thread interruption (when in synchronous mode) and `CompletableFuture.cancel(true)` (when in asynchronous mode) to release resources associated with an inflight request when the caller is no longer interested in the response.

Specification
-------------

The concepts of default `HttpClient` implementation and *cancelable* futures are introduced.

src/java.net.http/share/classes/java/net/http/HttpClient.java

A clarification is added to the class level API documentation:

      *
      * <p> An {@code HttpClient} can be used to send {@linkplain HttpRequest
      * requests} and retrieve their {@linkplain HttpResponse responses}. An {@code
    - * HttpClient} is created through a {@link HttpClient#newBuilder() builder}. The
    - * builder can be used to configure per-client state, like: the preferred
    + * HttpClient} is created through a {@link HttpClient.Builder builder}.
    + * The {@link #newBuilder() newBuilder} method returns a builder that creates
    + * instances of the default {@code HttpClient} implementation.
    + * The builder can be used to configure per-client state, like: the preferred
      * protocol version ( HTTP/1.1 or HTTP/2 ), whether to follow redirects, a
      * proxy, an authenticator, etc. Once built, an {@code HttpClient} is immutable,
      * and can be used to send multiple requests.

A paragraph is added to the API documentation of the `newBuilder` method:

         /**
          * Creates a new {@code HttpClient} builder.
          *
    +     * <p> Builders returned by this method create instances
    +     * of the default {@code HttpClient} implementation.
    +     *
          * @return an {@code HttpClient.Builder}
          */
         public static Builder newBuilder() {

A paragraph is added to the API documentation of the `HttpClient::send` method:

    +     * <p> If the operation is interrupted, the default {@code HttpClient}
    +     * implementation attempts to cancel the HTTP exchange and
    +     * {@link InterruptedException} is thrown.
    +     * No guarantee is made as to exactly <em>when</em> the cancellation request
    +     * may be taken into account. In particular, the request might still get sent
    +     * to the server, as its processing might already have started asynchronously
    +     * in another thread, and the underlying resources may only be released
    +     * asynchronously.
    +     * <ul>
    +     *     <li>With HTTP/1.1, an attempt to cancel may cause the underlying
    +     *         connection to be closed abruptly.
    +     *     <li>With HTTP/2, an attempt to cancel may cause the stream to be reset,
    +     *         or in certain circumstances, may also cause the connection to be
    +     *         closed abruptly, if, for instance, the thread is currently trying
    +     *         to write to the underlying socket.
    +     * </ul>
    +     *

A paragraph is added to the API documentation of the three args `HttpClient::sendAsync` method:

    +     * <p> The default {@code HttpClient} implementation returns
    +     * {@code CompletableFuture} objects that are <em>cancelable</em>.
    +     * {@code CompletableFuture} objects {@linkplain CompletableFuture#newIncompleteFuture()
    +     * derived} from cancelable futures are themselves <em>cancelable</em>.
    +     * Invoking {@linkplain CompletableFuture#cancel(boolean) cancel(true)}
    +     * on a cancelable future that is not completed, attempts to cancel the HTTP exchange
    +     * in an effort to release underlying resources as soon as possible.
    +     * No guarantee is made as to exactly <em>when</em> the cancellation request
    +     * may be taken into account. In particular, the request might still get sent
    +     * to the server, as its processing might already have started asynchronously
    +     * in another thread, and the underlying resources may only be released
    +     * asynchronously.
    +     * <ul>
    +     *     <li>With HTTP/1.1, an attempt to cancel may cause the underlying connection
    +     *         to be closed abruptly.
    +     *     <li>With HTTP/2, an attempt to cancel may cause the stream to be reset.
    +     * </ul>
    +     *