From 635cb3c9762aeaec6c8dd2c21b8323d187236b4f Mon Sep 17 00:00:00 2001 From: Jaikiran Pai Date: Tue, 9 Apr 2024 13:04:14 +0000 Subject: [PATCH] 8329745: Update the documentation of ServerSocket and Socket to refer to StandardSocketOptions instead of legacy SocketOptions Reviewed-by: alanb, dfuchs --- .../share/classes/java/net/ServerSocket.java | 57 ++++--- .../share/classes/java/net/Socket.java | 142 +++++++++--------- 2 files changed, 94 insertions(+), 105 deletions(-) diff --git a/src/java.base/share/classes/java/net/ServerSocket.java b/src/java.base/share/classes/java/net/ServerSocket.java index 5c57dc15ca9..b3e570c858a 100644 --- a/src/java.base/share/classes/java/net/ServerSocket.java +++ b/src/java.base/share/classes/java/net/ServerSocket.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2024, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -140,9 +140,10 @@ public class ServerSocket implements java.io.Closeable { * request to connect) is set to {@code 50}. If a connection * indication arrives when the queue is full, the connection is refused. *

- * 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 + * If the application has specified a {@linkplain SocketImplFactory server + * socket implementation factory}, that factory's + * {@linkplain SocketImplFactory#createSocketImpl() createSocketImpl} method + * is called to create the actual socket implementation. Otherwise a system-default * socket implementation is created. *

