[Internet]Recent SSLSocket close() @apiNote Changes.

[xueleifan(XueleiFan)]

Hi Brad,

I think you are right that this design is actually for TLSv1.3 half-close mode.  For TLS 1.3,  there is no duplex closure design.  The close() implementation in JDK is actually a workaround for compatibility.  Application can use either the half-close mode
  socket.shutdownOutput();
  socket.shutdownInput();

or duplex close mode for compatibilty:
  socket.close();

Unfortunately, in practice the half-close and duplex close are mixed with three lines:
  socket.shutdownOutput();
  socket.shutdownInput();
  socket.close();

It was not something I expected when I designed the spec for half-close mode.  It should be helpful if having another iteration for the @apiNote.

Thanks,
Xuelei


> On Mar 2, 2022, at 5:14 PM, Bradford Wetmore <bradford.wetmore at oracle.com> wrote:
> 
> 
> Hi Xuelei,
> 
> I am working on some close code including the recent PR[1] for:
> 
>    8282529: Fix API Note in javadoc for javax.net.ssl.SSLSocket
> 
> and ran into a change I hadn't noticed before.
> 
> * @apiNote
> * When the connection is no longer needed, the client and server
> * applications should each close both sides of their respective connection.
> * For {@code SSLSocket} objects, for example, an application can call
> * {@link Socket#shutdownOutput()} for output stream close and call
> * {@link Socket#shutdownInput()} for input stream close.
> 
> It used to be that just a single SSLSocket.close() was sufficient to completely shutdown the SSLSocket, and under the hood it closed the output/input in the right order.
> 
> I believe this code still closes everything as before, but the updated @apiNote encourages the user to do a three-part shutdown instead.
> 
>   socket.shutdownOutput();
>   socket.shutdownInput();
>   socket.close();            // mostly repeats of above.
> 
> This approach seems unnecessary unless the user is interested in the TLSv1.3 half-close mode.
> 
> What is the rationale for recommending this way of doing closes in general?  Or does this @apiNote need another iteration?
> 
> Thanks,
> 
> Brad
> 
> [1] https://github.com/openjdk/jdk/pull/7648
>