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.
