RFR: 8267140: Support closing the HttpClient by making it auto-closable [v3]

[Jaikiran Pai]

On Mon, 20 Mar 2023 10:50:12 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> src/java.net.http/share/classes/java/net/http/HttpClient.java line 816:
>> 
>>> 814:      * @since 21
>>> 815:      */
>>> 816:     public void shutdownNow() {
>> 
>> The first sentence of the `shutdownNow` api doc should describe the behavior of the method itself, ie that it does an immediate shutdown.
>> 
>> Also, I wonder if there is another way to formulate these implSpec comments? Naive readers might think they have to override the method.
>
> I have added some text to the `@apiNote` and added a link in all the `@implSpec`. Does that read better?

I think this part in this method's javadoc is a bit out of place:

> It is called if the thread waiting on {@link #close()} is interrupted.

It is just one of the place from where this method will be called from. Since the `shutdownNow()` is a public API, it could be called by applications too. Perhaps we should just remove that sentence from that method's javadoc? The javadoc of `close()` explains in a better way that this `shutdownNow()` method might get invoked from within `close()`, which I think should be enough.

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

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