* If there is a security manager, @@ -163,7 +164,6 @@ public class ServerSocket implements java.io.Closeable { * the specified range of valid port values, which is between * 0 and 65535, inclusive. * - * @see java.net.SocketImpl * @see SecurityManager#checkListen */ public ServerSocket(int port) throws IOException { @@ -183,9 +183,10 @@ public class ServerSocket implements java.io.Closeable { * a connection indication arrives when the queue is full, the * connection is refused. *

- * 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 + * If the application has specified a {@linkplain SocketImplFactory server + * socket implementation factory}, that factory's + * {@linkplain SocketImplFactory#createSocketImpl() createSocketImpl} method + * is called to create the actual socket implementation. Otherwise a system-default * socket implementation is created. *

* If there is a security manager, @@ -214,7 +215,6 @@ public class ServerSocket implements java.io.Closeable { * the specified range of valid port values, which is between * 0 and 65535, inclusive. * - * @see java.net.SocketImpl * @see SecurityManager#checkListen */ public ServerSocket(int port, int backlog) throws IOException { @@ -261,8 +261,6 @@ public class ServerSocket implements java.io.Closeable { * the specified range of valid port values, which is between * 0 and 65535, inclusive. * - * @see SocketOptions - * @see SocketImpl * @see SecurityManager#checkListen * @since 1.1 */ @@ -801,7 +799,7 @@ public class ServerSocket implements java.io.Closeable { * specified timeout, in milliseconds. With this option set to a positive * timeout value, a call to accept() for this ServerSocket * will block for only this amount of time. If the timeout expires, - * a java.net.SocketTimeoutException is raised, though the + * a {@link java.net.SocketTimeoutException} is raised, though the * ServerSocket is still valid. A timeout of zero is interpreted as an * infinite timeout. * The option must be enabled prior to entering the blocking @@ -843,7 +841,7 @@ public class ServerSocket implements java.io.Closeable { } /** - * Enable/disable the {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} + * Enable/disable the {@link StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} * socket option. *

* When a TCP connection is closed the connection may remain @@ -855,22 +853,22 @@ public class ServerSocket implements java.io.Closeable { * {@code SocketAddress} if there is a connection in the * timeout state involving the socket address or port. *

- * Enabling {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} prior to - * binding the socket using {@link #bind(SocketAddress)} allows the socket - * to be bound even though a previous connection is in a timeout state. + * Enabling {@code SO_REUSEADDR} prior to binding the socket using + * {@link #bind(SocketAddress)} allows the socket to be bound even + * though a previous connection is in a timeout state. *

* When a {@code ServerSocket} is created the initial setting - * of {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is not defined. - * Applications can use {@link #getReuseAddress()} to determine the initial - * setting of {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR}. + * of {@code SO_REUSEADDR} is not defined. Applications can use + * {@link #getReuseAddress()} to determine the initial + * setting of {@code SO_REUSEADDR}. *

- * The behaviour when {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is - * enabled or disabled after a socket is bound (See {@link #isBound()}) + * The behaviour when {@code SO_REUSEADDR} is enabled or disabled + * after a socket is bound (See {@link #isBound()}) * is not defined. * * @param on whether to enable or disable the socket option * @throws SocketException if an error occurs enabling or - * disabling the {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} + * disabling the {@code SO_REUSEADDR} * socket option, or the socket is closed. * @since 1.4 * @see #getReuseAddress() @@ -885,10 +883,10 @@ public class ServerSocket implements java.io.Closeable { } /** - * Tests if {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled. + * Tests if {@link StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled. * * @return a {@code boolean} indicating whether or not - * {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled. + * {@code SO_REUSEADDR} is enabled. * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. * @since 1.4 @@ -981,14 +979,14 @@ public class ServerSocket implements java.io.Closeable { /** * Sets a default proposed value for the - * {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option for sockets + * {@link StandardSocketOptions#SO_RCVBUF SO_RCVBUF} option for sockets * accepted from this {@code ServerSocket}. The value actually set * in the accepted socket must be determined by calling * {@link Socket#getReceiveBufferSize()} after the socket * is returned by {@link #accept()}. *

- * The value of {@link SocketOptions#SO_RCVBUF SO_RCVBUF} is used both to - * set the size of the internal socket receive buffer, and to set the size + * The value of {@code SO_RCVBUF} is used both to set the size of + * the internal socket receive buffer, and to set the size * of the TCP receive window that is advertised to the remote peer. *

* It is possible to change the value subsequently, by calling @@ -1024,14 +1022,13 @@ public class ServerSocket implements java.io.Closeable { } /** - * Gets the value of the {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option + * Gets the value of the {@link StandardSocketOptions#SO_RCVBUF SO_RCVBUF} option * for this {@code ServerSocket}, that is the proposed buffer size that * will be used for Sockets accepted from this {@code ServerSocket}. * *

Note, the value actually set in the accepted socket is determined by * calling {@link Socket#getReceiveBufferSize()}. - * @return the value of the {@link SocketOptions#SO_RCVBUF SO_RCVBUF} - * option for this {@code Socket}. + * @return the value of the {@code SO_RCVBUF} option for this {@code Socket}. * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. * @see #setReceiveBufferSize(int) diff --git a/src/java.base/share/classes/java/net/Socket.java b/src/java.base/share/classes/java/net/Socket.java index e291dc829fa..7d0b2acda99 100644 --- a/src/java.base/share/classes/java/net/Socket.java +++ b/src/java.base/share/classes/java/net/Socket.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2024, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -172,10 +172,11 @@ public class Socket implements java.io.Closeable { /** * 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. + * If the application has specified a {@linkplain SocketImplFactory client + * socket implementation factory}, that factory's + * {@linkplain SocketImplFactory#createSocketImpl() createSocketImpl} + * method is called to create the actual socket implementation. Otherwise + * a system-default socket implementation is created. * * @since 1.1 */ @@ -295,10 +296,11 @@ public class Socket implements java.io.Closeable { * In other words, it is equivalent to specifying an address of the * loopback interface.

*

- * 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. + * If the application has specified a {@linkplain SocketImplFactory client + * socket implementation factory}, that factory's + * {@linkplain SocketImplFactory#createSocketImpl() createSocketImpl} + * method is called to create the actual socket implementation. Otherwise + * a system-default socket implementation is created. *

* If there is a security manager, its * {@code checkConnect} method is called @@ -317,7 +319,6 @@ public class Socket implements java.io.Closeable { * @throws IllegalArgumentException if the port parameter is outside * the specified range of valid port values, which is between * 0 and 65535, inclusive. - * @see java.net.SocketImpl * @see SecurityManager#checkConnect */ @SuppressWarnings("this-escape") @@ -333,10 +334,11 @@ public class Socket implements java.io.Closeable { * Creates a stream socket and connects it to the specified port * number at the specified IP address. *

- * 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. + * If the application has specified a {@linkplain SocketImplFactory client + * socket implementation factory}, that factory's + * {@linkplain SocketImplFactory#createSocketImpl() createSocketImpl} + * method is called to create the actual socket implementation. Otherwise + * a system-default socket implementation is created. *

* If there is a security manager, its * {@code checkConnect} method is called @@ -352,7 +354,6 @@ public class Socket implements java.io.Closeable { * the specified range of valid port values, which is between * 0 and 65535, inclusive. * @throws NullPointerException if {@code address} is null. - * @see java.net.SocketImpl * @see SecurityManager#checkConnect */ @SuppressWarnings("this-escape") @@ -461,10 +462,11 @@ public class Socket implements java.io.Closeable { * stream socket. If the stream argument is {@code false}, it * creates a datagram 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. + * If the application has specified a {@linkplain SocketImplFactory client + * socket implementation factory}, that factory's + * {@linkplain SocketImplFactory#createSocketImpl() createSocketImpl} + * method is called to create the actual socket implementation. Otherwise + * a system-default socket implementation is created. *

* If there is a security manager, its * {@code checkConnect} method is called @@ -483,7 +485,6 @@ public class Socket implements java.io.Closeable { * @throws IllegalArgumentException if the port parameter is outside * the specified range of valid port values, which is between * 0 and 65535, inclusive. - * @see java.net.SocketImpl * @see SecurityManager#checkConnect * @deprecated Use DatagramSocket instead for UDP transport. */ @@ -503,10 +504,11 @@ public class Socket implements java.io.Closeable { * stream socket. If the stream argument is {@code false}, it * creates a datagram 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. + * If the application has specified a {@linkplain SocketImplFactory client + * socket implementation factory}, that factory's + * {@linkplain SocketImplFactory#createSocketImpl() createSocketImpl} + * method is called to create the actual socket implementation. Otherwise + * a system-default socket implementation is created. * *

If there is a security manager, its * {@code checkConnect} method is called @@ -526,7 +528,6 @@ public class Socket implements java.io.Closeable { * the specified range of valid port values, which is between * 0 and 65535, inclusive. * @throws NullPointerException if {@code host} is null. - * @see java.net.SocketImpl * @see SecurityManager#checkConnect * @deprecated Use DatagramSocket instead for UDP transport. */ @@ -1244,10 +1245,10 @@ public class Socket implements java.io.Closeable { } /** - * Enable/disable {@link SocketOptions#TCP_NODELAY TCP_NODELAY} + * Enable/disable {@link StandardSocketOptions#TCP_NODELAY TCP_NODELAY} * (disable/enable Nagle's algorithm). * - * @param on {@code true} to enable TCP_NODELAY, + * @param on {@code true} to enable {@code TCP_NODELAY}, * {@code false} to disable. * * @throws SocketException if there is an error @@ -1264,10 +1265,10 @@ public class Socket implements java.io.Closeable { } /** - * Tests if {@link SocketOptions#TCP_NODELAY TCP_NODELAY} is enabled. + * Tests if {@link StandardSocketOptions#TCP_NODELAY TCP_NODELAY} is enabled. * * @return a {@code boolean} indicating whether or not - * {@link SocketOptions#TCP_NODELAY TCP_NODELAY} is enabled. + * {@code TCP_NODELAY} is enabled. * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. * @since 1.1 @@ -1280,7 +1281,7 @@ public class Socket implements java.io.Closeable { } /** - * Enable/disable {@link SocketOptions#SO_LINGER SO_LINGER} with the + * Enable/disable {@link StandardSocketOptions#SO_LINGER SO_LINGER} with the * specified linger time in seconds. The maximum timeout value is platform * specific. * @@ -1310,13 +1311,13 @@ public class Socket implements java.io.Closeable { } /** - * Returns setting for {@link SocketOptions#SO_LINGER SO_LINGER}. + * Returns setting for {@link StandardSocketOptions#SO_LINGER SO_LINGER}. * -1 returns implies that the * option is disabled. * * The setting only affects socket close. * - * @return the setting for {@link SocketOptions#SO_LINGER SO_LINGER}. + * @return the setting for {@code SO_LINGER}. * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. * @since 1.1 @@ -1364,8 +1365,7 @@ public class Socket implements java.io.Closeable { * and there is no capability to distinguish between normal data and urgent * data unless provided by a higher level protocol. * - * @param on {@code true} to enable - * {@link SocketOptions#SO_OOBINLINE SO_OOBINLINE}, + * @param on {@code true} to enable {@code SO_OOBINLINE}, * {@code false} to disable. * * @throws SocketException if there is an error @@ -1385,7 +1385,7 @@ public class Socket implements java.io.Closeable { * Tests if {@link SocketOptions#SO_OOBINLINE SO_OOBINLINE} is enabled. * * @return a {@code boolean} indicating whether or not - * {@link SocketOptions#SO_OOBINLINE SO_OOBINLINE} is enabled. + * {@code SO_OOBINLINE} is enabled. * * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. @@ -1427,7 +1427,7 @@ public class Socket implements java.io.Closeable { * Returns setting for {@link SocketOptions#SO_TIMEOUT SO_TIMEOUT}. * 0 returns implies that the option is disabled (i.e., timeout of infinity). * - * @return the setting for {@link SocketOptions#SO_TIMEOUT SO_TIMEOUT} + * @return the setting for {@code SO_TIMEOUT} * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. * @@ -1447,15 +1447,13 @@ public class Socket implements java.io.Closeable { } /** - * Sets the {@link SocketOptions#SO_SNDBUF SO_SNDBUF} option to the + * Sets the {@link StandardSocketOptions#SO_SNDBUF SO_SNDBUF} option to the * specified value for this {@code Socket}. - * The {@link SocketOptions#SO_SNDBUF SO_SNDBUF} option is used by the - * platform's networking code as a hint for the size to set the underlying - * network I/O buffers. + * The {@code SO_SNDBUF} option is used by the platform's networking code + * as a hint for the size to set the underlying network I/O buffers. * - *

Because {@link SocketOptions#SO_SNDBUF SO_SNDBUF} is a hint, - * applications that want to verify what size the buffers were set to - * should call {@link #getSendBufferSize()}. + *

Because {@code SO_SNDBUF} is a hint, applications that want to verify + * what size the buffers were set to should call {@link #getSendBufferSize()}. * * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. @@ -1478,11 +1476,10 @@ public class Socket implements java.io.Closeable { } /** - * Get value of the {@link SocketOptions#SO_SNDBUF SO_SNDBUF} option + * Get value of the {@link StandardSocketOptions#SO_SNDBUF SO_SNDBUF} option * for this {@code Socket}, that is the buffer size used by the platform * for output on this {@code Socket}. - * @return the value of the {@link SocketOptions#SO_SNDBUF SO_SNDBUF} - * option for this {@code Socket}. + * @return the value of the {@code SO_SNDBUF} option for this {@code Socket}. * * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. @@ -1502,22 +1499,20 @@ public class Socket implements java.io.Closeable { } /** - * Sets the {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option to the + * Sets the {@link StandardSocketOptions#SO_RCVBUF SO_RCVBUF} option to the * specified value for this {@code Socket}. The - * {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option is - * used by the platform's networking code as a hint for the size to set - * the underlying network I/O buffers. + * {@code SO_RCVBUF} option is used by the platform's networking code + * as a hint for the size to set the underlying network I/O buffers. * *

Increasing the receive buffer size can increase the performance of * network I/O for high-volume connection, while decreasing it can * help reduce the backlog of incoming data. * - *

Because {@link SocketOptions#SO_RCVBUF SO_RCVBUF} is a hint, - * applications that want to verify what size the buffers were set to - * should call {@link #getReceiveBufferSize()}. + *

Because {@code SO_RCVBUF} is a hint, applications that want to verify + * what size the buffers were set to should call {@link #getReceiveBufferSize()}. * - *

The value of {@link SocketOptions#SO_RCVBUF SO_RCVBUF} is also used - * to set the TCP receive window that is advertised to the remote peer. + *

The value of {@code SO_RCVBUF} is also used to set the TCP receive window + * that is advertised to the remote peer. * Generally, the window size can be modified at any time when a socket is * connected. However, if a receive window larger than 64K is required then * this must be requested before the socket is connected to the @@ -1550,12 +1545,11 @@ public class Socket implements java.io.Closeable { } /** - * Gets the value of the {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option + * Gets the value of the {@link StandardSocketOptions#SO_RCVBUF SO_RCVBUF} option * for this {@code Socket}, that is the buffer size used by the platform * for input on this {@code Socket}. * - * @return the value of the {@link SocketOptions#SO_RCVBUF SO_RCVBUF} - * option for this {@code Socket}. + * @return the value of the {@code SO_RCVBUF} option for this {@code Socket}. * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. * @see #setReceiveBufferSize(int) @@ -1573,7 +1567,7 @@ public class Socket implements java.io.Closeable { } /** - * Enable/disable {@link SocketOptions#SO_KEEPALIVE SO_KEEPALIVE}. + * Enable/disable {@link StandardSocketOptions#SO_KEEPALIVE SO_KEEPALIVE}. * * @param on whether or not to have socket keep alive turned on. * @throws SocketException if there is an error @@ -1588,10 +1582,10 @@ public class Socket implements java.io.Closeable { } /** - * Tests if {@link SocketOptions#SO_KEEPALIVE SO_KEEPALIVE} is enabled. + * Tests if {@link StandardSocketOptions#SO_KEEPALIVE SO_KEEPALIVE} is enabled. * * @return a {@code boolean} indicating whether or not - * {@link SocketOptions#SO_KEEPALIVE SO_KEEPALIVE} is enabled. + * {@code SO_KEEPALIVE} is enabled. * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. * @since 1.3 @@ -1647,7 +1641,7 @@ public class Socket implements java.io.Closeable { * traffic class or type-of-service * @since 1.4 * @see #getTrafficClass - * @see SocketOptions#IP_TOS + * @see StandardSocketOptions#IP_TOS */ public void setTrafficClass(int tc) throws SocketException { if (tc < 0 || tc > 255) @@ -1671,14 +1665,14 @@ public class Socket implements java.io.Closeable { * traffic class or type-of-service value. * @since 1.4 * @see #setTrafficClass(int) - * @see SocketOptions#IP_TOS + * @see StandardSocketOptions#IP_TOS */ public int getTrafficClass() throws SocketException { return ((Integer) (getImpl().getOption(SocketOptions.IP_TOS))).intValue(); } /** - * Enable/disable the {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} + * Enable/disable the {@link StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} * socket option. *

* When a TCP connection is closed the connection may remain @@ -1690,21 +1684,19 @@ public class Socket implements java.io.Closeable { * {@code SocketAddress} if there is a connection in the * timeout state involving the socket address or port. *

- * Enabling {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} - * prior to binding the socket using {@link #bind(SocketAddress)} allows - * the socket to be bound even though a previous connection is in a timeout - * state. + * Enabling {@code SO_REUSEADDR} prior to binding the socket using + * {@link #bind(SocketAddress)} allows the socket to be bound even + * though a previous connection is in a timeout state. *

* When a {@code Socket} is created the initial setting - * of {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is disabled. + * of {@code SO_REUSEADDR} is disabled. *

- * The behaviour when {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is - * enabled or disabled after a socket is bound (See {@link #isBound()}) - * is not defined. + * The behaviour when {@code SO_REUSEADDR} is enabled or disabled after + * a socket is bound (See {@link #isBound()}) is not defined. * * @param on whether to enable or disable the socket option * @throws SocketException if an error occurs enabling or - * disabling the {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} + * disabling the {@code SO_REUSEADDR} * socket option, or the socket is closed. * @since 1.4 * @see #getReuseAddress() @@ -1719,10 +1711,10 @@ public class Socket implements java.io.Closeable { } /** - * Tests if {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled. + * Tests if {@link StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled. * * @return a {@code boolean} indicating whether or not - * {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled. + * {@code SO_REUSEADDR} is enabled. * @throws SocketException if there is an error * in the underlying protocol, such as a TCP error. * @since 1.4