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

[Chris Hegarty]

> On 7 Jun 2019, at 15:02, Alan Bateman <Alan.Bateman at oracle.com> wrote:
> 
> 
> 
> On 07/06/2019 14:20, Chris Hegarty wrote:
>> 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.
> Looks good.
> 
> In passing, the methods that set factory are specified to set the "client socket implementation factory" or "server socket implementation factory" but in other places they are referred to as the "client socket factory" or "server socket factory". I don't think it matters too much but I noticed it when looking at the diffs.


“socket implementation factory” is better. Updated:

---

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.
+     * If the application has specified a server socket implementation
+     * 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 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.
+     * If the application has specified a server socket implementation
+     * 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 checkListen} method is called
      * with the {@code port} argument
      * as its argument to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
      * The {@code backlog} argument is the requested maximum number of
      * pending connections on the socket. Its exact semantics are implementation
      * specific. In particular, an implementation may impose a maximum length
      * or may choose to ignore the parameter altogether. The value provided
      * should be greater than {@code 0}. If it is less than or equal to
      * {@code 0}, then an implementation specific default will be used.
      *
      * ...
      */
     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 implementation
+     * 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
-     * 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 implementation
+     * 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(String host, int port)
         throws UnknownHostException, IOException
 
     /**
      * 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 implementation
+     * 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
-     * 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 implementation
+     * 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.
      * ...
      */
     @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
-     * 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 implementation
+     * 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 {@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.