stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8329745: Update the documentation of ServerSocket and Socket to refer to StandardSocketOptions instead of legacy SocketOptions

Browse Source 
Reviewed-by: alanb, dfuchs
This commit is contained in:
Jaikiran Pai 2024-04-09 13:04:14 +00:00
parent 5c9f03686d
commit 635cb3c976
2 changed files with 94 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
src/java.base/share/classes/java/net/ServerSocket.java
View File

@ -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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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 <B>java.net.SocketTimeoutException</B> 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 <B>must</B> 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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}.
* <p>
* 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()}.
* <p>
* 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.
* <p>
* 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}.
*
* <p>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)

142
src/java.base/share/classes/java/net/Socket.java
View File

@ -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.
* <p>
* 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. </p>
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
*
* <p>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.
*
* <p>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()}.
* <p>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.
*
* <p>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.
*
* <p>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()}.
* <p>Because {@code SO_RCVBUF} is a hint, applications that want to verify
* what size the buffers were set to should call {@link #getReceiveBufferSize()}.
*
* <p>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.
* <p>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 <B>before</B> 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* When a {@code Socket} is created the initial setting
* of {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is disabled.
* of {@code SO_REUSEADDR} is disabled.
* <p>
* 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