WebSocket client API

[Pavel Rappo]

> On 20 Oct 2015, at 14:32, Simone Bordet <simone.bordet at gmail.com> wrote:
> 
> So why choosing CharBuffer ?

Because in general when an API provides a callback method `c`

   <ReturnType> c(<ParameterTye> x)

an application has to implement, it should better be the case that the
<ParameterType> is the most specific type possible (with possibly more methods
and stricter guarantees) and the <ReturnType> is the least specific type
possible (weaker guarantees).

Note: it's obviously the opposite with an API's method `m` the application has
to call:
 
    <ReturnType> m(<ParameterTye> x)
    
<ReturnType> is the most specific possible, the <ParameterTye> is the least
specific possible.

> The only thing you can do with it is to copy, one more time and with
> no need to, the chars it contains before using them.

Not true. One could use it as Appendable or CharSequence. Or, which is an extra
win, encode it into a ByteBuffer (probably with different encoding) and write
the resulting thing to a Channel.

> Providing a CharSequence, instead, leaves the implementation much more
> room and has the potential to avoid unnecessary copies.

"More room"? Maybe. Unnecessary copies -- highly doubt it. What would
an application (an API's user) need to do to write this CharSequence to
a Channel?

    CompletableFuture<?> onText(CharSequence text, boolean isLast) {
        ...
        if (text instanceof CharBuffer) {
            cb = (CharBuffer) text;
        } else {
            cb = CharBuffer.wrap(text);
        }

        encoder.encode(cb, bb, isLast);
        channel.write(bb);
        ...
    }

------------
So the implementation is very honest here. It returns the same object it's just
used for a decoding. Whether a code snippet above worth weakening the type
passed (from CharBuffer to CharSequence) is something to think about.

As for me, I need to think about it.

> The implementation could synthesize the bytes into a String, and pass
> that to the application without further copies (with some JDK help).

Any specific examples?