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

[Daniel Fuchs]

On Mon, 9 Jun 2025 07:39:02 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.

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

> 623:      *
> 624:      * @apiNote Establishing a TCP/IP connection is subject to connection timeout settings
> 625:      * in the operating system. The typical timeout is 60 seconds. If the operating system

Suggestion:

     * in the operating system. The typical operating system timeout is 60 seconds. If the operating system


I would suggest repeating "operating system timeout" here too, to remove confusion with the simple API `timeout` which also appears later in this paragraph.

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

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