RFR: 8294948: Document IllegalArgumentException and NullPointerException thrown by URLStreamHandler::parseURL and URLStreamHandler::setURL [v8]

[Alan Bateman]

On Tue, 18 Oct 2022 11:56:17 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> During the review of JDK-8293590, it was noted that some methods in `URLStreamHandler` were missing an `@throws IllegalArgumentException` clause in their API documentation. 
>> 
>> This change adds the requested information, and also clarifies throwing `MalformedURLException` from URL constructors.
>> 
>> The CSR can be reviewed here: https://bugs.openjdk.org/browse/JDK-8294984
>
> Daniel Fuchs 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 10 additional commits since the last revision:
> 
>  - More review comments
>  - Taking into account review feedback
>  - Merge branch 'master' into url-iae-8294948
>  - Merge branch 'master' into url-iae-8294948
>  - Minor wording updates - unmmapable single quote character
>  - Minor wording updates
>  - Update Copyright Years
>  - Adding missing @throws NPE
>  - 8294948
>  - 8294948

src/java.base/share/classes/java/net/URL.java line 580:

> 578:      * @implSpec Parsing the URL involves calling the {@link
> 579:      * URLStreamHandler#parseURL(URL, String, int, int) parseURL} method on the
> 580:      * selected handler.

What you would think about making this more direct, e.g. "This constructor invokes the selected stream handler's parseURL method to parse the URL."

src/java.base/share/classes/java/net/URL.java line 590:

> 588:      *               underlying stream handler's {@linkplain
> 589:      *               URLStreamHandler#parseURL parseURL method} throws
> 590:      *               {@code IllegalArgumentException}

This looks okay but it might be simpler to drop "In particular" and just say "or the stream handler's parseURL throws ...".

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

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