8241995: Clarify InetSocketAddress::toString specification

[Julia Boes]

Hi Jaikiran,

I just created a PR, taking into consideration your suggestion:

https://github.com/openjdk/jdk/pull/2357
https://mail.openjdk.java.net/pipermail/net-dev/2021-February/015298.html

Regards,
Julia

From: net-dev <net-dev-retn at openjdk.java.net> on behalf of Jaikiran Pai <jai.forums2013 at gmail.com>
Date: Tuesday, 2 February 2021 at 15:06
To: Chris Hegarty <chris.hegarty at oracle.com>, OpenJDK Network Dev list <net-dev at openjdk.java.net>
Subject: Re: 8241995: Clarify InetSocketAddress::toString specification
Hello Chris,

I missed this thread previously. This suggested change to the javadoc
looks good to me and the example now makes it clear on what to expect.

As for the last paragraph of the javadoc, I'm just adding to the
suggestions already made by others in this thread. Perhaps the following
text would be OK?:

"The string returned from this method should not be relied upon to
obtain the hostname or address of this InetSocketAddress instance.
Instead the {@link #getHostString()} should be used."

Given that the getHostString() method's javadoc already has the following:

"Returns the hostname, or the String form of the address if it doesn't
have a hostname (it was created using a literal)."

I think it's not necessary to repeat that part here.

-Jaikiran


On 03/04/20 10:56 pm, Chris Hegarty wrote:
> 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/20210202/608e234a/attachment-0001.htm>