Summary
-------
The minimal set of options required to be supported by each socket type in the java.net package should be explicitly documented.
Problem
-------
The socket types in the java.net package do not specify the minimum set
of standard socket options that they are required to support. To help assert compliance checks the set of Java SE standard options that are required to be supported should be explicitly documented in each of the socket types, similar to what is done for the channels area, e.g. SocketChannel, etc.
Solution
--------
The class level API documentation of each socket type in the java.net package is augmented with a table that lists the minimal set of option that this socket type supports.
Webrev link provided for convenience: http://cr.openjdk.java.net/~dfuchs/webrev_8235141/webrev.00/
Specification
-------------
--- old/src/java.base/share/classes/java/net/DatagramSocket.java 2019-12-02 15:01:43.000000000 +0000
+++ new/src/java.base/share/classes/java/net/DatagramSocket.java 2019-12-02 15:01:43.000000000 +0000
@@ -43,24 +43,69 @@
* <p> Where possible, a newly constructed {@code DatagramSocket} has the
- * {@link SocketOptions#SO_BROADCAST SO_BROADCAST} socket option enabled so as
+ * {@link StandardSocketOptions#SO_BROADCAST SO_BROADCAST} socket option enabled so as
* to allow the transmission of broadcast datagrams. In order to receive
* broadcast packets a DatagramSocket should be bound to the wildcard address.
* In some implementations, broadcast packets may also be received when
* a DatagramSocket is bound to a more specific address.
>[...]
+ * <p> The {@code DatagramSocket} class defines convenience
+ * methods to set and get several socket options. This class also
+ * defines the {@link #setOption(SocketOption,Object) setOption}
+ * and {@link #getOption(SocketOption) getOption} methods to set
+ * and query socket options.
+ * A {@code DatagramSocket} supports the following socket options:
+ * <blockquote>
+ * <a id="SocketOptions"></a>
+ * <table class="striped">
+ * <caption style="display:none">Socket options</caption>
+ * <thead>
+ * <tr>
+ * <th scope="col">Option Name</th>
+ * <th scope="col">Description</th>
+ * </tr>
+ * </thead>
+ * <tbody>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </th>
+ * <td> The size of the socket send buffer </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </th>
+ * <td> The size of the socket receive buffer </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </th>
+ * <td> Re-use address </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_BROADCAST SO_BROADCAST} </th>
+ * <td> Allow transmission of broadcast datagrams </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#IP_TOS IP_TOS} </th>
+ * <td> The Type of Service (ToS) octet in the Internet Protocol (IP) header </td>
+ * </tr>
+ * </tbody>
+ * </table>
+ * </blockquote>
+ * An implementation may also support additional options. In particular an implementation
+ * may support <a href="MulticastSocket.html#MulticastOptions">multicast options</a> which
+ * can be useful when using a plain {@code DatagramSocket} to send datagrams to a
+ * multicast group.
+ *
--- old/src/java.base/share/classes/java/net/MulticastSocket.java 2019-12-02 15:01:45.000000000 +0000
+++ new/src/java.base/share/classes/java/net/MulticastSocket.java 2019-12-02 15:01:45.000000000 +0000
@@ -78,7 +78,45 @@
* Multiple MulticastSocket's</B> may subscribe to a multicast group
* and port concurrently, and they will all receive group datagrams.
* <P>
- * Currently applets are not allowed to use multicast sockets.
+ *
+ * <p> The {@code DatagramSocket} and {@code MulticastSocket}
+ * classes defines convenience methods to set and get several
+ * socket options. Like {@code DatagramSocket} this class also
+ * supports the {@link #setOption(SocketOption, Object) setOption}
+ * and {@link #getOption(SocketOption) getOption} methods to set
+ * and query socket options.
+ * In addition to the socket options supported by
+ * <a href="DatagramSocket.html#SocketOptions">{@code DatagramSocket}</a>, a
+ * {@code MulticastSocket} supports the following socket options:
+ * <blockquote>
+ * <a id="MulticastOptions"></a>
+ * <table class="striped">
+ * <caption style="display:none">Socket options</caption>
+ * <thead>
+ * <tr>
+ * <th scope="col">Option Name</th>
+ * <th scope="col">Description</th>
+ * </tr>
+ * </thead>
+ * <tbody>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_IF IP_MULTICAST_IF} </th>
+ * <td> The network interface for Internet Protocol (IP) multicast datagrams </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_TTL
+ * IP_MULTICAST_TTL} </th>
+ * <td> The <em>time-to-live</em> for Internet Protocol (IP) multicast
+ * datagrams </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP
+ * IP_MULTICAST_LOOP} </th>
+ * <td> Loopback for Internet Protocol (IP) multicast datagrams </td>
+ * </tr>
+ * </tbody>
+ * </table>
+ * </blockquote>
+ * Additional (implementation specific) options may also be supported.
--- old/src/java.base/share/classes/java/net/ServerSocket.java 2019-12-02 15:01:47.000000000 +0000
+++ new/src/java.base/share/classes/java/net/ServerSocket.java 2019-12-02 15:01:46.000000000 +0000
@@ -46,6 +46,35 @@
+ * <p> The {@code ServerSocket} class defines convenience
+ * methods to set and get several socket options. This class also
+ * defines the {@link #setOption(SocketOption, Object) setOption}
+ * and {@link #getOption(SocketOption) getOption} methods to set
+ * and query socket options.
+ * A {@code ServerSocket} supports the following options:
+ * <blockquote>
+ * <table class="striped">
+ * <caption style="display:none">Socket options</caption>
+ * <thead>
+ * <tr>
+ * <th scope="col">Option Name</th>
+ * <th scope="col">Description</th>
+ * </tr>
+ * </thead>
+ * <tbody>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </th>
+ * <td> The size of the socket receive buffer </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </th>
+ * <td> Re-use address </td>
+ * </tr>
+ * </tbody>
+ * </table>
+ * </blockquote>
+ * Additional (implementation specific) options may also be supported.
+ *
--- old/src/java.base/share/classes/java/net/Socket.java 2019-12-02 15:01:48.000000000 +0000
+++ new/src/java.base/share/classes/java/net/Socket.java 2019-12-02 15:01:48.000000000 +0000
@@ -50,6 +50,52 @@
+ * <p> The {@code Socket} class defines convenience
+ * methods to set and get several socket options. This class also
+ * defines the {@link #setOption(SocketOption, Object) setOption}
+ * and {@link #getOption(SocketOption) getOption} methods to set
+ * and query socket options.
+ * A {@code Socket} support the following options:
+ * <blockquote>
+ * <table class="striped">
+ * <caption style="display:none">Socket options</caption>
+ * <thead>
+ * <tr>
+ * <th scope="col">Option Name</th>
+ * <th scope="col">Description</th>
+ * </tr>
+ * </thead>
+ * <tbody>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </th>
+ * <td> The size of the socket send buffer </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </th>
+ * <td> The size of the socket receive buffer </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_KEEPALIVE SO_KEEPALIVE} </th>
+ * <td> Keep connection alive </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </th>
+ * <td> Re-use address </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#SO_LINGER SO_LINGER} </th>
+ * <td> Linger on close if data is present (when configured in blocking mode
+ * only) </td>
+ * </tr>
+ * <tr>
+ * <th scope="row"> {@link java.net.StandardSocketOptions#TCP_NODELAY TCP_NODELAY} </th>
+ * <td> Disable the Nagle algorithm </td>
+ * </tr>
+ * </tbody>
+ * </table>
+ * </blockquote>
+ * Additional (implementation specific) options may also be supported.
+ *