8241995: Clarify InetSocketAddress::toString specification

[Michael McMahon]

On 03/04/2020 21:39, mark sheppard wrote:
> 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.
>
As above but,


"rather than parsing the toString string representation"


maybe instead


"rather than parsing the String returned from toString"


My 2c

Michael


> 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/20200414/dd662c46/attachment.htm>