RFR: 8356154: Respecify java.net.Socket constructors that allow creating UDP sockets to throw IllegalArgumentException [v8]

[Jaikiran Pai]

On Tue, 6 May 2025 15:22:02 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> Jaikiran Pai has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Michael's review suggestions
>
> src/java.base/share/classes/java/net/Socket.java line 390:
> 
>> 388:      * The {@code stream} parameter provided a way in early JDK releases
>> 389:      * to create a {@code Socket} that used a datagram socket. This feature
>> 390:      * no longer exists.
> 
> Should we also re-iterate here that this constructor is deprecated? It kind of feels like this information should be in `@deprecated` instead, or that it should say that IAE is being thrown...

Hello Daniel, do you mean something like this:

-     * @apiNote
-     * The {@code stream} parameter provided a way in early JDK releases
-     * to create a {@code Socket} that used a datagram socket. This feature
-     * no longer exists.
-     *
      * @param      host     the IP address.
      * @param      port      the port number.
      * @param      stream    must be true, false is not allowed.
@@ -429,7 +424,9 @@ public Socket(String host, int port, boolean stream) throws IOException {
      *             or if the port parameter is outside the specified range of valid
      *             port values, which is between 0 and 65535, inclusive.
      * @throws     NullPointerException if {@code host} is null.
-     * @deprecated Use {@link DatagramSocket} instead for UDP transport.
+     * @deprecated The {@code stream} parameter provided a way in early JDK releases
+     *             to create a {@code Socket} that used a datagram socket. This feature
+     *             no longer exists. Use {@link DatagramSocket} instead for UDP transport.


Having that text in `@deprecated` does convey the reason for deprecation and does show up prominently in the rendered javadoc:

<img width="1097" alt="doc" src="https://github.com/user-attachments/assets/897e581e-28c4-424c-b3f9-3bce4591cb7e" />


So if you and others think we should remove the apiNote and move the text to deprecated, then I'll update the PR and the CSR.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/25031#discussion_r2077324431