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

[Alan Bateman]

On Tue, 11 Oct 2022 14:17:31 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 seven additional commits since the last revision:
> 
>  - 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 181:

> 179:  * called during URL construction and it throws {@code IllegalArgumentException}.
> 180:  * However, which checks are performed is implementation dependent, and
> 181:  * callers should not rely on such checks for full URL validation.

I think the API note  will need a few adjustments. 

The first sentence uses the word "additionally" but the text prior to that isn't about throwing exceptions. I think what you mean is in addition to the reasons specified by the URL constructors, in which case this makes it normative. Maybe you could lend on the text "parsed URL fails to comply ..." or if that is too complicated then just drop this part of the API note.

A second sentence uses "In particular when ..." but I don't think URL specifies that it calls the parseURL method. If the URL constructors did specify this when you could reference it here. If you map to document the mapping of ISE to MalformedURLException then I think the URL constructors will need to document that they delegate to parseURL and throw MalformedURLException if the parsing fails with IAE.

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

> 364:      *                  is a negative number other than -1, or if the
> 365:      *                  underlying stream handler implementation rejects,
> 366:      *                  or is known to reject, the {@code URL}

and "underlying stream handling implementation rejects" would fit with the constructor specifying that it calls the stream handler's parseURL method.

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

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