Description

Summary

This request consists of a number of small API changes to the new HTTP
Client API, each of which is summarized below.

Problem

Refresh the HTTP Client API based on recent feedback.

Solution

1) Make HttpHeaders final. The abstract HttpHeaders class has been
made final, with a factory method for its construction. By eliminating
a narrow, likely uncommon, performance optimization possibility, it has
been possible to make HttpHeaders final. Given that the class is now
final, additional clarification around header name and value
interpretation, ordering, etc, have been added.

2) Dependent tasks run in the common pool. The default execution of
dependent tasks has been updated to run in the same executor as that of
CompletableFuture's defaultExecutor. This is more familiar to
developers that already use CF, and reduces the likelihood of the HTTP
Client being starved of threads to execute its tasks. This is just
default behaviour, both the HTTP Client and CompletableFuture allow
more fine-grain control, if needed.

3) The immutable flow of response body data has been made an
implementation note, rather than part of the normative specification.
This allows for a more performance focused implementation by making it
possible to directly access the byte buffer's backing byte array.

4) The default executor has been made an implementation note, rather
than part of the normative specification. This allows for the default
to be changed in the future, if a more suitable thread pool executor
were added to the platform.

5) A clarifying note has been added to HttpRequest.Builder that the
HTTP GET method is the default method, if not explicitly set. While
already the case, it was noted during review that the existing note
regarding the default HTTP method, in HttpRequest, is not easily
seen when browsing the Builder javadoc.

6) A clarifying note has been added to WebSocket.Listener that the
invocation of its methods are thread-safe, strictly ordered, and not
reentrant.