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

[Daniel Fuchs]

On Sun, 16 Oct 2022 07:31:03 GMT, Alan Bateman <alanb at openjdk.org> wrote:

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

Thanks @AlanBateman - I have updated the API note, added an `@implSpec` in two of the constructors to spell out that they are calling the stream handler's parseURL method (the first one says it's equivalent to the second one so I don't think `@implSpec` is needed there), and improved the `@throws MalformedURLException` with more details.
Does the new text match your expectations?

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

Done

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

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