Summary

A number of small specification clarifications and rewordings to supplement the already approved HTTP Client, JDK-8197565.

Problem

Feedback from a number of sources including, JCK, both internal and external engineers, have identified:

• a number of small deficiencies in the specification that require clarification, and

• opportunities to simplify the API by removing a superfluous public type and enum value, and

• opportunities to reword certain targeted sections of text, mainly in WebSocket, to avoid ambiguity thus avoiding misunderstanding.

Solution

1) From HttpClient.Redirect remove SAME_PROTOCOL and SECURE. Replace with NORMAL. Leaving { ALWAYS, NORMAL, NEVER }. It has been observed that the previously named SECURE was not really appropriately named and should be renamed to NORMAL, since it will likely be suitable for most normal cases. Given the newly named, aforementioned, NORMAL, SAME_PROTOCOL appears oddly named, possibly confusing, and not likely to be used.

2) Remove WebSocket.MessagePart. This enum was used on the the receiving side to indicate whether the delivery of message was complete, or not. It is asymmetric with the sending side, which uses a simple boolean for this purpose. Additionally, it has been observed that handling received messages with a simple boolean significantly reduces and simplifies the receiving code logic. Determination of messages being delivered as a WHOLE, one of the benefits and the main purposes for the aforementioned MessagePart, has proved to not carry its own weight. Note: as part of this review, MessagePart, and variants thereof, have been considered and dismissed, on the sending side, as they obstruct one of the most common patterns of iterating over data and sending it as chunks.

3) Throughout the WebSocket documentation care has been taken to avoid ambiguity between websocket messages and the number of invocations of the WebSocket.Listener. The number of messages may not equal the number of listener invocations, as partial messages may be delivered. This has been a source of confusion when folk first start using the API.

4) WebSocket does not ( for good reasons ) use the Java SE reactive-stream support in java.util.concurrent.Flow, but its request ( invocation demand ) is heavily influenced by it, and the API can be used to build higher-level Flow's using such. This concept, since analogous to Flow ( Subscriber and Subscription), has been clarified. These changes touch a lot of documentation, but it has not changed semantically.

5) The WebSocket specification around closure has been tightened up and several corner cases clarified. Again, this touches many parts of the spec, but has not changed significantly.

6) Outbound data flow, in the WebSocket API, is pressured by CompletableFutures returned by the sendBinary and sendText methods. Equivalent have been added to the less-data driven sendPing and sendPong methods to prevent outbound saturation.

7) The WebSocket API throws NullPointerException directly from methods where a null value is passed, but completes exceptionally returned CompletableFutures in almost all other cases. This is a decision that was made to simplify and streamline error handling. The HttpClient API exposes significantly less CompletableFutures, typically just a single CF from sendAsync, which results in less burdensome error handling, therefore throws ( rather than completes exceptionally ) when illegal arguments are passed.

Specification

Specdiff in attached zip file, or browsable online at: http://cr.openjdk.java.net/~chegar/httpclient/supplementary/overview-summary.html