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