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

[Alan Bateman]

On Tue, 6 May 2025 07:26:05 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> Can I please get a review of this change which proposes to respecify the 2 `java.net.Socket` constructors that allow construction of UDP sockets? This addresses https://bugs.openjdk.org/browse/JDK-8356154.
>> 
>> As noted in that JBS issue, in Java 23 we deprecated for removal the 2 `Socket` constructors that allowed UDP socket creation. The plan continues to be to remove those constructors. Before removing those, in order to allow for applications to notice this deprecation, these constructors are now being respecified to throw an `IllegalArgumentException` when the `stream` parameter is `false`.
>> 
>> I will create a CSR once we settle on these changes.
>> 
>> tier1 through tier8 tests have been run with this change and no related failures have been noticed.
>
> Jaikiran Pai has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Alan's review suggestion - simplify Socket constructor API documentation

src/java.base/share/classes/java/net/Socket.java line 384:

> 382:      * stream socket. If the stream argument is {@code false}, it
> 383:      * creates a datagram socket.
> 384:      * <p>

One final though on the Socket changes is that maybe we should include an API note to say that the stream parameter provided a way in early JDK releases to create a Socket that used a datagram socket, this feature no longer exists.

src/java.base/share/classes/java/net/SocketImpl.java line 86:

> 84:      * The {@code stream} parameter provided a way in early JDK releases
> 85:      * to create a {@link Socket} that used a datagram socket.
> 86:      * It is no longer possible to do that and therefore this method will

"It is no longer possible to do that ...", can you try changing this to "The Socket API no longer provides a way to do this so the create method will ways to be called with a stream value of true". I think it might be a bit easier to read.

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

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