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

[Aleksei Efimov]

On Sun, 17 Sep 2023 13:38:08 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.lang.String)

Thanks for all the comments/feedback/suggestions provided. They highlight the fact that this change requires additional work in the following areas:
- Improving new methods Javadoc to mention all supported IP address literal forms.
- Having Inet4Addres.ofLiteral responsible for parsing IPv4-mapped IPv6 addresses looks strange. That will require method signature changes, but will keep javadoc and API less confusing.

In comming days I will work on fixing the above issues first. The methods name can be discussed after that.

The next iteration contains the following changes:

- Improvements to Javadoc of the new methods. That includes the addition of all supported IP address literal forms.
- `Inet4Addres.ofLiteral` is no longer capable of parsing IPv4-mapped IPv6 address literals - it can be done with `Inet6Address.ofLiteral` instead.
- Added missing `null` checks for literal parameters.
- Added new test scenarios.

To restart the conversation around the method name, I've prepared the following table with a list of method names discussed during the previous review iteration:

| Name | Usage Example | Notes |
|-------|--------------|-------|
| `ofLiteral` | `InetAddress.ofLiteral` | Current version. Cleary conveys it takes only an IP literal. Matches its implementation. Good for IDE autocompletion. |
| `parse` | `InetAddress.parse` | The fact that only IP address literals are taken as a parameter is obscured a bit. But still suggests that the InetAddress instance is constructed by parsing some text. Good for IDE.|
| `parseLiteral` | `InetAddress.parseLiteral` | Method name changed to hint that an IP address literal is taken as a parameter. Good for IDE. Matches its implementation.|
| `getByAddress` | `InetAddress.getByAddress` | Overrides existing method in InetAddress, but adds new method to Inet4Address and Inet6Address. Introduces new meaning of `address` term - IP address literal string. In existing API the `address` means a raw byte array.|

My preference is to proceed with one of the following two:
`ofLiteral` or `parseLiteral`.

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

PR Comment: https://git.openjdk.org/jdk/pull/15775#issuecomment-1725438962
PR Comment: https://git.openjdk.org/jdk/pull/15775#issuecomment-1732371463
PR Comment: https://git.openjdk.org/jdk/pull/15775#issuecomment-1747264766