On Sun, 16 Oct 2022 07:31:03 GMT, Alan Bateman <[email protected]> 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
