RFR [13] 8216988: ServerSocket.implAccept should include warnings about Socket type/state

[Chris Hegarty]

The changes in 8220493 (Prepare Socket/ServerSocket for alternative
platform SocketImpl) disallow a number of scenarios where it is not
possible for `ServerSocket::implAccept` to accept a new connection with
a given Socket. This change proposes to 1) update the specification to
clarify the expected behavior of `implAccept` for these scenarios, i.e.
throw an IOException, and 2) add an implNote describing the behavior of
the system-default SocketImpl.

Additionally, prior to the `implAccept` invocation the given Socket
may be connected, closed, or even have socket options set. A note is
added to warning against this, as the behavior cannot be guaranteed.

src/java.base/share/classes/java/net/ServerSocket.java

     /**
      * Listens for a connection to be made to this socket and accepts
      * it. The method blocks until a connection is made.
      *
      * <p>A new Socket {@code s} is created and, if there
      * is a security manager,
      * the security manager's {@code checkAccept} method is called
      * with {@code s.getInetAddress().getHostAddress()} and
      * {@code s.getPort()}
      * as its arguments to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
+     * @implNote
+     * An instance of this class using a system-default {@code SocketImpl}
+     * accepts sockets with a {@code SocketImpl} of the same type, regardless
+     * of the {@linkplain Socket#setSocketImplFactory(SocketImplFactory)
+     * client socket implementation factory}, if one has been set.
+     *
      * @exception  IOException  if an I/O error occurs when waiting for a
      *               connection.
      * @exception  SecurityException  if a security manager exists and its
      *             {@code checkAccept} method doesn't allow the operation.
      * @exception  SocketTimeoutException if a timeout was previously set with setSoTimeout and
      *             the timeout has been reached.
      * @exception  java.nio.channels.IllegalBlockingModeException
      *             if this socket has an associated channel, the channel is in
      *             non-blocking mode, and there is no connection ready to be
      *             accepted
      *
      * @return the new Socket
      * @see SecurityManager#checkAccept
      * @revised 1.4
      * @spec JSR-51
      */
     public Socket accept() throws IOException

     /**
      * Subclasses of ServerSocket use this method to override accept()
      * to return their own subclass of socket.  So a FooServerSocket
-     * will typically hand this method an <i>empty</i> FooSocket.  On
-     * return from implAccept the FooSocket will be connected to a client.
+     * will typically hand this method a newly created, unbound, FooSocket.
+     * On return from implAccept the FooSocket will be connected to a client.
+     *
+     * <p> The behavior of this method is unspecified when invoked with a
+     * socket that is not newly created and unbound. Any socket options set
+     * on the given socket prior to invoking this method may or may not be
+     * preserved when the connection is accepted. It may not be possible to
+     * accept a connection when this socket has a {@code SocketImpl} of one
+     * type and the given socket has a {@code SocketImpl} of a completely
+     * different type.
+     *
+     * @implNote
+     * An instance of this class using a system-default {@code SocketImpl}
+     * can accept a connection with a Socket using a {@code SocketImpl} of
+     * the same type: {@code IOException} is thrown if the Socket is using
+     * a custom {@code SocketImpl}. An instance of this class using a
+     * custom {@code SocketImpl} cannot accept a connection with a Socket
+     * using a system-default {@code SocketImpl}.
      *
      * @param s the Socket
      * @throws java.nio.channels.IllegalBlockingModeException
      *         if this socket has an associated channel,
      *         and the channel is in non-blocking mode
      * @throws IOException if an I/O error occurs when waiting
-     * for a connection.
+     *         for a connection, or if it is not possible for this socket
+     *         to accept a connection with the given socket
+     *
      * @since   1.1
      * @revised 1.4
      * @spec JSR-51
      */
     protected final void implAccept(Socket s)


CSR for this change:
 https://bugs.openjdk.java.net/browse/JDK-8225431
 
-Chris.