RFR: 8272215: Add InetAddress methods for parsing IP address literals

[Aleksei Efimov]

On Fri, 13 Oct 2023 09:08:33 GMT, Daniel Fuchs <dfuchs at openjdk.org> 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...
>
> 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).

Thanks for the suggestions Daniel. They look reasonable to me, and improve the readability. Taken them aboard in 4bd63f29386a515d63879412f80d958046e6c8c2.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/15775#discussion_r1358126045