Preliminary RFR JDK-8159053: Improve onPing/onClose behavior

[Simone Bordet]

Hi,

On Thu, Jun 23, 2016 at 2:19 PM, Pavel Rappo <pavel.rappo at oracle.com> wrote:
> Summing up, I would propose to change the whole paragraph to this:
>
> * <p> After a Close message has been received, the {@code WebSocket}
> * will close <i>automatically</i>.

I would remove this. It is clear from the text below *when* the
implementation will send the reply close frame.

> However, the client may finish
> * sending the current sequence of message parts, if any.

I think you should not use the word "client" since it's not clear if
you refer to the application or the implementation.
Here it can be mistaken for both, but it's really the implementation.
However, the readers of the Javadocs will mostly be application
writers and would interpret it as the application.

> To facilitate this,

Remove it: "facilitation" is an implementation detail.

> the {@code WebSocket} will close after the completion of the
> * returned {@code CompletionStage} or earlier if a Close message has
> * been sent.

I would add:

"The implementation will take care of sending the reply close frame to
the server and close the underlying TCP connection.
Applications _may_ explicitly invoke sendClose() if they want to send
a different code or reason in the reply close frame."

> I think the behaviour of the WebSocket in case the client tries to start a new
> messages sequence from within onClose (if the previous one has been finished) is
> implementation specific. It might report to onError, or send a Close message
> automatically or both. What's important is that the server SHOULD NOT receive
> any part of the new message.

I think this is wrong.
Leaving room to "implementation specific" details is allowing for
writing applications that are not portable.

WebSocket's close mechanism is a double half close, like TCP.
In TCP the semantic is very clear: sideA can half close, sideB can
continue sending data, sideA will continue reading data, until sideB
half closes.
Same semantic in WebSocket.

WebSocket's onClose() is invoked when the server has half closed,
similar to reading -1 from TCP.
That only means that the server will not send more data.
The client side could send data, and the server must receive it
without problems.
Once the client decides it's finished sending data, it will return
from onClose(), and the implementation will send the reply close frame
(if not already sent by the application).

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