WebSocket API tasks

1. Provide more examples in the API
2. <s>Remove Text interface and sendText(ByteBuffer): JDK-8156650</s>
3. <s>Specify it's up to implementation how to treat incomplete (UTF-16 representation) CharSequences: JDK-8156650</s>
4. <s>Remove word immediately everywhere from methods that return CompletableFuture: JDK-8156693</s>
5. <s>CompletableFuture<WebSocket> instead of CompletableFuture<Void>: JDK-8156693</s>
6. <s>All exceptions other than NPE and IAE should be relayed through CompletableFuture rather than thrown on the spot: JDK-8156693</s>
7. <s>Provide better design for onPong (take care of as much as possible in the implementation rather than delegate to the Listener): JDK-8159053</s>
8. <s>Provide better design for onClose (e.g. return CF to indicate when close can be sent): JDK-8159053</s>
9. <s>Builder.connectTimeout(Duration) instead of Builder.connectTimeout(long, TimeUnit): JDK-8156742</s>
10. <s>void request(long) instead of long request(long): JDK-8156742</s>
11. <s>Remove sendBinary(byte[], boolean): JDK-8156742</s>
12. <s>Remove sendText(Stream<CharSequence>): JDK-8156742</s>
13. <s>Specify it's up to an implementation to serialize Ping, Pong and Close messages with Text and Binary ones however it wants. Given the relative order of messages of the same type (control/non-control) is preserved.</s> One outstanding write. Period.
14. <s>Remove CloseCode and use simple (int, String): JDK-8159053</s>
15. <s>Return an empty String for no subprotocol rather than null</s>
16. <s>if onClose(1006) is signalled instead of onError(), then

onOpen (onText|onBinary|onPing|onPong)* (onClose|onError)?

could be more strict

onOpen (onText|onBinary|onPing|onPong)* onClose|onError</s>

WebSocket implementation tasks

1. <s>Better check subprotocol syntax. Check for separators like

"(" | ")" | "<" | ">" | "@", </s>

1. Think of repeated reading from the channel until the buffer is full or a message is received -- which comes first (optimization).

2. Default implementation of Listener.onError must log the error or do something like

    default void onError(WebSocket webSocket, Throwable error) {
        Thread.currentThread().getUncaughtExceptionHandler()
                .uncaughtException(Thread.currentThread(), error);
    }
   

Or make it abstract.

1. Get rid of ByteBuffer pooling on the receiving side for binary messages as an error-prone activity for user. ByteBuffers can be stored by the user and reused. Bottom line. Slicing? Yes. Pooling? No! At the same time it's absolutely fine to pool CharBuffer, since they are exposed as CharSequence. And CharSequence is implementable, thus we can control access to an already disposed sequences.
2. <s>Own package for the implementation instead of WS type prefix.</s>
3. Consider changing one-off registration with key cancellation for modifying interestOps (see Java™ NIO, 4.5 Selection Scaling); maybe we should put scalability one level higher, i.e. each channel reading/writing task is submitted to an executor? Is key cancellation followed by registration is expensive compared modifying interestOps for the duration of the task?
4. Provide better exception messages, more descriptive and capturing state.
5. <s>Unbounded queue for outgoing messages: JDK-8157273</s> Decided not to do this.
6. <s>Delegate forbidden (used by RFC 6455) headers checking to HttpClient's internals (mainly because of the case-sensitivity rules)</s> It's fine the way it is now.
7. <s>Consider pros and cons of attempting to send from the same thread followed by asynchronous sent of leftovers. Investigate possible problems with stack bloating.</s>
8. Consider ByteBuffer pooling on the sending side.
9. Provide security checks for sendXXX.
10. Move UTF-16 to UTF-8 encoding operations to a point before message acceptance. So these errors become non-fatal: JDK-8156693

Test

1. Group all tests in a dedicated folder
2. Tests must be parametric (i.e. do not have a hardcoded data) where possible

Wordsmithing

1. abort() and isClosed() should agree on terminology. Use either of "TCP connection" or "socket" <s>1. Work out a better notation for sendX/onX in the javadoc. Maybe sendType/onType </s>