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

[Alan Bateman]

On Wed, 7 May 2025 10:29:44 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> 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.

Okay with me but for SocketImpl then I think it has to be an apiNote as the create method is not deprecated.

BTW: "Use DatagramSocket instead for UDP transport" switches the terminology. The first sentence uses "datagram socket" so I best to use that in the second sentence to avoid "UDP" and "transport".

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

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