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

[Michael McMahon]

On Mon, 21 Nov 2022 13:41:06 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

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

I would agree with linking to the StandardSocketOption descriptions, as that would also help to distinguish the send buffer option from the write buffer option, which sounds similar. In my view, any discussion of performance trade-offs should be in the StandardSocketOption apidoc rather than here.

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

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