Summary

An API Note was introduced by JDK-8208526 that described the new closing behavior of SSLSocket for TLSv1.3. Subsequent work done by JDK-8216326 reverted the implementation behavior to match that of Sockets and previous SSLSockets (pre-JDK11), but the API Note was not updated to reflect the correct behavior.

Problem

The existing @apiNote is incorrect and out of date.

(Apparently CSRs are not needed for @apiNotes, but will complete one for visibility and reviewer eyes.)

Solution

In order to support TLSv1.3 1/2 closed sockets, JDK-8207009(bug)/JDK-8208526(CSR) introduced behavior into the JDK 11 APIs and implementations which was not consistent with the normal behavior of InputStream/OutputStreams created by Sockets and SSLSockets. Closing a Socket's InputStream/OutputStream is expected to close the associated underlying Socket.

java.net.Socket
public OutputStream getOutputStream() throws IOException

Returns an output stream for this socket. 
...deleted...
Closing the returned OutputStream will close the associated socket.

With JDK-8207009, calling InputStream/OutputStream.close() did not close the underlying SSLSocket, only the input or output side.

This was later noticed by JDK-8216326, which fixed the incorrect behavior in 13 and was backported to 11.0.5. This change probably should have had a CSR, but I am unable to find one for it. Unfortunately, the incorrect API documentation was not noticed during JDK-8216326 and has remained.

Specification

Change the @apiNote in javax.net.ssl.SSLSocket.java

src/java.base/share/classes/javax/net/ssl/SSLSocket.java
@@ -172,21 +172,23 @@
  * </pre></blockquote>
  *
  * @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()} or {@link java.io.OutputStream#close()}
- * for output stream close and call {@link Socket#shutdownInput()} or
- * {@link java.io.InputStream#close()} for input stream close.  Note that
- * in some cases, closing the input stream may depend on the peer's output
- * stream being closed first.  If the connection is not closed in an orderly
- * manner (for example {@link Socket#shutdownInput()} is called before the
- * peer's write closure notification has been received), exceptions may
- * be raised to indicate that an error has occurred.  Once an
- * {@code SSLSocket} is closed, it is not reusable: a new {@code SSLSocket}
- * must be created.
+ * This can be done either in one shot by calling {@link Socket#close()},
+ * or by closing each side individually using
+ * {@link Socket#shutdownOutput()} / {@link Socket#shutdownInput()} which is
+ * useful for protocol versions that can support half-closed connections.
+ *
+ * <P> Note that in some cases, closing the input stream may depend on the
+ * peer's output stream being closed first.  If the connection is not closed
+ * in an orderly manner (for example {@link Socket#shutdownInput()} is called
+ * before the peer's write closure notification has been received), exceptions
+ * may be raised to indicate that an error has occurred.
+ *
+ * <P> Once an {@code SSLSocket} is closed, it is not reusable: a new
+ * {@code SSLSocket} must be created.