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

[Aleksei Efimov]

On Sun, 17 Sep 2023 15:30:12 GMT, Alan Bateman <alanb at openjdk.org> wrote:

> At a high-level, introducing static methods named "ofLiteral" or "parse" to parse a string as an IPv4 or IPv6 literal address is good. I think the methods will require work on the class descriptions, speak about parsing the input string, and only mention "blocking" in the context of specifying that they don't attempt reverse name resolution.

Thanks Alan. Based on the intial feedback it is clear that these new methods require more work on documentation. 

> On Inet4Address.ofLiteral, I can't tell from the method description if it supports all 4 forms that are listed in the class description. It may be a surprise that this method parses IPv4-mapped IPv6 addresses. So I think my main comment here is that the method description will need to more completely specify the forms that the input string may take.

I agree that seeing `Inet4Address.ofLiteral` capable of parsing IPv4-mapped IPv6 addresses can look strange here. On contrary, there should be no surprise for `Inet6Address.ofLiteral` to parse such addresses. I will pursue updating its signature to return `InetAddress` and document it as one of the supported forms.

> Similar comment on Inet6Address.ofLiteral. I can't tell from the API docs if the input needs enclosing square brackets, I can't tell if it supports shortened forms, I can't tell if it's legal or not to include a scope ID. 

`Inet6Address.ofLiteral` supports literal enclosed with/without square brackets, supports scope ID, shorten-format. But it is not mentioned in Javadoc. I will work on updating Javadoc to list all these aspects.

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

PR Comment: https://git.openjdk.org/jdk/pull/15775#issuecomment-1725373552