RFR: 8272215: Add InetAddress methods for parsing IP address literals [v2]

[Jaikiran Pai]

On Sat, 23 Sep 2023 17:28:55 GMT, Aleksei Efimov <aefimov 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...
>
> Aleksei Efimov has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - updates for Inet6Address.ofLiteral return type, javadoc and the regression test
>  - add null checks and NPE to methods javadoc

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

> 179:     /**
> 180:      * Parses string with an IPv4 address literal.
> 181:      * If string doesn't contain a valid literal - null is returned.

This sentence is a bit confusing, given the implementation details of this method. I think `null` is only returned if `throwIAE` is false?

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

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