Recent SSLSocket close() @apiNote Changes.

[Bradford Wetmore]

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