Hi Pavel,
I would avoid terms like application and client in any specification or
API description,
it may be that the caller of the API is another library.
The javadoc should focus on the behavior of each method when it is called.
$.02, Roger
On 6/23/2016 10:09 AM, Pavel Rappo wrote:
Simone,
On 23 Jun 2016, at 14:48, Simone Bordet <simone.bor...@gmail.com> wrote:
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.
Is this some kind of a clever sarcasm, designed to point out the ambiguity in
question? Because I actually meant the *application*. Consider the following
flow of events (let's assume a simplified scenario where all CFs from sendText
are returned already completed):
|->sendText("...", false);
|->sendText("...", false);
|<-onClose()
|->sendText("...", false); (A)
|->sendText("...", true); (B)
onClose() has been received, but the application can still send messages until
the last chunk has been finally sent. Do you agree with this?
I think this is wrong.
Leaving room to "implementation specific" details is allowing for
writing applications that are not portable.
We're talking about an extremely rare corner case, where we guarantee that a new
message WILL NOT be sent to the server. The difference is how the WebSocket will
react on attempting to do so.
Okay, I'm fine with REQUIRING is a new message is a attempted to be send, WS
will send a Close message instead and complete the CF returned from send
operation exceptionally.
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).
I'm not a TCP expert. Does TCP allow an endpoint to skip the data it receives
after this endpoint has half-closed the connection? Because WebSocket does:
...However, there is no guarantee that the
endpoint that has already sent a Close frame will continue to process
data...
Thanks,
-Pavel