RFR [13] 8225426: Replace plain with system-default in Socket and ServerSocket

[Chris Hegarty]

Alan, Daniel,

> On 7 Jun 2019, at 13:07, Alan Bateman <Alan.Bateman at oracle.com> wrote:
> 
> On 07/06/2019 12:24, Chris Hegarty wrote:
>> ...
> Replacing with "plain" with system-default is okay but it does remind me of problems in the other constructors. The no-arg Socket constructor is currently specified to use a system-default SocketImpl but that isn't correct when a client socket implementation factory is set.

Good catch, I was not aware of this one. Easy to fix while here.
Added, see below.

> The Socket(Proxy) constructor is also ambiguous for the Proxy.DIRECT case as it's not clear which SocketImpl should be used. 

I’d like to address this one separately, as there are other issues
related to that specific constructor, as you have described in
8216985 [1].


Complete set of changes ( will be copied as-is into the CSR ):
---

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

     /**
      * Creates a server socket, bound to the specified port. A port number
      * of {@code 0} means that the port number is automatically
      * allocated, typically from an ephemeral port range. This port
      * number can then be retrieved by calling {@link #getLocalPort getLocalPort}.
      * <p>
      * The maximum queue length for incoming connection indications (a
      * request to connect) is set to {@code 50}. If a connection
      * indication arrives when the queue is full, the connection is refused.
      * <p>
      * If the application has specified a server socket factory, that
      * factory's {@code createSocketImpl} method is called to create
-     * the actual socket implementation. Otherwise a "plain" socket is created.
+     * the actual socket implementation. Otherwise a system-default
+     * socket implementation is created.
      * <p>
      * If there is a security manager,
      * its {@code checkListen} method is called
      * with the {@code port} argument
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      *...
      */
     public ServerSocket(int port) throws IOException

     /**
      * Creates a server socket and binds it to the specified local port
      * number, with the specified backlog.
      * A port number of {@code 0} means that the port number is
      * automatically allocated, typically from an ephemeral port range.
      * This port number can then be retrieved by calling
      * {@link #getLocalPort getLocalPort}.
      * <p>
      * The maximum queue length for incoming connection indications (a
      * request to connect) is set to the {@code backlog} parameter. If
      * a connection indication arrives when the queue is full, the
      * connection is refused.
      * <p>
      * If the application has specified a server socket factory, that
      * factory's {@code createSocketImpl} method is called to create
-     * the actual socket implementation. Otherwise a "plain" socket is created.
+     * the actual socket implementation. Otherwise a system-default
+     * socket implementation is created.
      * <p>
      * If there is a security manager,
      * its {@code checkListen} method is called
      * with the {@code port} argument
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
      * ...
      */
     public ServerSocket(int port, int backlog) throws IOException


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

     /**
-     * Creates an unconnected socket, with the
-     * system-default type of SocketImpl.
+     * Creates an unconnected socket.
+     *
+     * If the application has specified a client socket factory, that
+     * factory's {@code createSocketImpl} method is called to create
+     * the actual socket implementation. Otherwise a system-default
+     * socket implementation is created.
      *
      * @since   1.1
      * @revised 1.4
      */
     public Socket()

     /**
      * Creates a stream socket and connects it to the specified port
      * number on the named host.
      * <p>
      * If the specified host is {@code null} it is the equivalent of
      * specifying the address as
      * {@link java.net.InetAddress#getByName InetAddress.getByName}{@code (null)}.
      * In other words, it is equivalent to specifying an address of the
      * loopback interface. </p>
      * <p>
-     * If the application has specified a server socket factory, that
+     * If the application has specified a client socket factory, that
      * factory's {@code createSocketImpl} method is called to create
-     * the actual socket implementation. Otherwise a "plain" socket is created.
+     * the actual socket implementation. Otherwise a system-default
+     * socket implementation is created.
      * <p>
      * If there is a security manager, its
      * {@code checkConnect} method is called
      * with the host address and {@code port}
      * as its arguments. This could result in a SecurityException.
      *
      * ...
      */
     public Socket(String host, int port)

     /**
      * Creates a stream socket and connects it to the specified port
      * number at the specified IP address.
      * <p>
-     * If the application has specified a socket factory, that factory's
-     * {@code createSocketImpl} method is called to create the
-     * actual socket implementation. Otherwise a "plain" socket is created.
+     * If the application has specified a client socket factory, that
+     * factory's {@code createSocketImpl} method is called to create
+     * the actual socket implementation. Otherwise a system-default
+     * socket implementation is created.
      * <p>
      * If there is a security manager, its
      * {@code checkConnect} method is called
      * with the host address and {@code port}
      * as its arguments. This could result in a SecurityException.
      *
      * ...
      */
     public Socket(InetAddress address, int port) throws IOException

     /**
      * Creates a stream socket and connects it to the specified port
      * number on the named host.
      * <p>
      * If the specified host is {@code null} it is the equivalent of
      * specifying the address as
      * {@link java.net.InetAddress#getByName InetAddress.getByName}{@code (null)}.
      * In other words, it is equivalent to specifying an address of the
      * loopback interface. </p>
      * <p>
      * If the stream argument is {@code true}, this creates a
      * stream socket. If the stream argument is {@code false}, it
      * creates a datagram socket.
      * <p>
-     * If the application has specified a server socket factory, that
+     * If the application has specified a client socket factory, that
      * factory's {@code createSocketImpl} method is called to create
-     * the actual socket implementation. Otherwise a "plain" socket is created.
+     * the actual socket implementation. Otherwise a system-default
+     * socket implementation is created.
      * <p>
      * If there is a security manager, its
      * {@code checkConnect} method is called
      * with the host address and {@code port}
      * as its arguments. This could result in a SecurityException.
      * <p>
      * If a UDP socket is used, TCP/IP related socket options will not apply.
      *...
      */
     @Deprecated
     public Socket(String host, int port, boolean stream) throws IOException

     /**
      * Creates a socket and connects it to the specified port number at
      * the specified IP address.
      * <p>
      * If the stream argument is {@code true}, this creates a
      * stream socket. If the stream argument is {@code false}, it
      * creates a datagram socket.
      * <p>
-     * If the application has specified a server socket factory, that
+     * If the application has specified a client socket factory, that
      * factory's {@code createSocketImpl} method is called to create
-     * the actual socket implementation. Otherwise a "plain" socket is created.
+     * the actual socket implementation. Otherwise a system-default
+     * socket implementation is created.
      *
      * <p>If there is a security manager, its
      * {@code checkConnect} method is called
      * with {@code host.getHostAddress()} and {@code port}
      * as its arguments. This could result in a SecurityException.
      * <p>
      * If UDP socket is used, TCP/IP related socket options will not apply.
      *
      * ...
      */
     @Deprecated
     public Socket(InetAddress host, int port, boolean stream) throws IOException
—

-Chris.

[1] https://bugs.openjdk.java.net/browse/JDK-8216985