Simone,
Based on the answers you've provided, careful thinking and re-reading
appropriate parts of the RFC, I think we might find the following solution a
good compromise. (Please note that here I'm only talking about Close message
representation. Other topics discussed, like returning CS/CF from onClose will
be addressed later.)
default void onClose(WebSocket webSocket, int statusCode, String reason) { }
CompletableFuture<Void> sendClose();
CompletableFuture<Void> sendClose(int statusCode, String reason);
To your credit, you proposed something similar back in October 2015 [1], [2].
But now we have a good supporting argument based on special status code (1005)
built into the protocol. Which is sort of a built-in Optional.
Let me mention a couple of differences, though.
1. The type of the reason is String, not ByteBuffer.
2. There's a sendClose() with no args, for those who don't want to know anything
about status codes and reason strings.
3. There are no enums, named int constants, or other special gimmicks for status
code exposed.
Simply because a) there are no names defined for them in the RFC b) to not put
disproportional focus in the API on the Close message. If one wants to handle
codes they'd better go and read the RFC to understand the precise meaning.
4. There will be an asymmetry.
I'm ok with receiving 1005/1006, after all it helps to get away with not having
an int in the message. But I don't think it should be allowed to stick any of
these codes into sendClose(int, String) and to make the implementation to treat
them specially. Representation for an empty Close message can be bound to
sendClose().
The implication is that you won't be able to do this (for example):
void onClose(WebSocket webSocket, int statusCode, String reason) {
webSocket.sendClose(statusCode, reason);
}
Just because the received statusCode might be one of the special ones.
What do you think?
--------------------------------------------------------------------------------
[1] http://mail.openjdk.java.net/pipermail/net-dev/2015-October/009248.html
[2] http://mail.openjdk.java.net/pipermail/net-dev/2015-October/009242.html
> On 2 Jun 2016, at 21:58, Simone Bordet <simone.bor...@gmail.com> wrote:
>
> Hi,
>
> On Thu, Jun 2, 2016 at 10:40 PM, Pavel Rappo <pavel.ra...@oracle.com> wrote:
>> 1. Are there any cases where the app needs to know that Close message was in
>> fact
>> empty?
>
> Not that I know.
>
>> 2. Does the app behaviour (especially, parsing the reason phrase/description)
>> depend on the status code?
>
> Not much really. My experience is that it is only logged.
> Even when a server closes a connection for idle timeout or shutdown,
> there is not much that the client can do.
> For a client receiving a 1001 or a network exception, it can only show
> to the client application something like "connection lost" and retry
> periodically to contact the server again.
>
>> 3. If the app initiates the Closing handshake, what Close message does it
>> send?
>
> Until a little time ago, browsers were forbidding to send a close with
> a code != 1000.
> Now looks like they have relaxed this restriction. Not sure how many
> applications make use of different codes, but I don't think many.
>
>> 4. Which codes does the app distinguish?
>
> Here is the gist of the whole thing.
> WebSocket is a very low-level protocol. Applications don't use
> "WebSocket", they use a protocol on top of WebSocket.
> Take Bayeux (https://docs.cometd.org/current/reference/#_bayeux), for
> example: it has its own "connect" and "disconnect" semantic *on top*
> of WebSocket.
> Take WAMP (http://wamp-proto.org/spec/), it has a HELLO and GOODBYE
> messages *on top* of WebSocket. GOODBYE even has close codes that
> duplicates those defined in WebSocket (e.g. 1001).
> And so on.
>
> So at the end, applications don't really use the WebSocket close codes
> because WebSocket is only used as a transport protocol for some other
> protocol (unless very simple cases).
>
> I'd keep it simple and clear, and always offering a close code in the
> API (and thus get rid of the Optional).
>
> Thanks !
>
> --
> Simone Bordet
> http://bordet.blogspot.com
> ---
> Finally, no matter how good the architecture and design are,
> to deliver bug-free software with optimal performance and reliability,
> the implementation technique must be flawless. Victoria Livschitz
