On Fri, 13 Oct 2023 01:26:26 GMT, Aleksei Efimov <[email protected]> wrote:

>> ### Summary 
>> 
>> The changes in this PR add new API to `java.net.InetAddress`, 
>> `java.net.Inet4Address`, and
>>  `java.net.Inet6Address` classes to parse IP address literals:
>>  ```
>> method public static java.net.InetAddress 
>> java.net.InetAddress.ofLiteral(java.lang.String)
>> method public static java.net.Inet4Address 
>> java.net.Inet4Address.ofLiteral(java.lang.String)
>> method public static java.net.InetAddress 
>> java.net.Inet6Address.ofLiteral(java.lang.String)
>> ``` 
>> 
>> ### How new methods differ from existing ones
>> 
>> These methods differ from `InetAddress.getByName` and 
>> `InetAddress.getAllByName` in the following ways:
>> 1. If a string supplied is not an address literal it is not forwarded to the 
>> system-wide resolver, but IllegalArgumentException is thrown instead. The 
>> system-wide resolver is never called from these new methods.
>> 2. No reverse lookup is performed to resolve a hostname for the supplied 
>> address literal - the `InetAddress[46 ]` instances returned by the new 
>> `ofLiteral` API has no hostname set.
>> 3. Each `ofLiteral` static method returns addresses of its class only. It 
>> gives the ability to check if an IP address literal is of a specific address 
>> type. 
>> 
>> ### The list of noteworthy changes
>> - `IPv4-mapped IPv6 address` and `IPv4-compatible IPv6 addresses` require 
>> some special handling in the new API to implement all supported IP address 
>> types.  
>> - All address literal parsing code has been moved from 
>> `InetAddress.getAllByName` to address type-specific 
>> `Inet4Address.parseAddressString` and `Inet6Address.parseAddressString` 
>> methods.
>> - The text with scoped IPv6 addresses architecture draft IETF file has been 
>> replaced from `[draft-ietf-ipngwg-scoping-arch-04.txt]` to reference `RFC 
>> 4007: IPv6 Scoped Address Architecture`. The "RFC 4007" has been also added 
>> as `@ spec` into Inet6Address class-level Javadoc.
>> 
>> ### Testing 
>> 
>> `jdk-tier1`, `jdk-tier2`, and `jdk-tier3` test sets show no failure with the 
>> changes.
>> 
>> `java/net` JCK tests are failing with new methods added failure (CSR is 
>> planned for this change):
>> 
>> Added Methods
>> -------------
>> 
>> java.net.Inet4Address:                  method public static 
>> java.net.Inet4Address java.net.Inet4Address.ofLiteral(java.lang.String)
>> java.net.Inet6Address:                  method public static 
>> java.net.InetAddress java.net.Inet6Address.ofLiteral(java.lang.String)
>> java.net.InetAddress:                   method public static 
>> java.net.InetAddress java.net.InetAddress.ofLiteral(java.lan...
>
> Aleksei Efimov has updated the pull request incrementally with three 
> additional commits since the last revision:
> 
>  - test update: run IPv6-scoped address with wrong scope-id test case only 
> with at least 2 NI
>  - Moving snippets to class-level docs per Michael suggestion, associated doc 
> changes
>  - Daniel suggestions

Sorry for the back and forth suggestions - I hadn't noticed that "ambiguous" 
was already introduced earlier in the method description. I'd suggest the 
following refactoring to make it easier to read.

src/java.base/share/classes/java/net/Inet4Address.java line 189:

> 187:      * and {@code throwIAE} is {@code true}, an {@code 
> IllegalArgumentException} is thrown.
> 188:      * If string contains an {@linkplain 
> IPAddressUtil#validateNumericFormatV4(String, boolean)
> 189:      * ambiguous literal} - {@code IllegalArgumentException} is thrown 
> irrelevant to

Suggestion:

     * Otherwise, if it can be considered as {@linkplain 
IPAddressUtil#validateNumericFormatV4(String, boolean)
     * an ambiguous literal} - {@code IllegalArgumentException} is thrown 
irrelevant to

src/java.base/share/classes/java/net/Inet4Address.java line 190:

> 188:      * If string contains an {@linkplain 
> IPAddressUtil#validateNumericFormatV4(String, boolean)
> 189:      * ambiguous literal} - {@code IllegalArgumentException} is thrown 
> irrelevant to
> 190:      * {@code throwIAE} value.

Suggestion:

     * {@code throwIAE} value.
     *
     * @apiNote
     * The given {@code addressLiteral} string is considered ambiguous if it 
cannot be parsed as
     *  a valid IPv4 address literal using decimal notation, but could be
     * interpreted as an IPv4 address in some other representation (octal, 
hexadecimal, or mixed).

src/java.base/share/classes/java/net/Inet4Address.java line 202:

> 200:      * {@code throwIAE} if the given {@code addressLiteral} string is 
> ambiguous, that is,
> 201:      * it cannot be parsed as a valid IPv4 address literal using decimal 
> notation but could be
> 202:      * interpreted as an IPv4 address in some other representation 
> (octal, hexadecimal, or mixed).

Suggestion:

     * @throws IllegalArgumentException if the given {@code addressLiteral} 
string
     * cannot be parsed as an IPv4 address literal and {@code throwIAE} is 
{@code true},
     * or if it is considered ambiguous, regardless of the value of the value of
     * {@code throwIAE}.

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

PR Review: https://git.openjdk.org/jdk/pull/15775#pullrequestreview-1676057283
PR Review Comment: https://git.openjdk.org/jdk/pull/15775#discussion_r1358006767
PR Review Comment: https://git.openjdk.org/jdk/pull/15775#discussion_r1357992180
PR Review Comment: https://git.openjdk.org/jdk/pull/15775#discussion_r1357995298

Reply via email to