RFR: 7116990: (spec) Socket.connect(addr,timeout) not clear if IOException because of TCP timeout [v4]

[Alan Bateman]

On Sun, 15 Jun 2025 04:41:22 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> Can I please get a review of this doc-only change which proposes to add a `@apiNote` to the `Socket.connect(SocketAddress endpoint, int timeout)` method? This addresses https://bugs.openjdk.org/browse/JDK-7116990.
>> 
>> As noted in that issue, users can find it surprising that when the `Socket.connect(...)` method is called with a `timeout` value, then if that timeout value happens to be greater than the connect timeout that operating systems typically impose, then a `IOException` gets thrown instead of the `SocketTimeoutException`. The change in this PR proposes to add a `@apiNote` which explains this current behaviour.
>> 
>> If this requires a CSR, I'll open one once we settle on the proposed text.
>
> Jaikiran Pai has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Mark's suggestion - use "connect timeout" instead of "connection timeout"
>  - Daniel's suggestion for the text

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

> 627:      * {@code timeout} specified to this method then an {@code IOException} is thrown.
> 628:      * The {@code timeout} specified to this method is typically a timeout value that is
> 629:      * shorter than the operating system timeout.

The previous version was a bit clearer but this version is okay too. You might want to consider "is in the range of tens of seconds to ..." rather than "ranges within tens of seconds to ..".

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25690#discussion_r2151522882