HTTP Client refresh

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.

Specification

See attached specdiff.zip, or browse online.