RFR: 8296804: Document HttpClient configuration properties in java.net.http module-info [v3]

[Daniel Fuchs]

On Mon, 21 Nov 2022 12:31:44 GMT, Michael McMahon <michaelm at openjdk.org> wrote:

>> Hi,
>> 
>> Could I get the following doc change reviewed please? It documents the system/networking properties used by the java.net.http HTTP client in its module-info. (CSR to follow)
>> 
>> Thanks,
>> Michael
>
> Michael McMahon has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision:
> 
>  - Merge branch 'master' into http.properties
>  - update after Daniel's review
>  - first draft

src/java.net.http/share/classes/module-info.java line 113:

> 111:  * <li><p><b>{@systemProperty jdk.httpclient.maxstreams}</b> (default: 100)<br>
> 112:  * The maximum number of HTTP/2 streams per connection.
> 113:  * </li>

It might be useful to be a bit more precise here: this is the maximum number of concurrent push streams that a server is allowed to initiate on an HTTP/2 connection

src/java.net.http/share/classes/module-info.java line 133:

> 131:  * This allows the thread to terminate when no longer needed. The value provided is limited
> 132:  * to the range from 1 to 1200(???) seconds.
> 133:  * </li>

Do we need to document this property? If yes then what is the meaning of the `(???)` question marks?

src/java.net.http/share/classes/module-info.java line 136:

> 134:  * <li><p><b>{@systemProperty jdk.httpclient.sendBufferSize}</b> (default: operating system default)<br>
> 135:  * The HTTP client socket send buffer size. Values less than or equal to zero are ignored.
> 136:  * </li>

I wonder if we should make a note that attempting to specify a receive or send buffer size may be detrimental to performance as it might prevent the underlying system to optimize sending and receiving. Also a link to the corresponding StandardOptions may be in order (same for receive buffer size above).

src/java.net.http/share/classes/module-info.java line 139:

> 137:  * <li><p><b>{@systemProperty jdk.internal.httpclient.disableHostnameVerification}</b> (default: false)<br>
> 138:  * If true, hostname verification in SSL certificates is disabled. This is a system property only.
> 139:  * </li>

Should we emphasize that it is intended for testing purposes?

src/java.net.http/share/classes/module-info.java line 147:

> 145:  * A comma separated list of HTTP authentication scheme names, that are disallowed for use by
> 146:  * the HTTP client implementation, for HTTP CONNECT tunneling.
> 147:  * </li>

Should we provide a link to net-properties.html here?

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

PR: https://git.openjdk.org/jdk/pull/11241