8241995: Clarify InetSocketAddress::toString specification

[mark sheppard]

Hi Chris,
    possible wording for your last paragraph:

To retrieve a string representation of the hostname, or in the
absence of a hostname, the string form of the address, use {@link
#getHostString()}, rather than parsing the toString string representation.

or

It is advised to use {@link#getHostString()} to obtain a hostname string, or
in the absence of a hostname, a string form of the address. Do not rely on
parsing the toString() return value to obtain a hostname string.

regards
Mark




________________________________
From: net-dev <net-dev-bounces at openjdk.java.net> on behalf of Chris Hegarty <chris.hegarty at oracle.com>
Sent: Friday 3 April 2020 17:26
To: OpenJDK Network Dev list <net-dev at openjdk.java.net>
Subject: 8241995: Clarify InetSocketAddress::toString specification

As noted in a recent thread [1], the wording of InetSocketAddress::toString
could be improved a little, to avoid any potential confusion about how
and when "<unresolved>" is displayed. It was also suggested that a link
to getHostString could be added.

Below is an initial suggestion. It does not change the spec, just adds
some examples and guidance. I'm relatively happy with the examples, but
less so with the final advise paragraph. Suggestions welcome.


-  /**
-   * Constructs a string representation of this InetSocketAddress.
-   * This String is constructed by calling toString() on the InetAddress
-   * and concatenating the port number (with a colon). If the address
-   * is an IPv6 address, the IPv6 literal is enclosed in square brackets.
-   * If the address is {@linkplain #isUnresolved() unresolved},
-   * {@code <unresolved>} is displayed in place of the address literal.
-   *
-   * @return  a string representation of this object.
-   */
-  public String toString() { ... }
---
+  /**
+   * Constructs a string representation of this InetSocketAddress.
+   * This String is constructed by calling {@link InetAddress#toString()}
+   * on the InetAddress and concatenating the port number (with a colon).
+   *
+   * <p> If the address is an IPv6 address, the IPv6 literal is enclosed in
+   * square brackets, for example: {@code "localhost/[0:0:0:0:0:0:0:1]:80"}.
+   * If the address is {@linkplain #isUnresolved() unresolved},
+   * {@code <unresolved>} is displayed in place of the address literal, for
+   * example {@code "foo/<unresolved>:80"}.
+   *
+   * <p> To retrieve a string representation of the hostname, or the string
+   * form of the address if it doesn't have a hostname, use {@link
+   * #getHostString()}, rather than parsing the string representation.
+   *
+   * @return  a string representation of this object.
+   */
+  public String toString() { ... }

-Chris

[1]  https://mail.openjdk.java.net/pipermail/net-dev/2020-April/013747.html

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/net-dev/attachments/20200403/dcd86fdc/attachment-0001.htm>