suggest improvement for java doc for getting address of local host
mark.yagnatinsky at barclays.com
mark.yagnatinsky at barclays.com
Thu Aug 4 22:24:55 UTC 2022
I suspect that this is the wrong list; please redirect me if so.
The docs for this method:
https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/net/InetAddress.html#getLocalHost()
say that it "Returns the address of the local host. This is achieved by retrieving the name of the host from the system, then resolving that name into an InetAddress."
This is true enough in simple cases, but horribly misleading in non-trivial cases.
As far as I can tell it can't return "the address" because the local host may have multiple addresses.
Instead it returns "an address" of the local host. My laptop right now has 3 addresses: IPv6 loopback, IPv4 from home WiFi, and IPv4 from company network via VPN.
As far as I can tell (please correct me if I'm wrong!!) if there are multiple addresses, the current implementation makes no effort to pick a more "useful" one.
Instead, it takes whatever addresses it gets from the OS and returns the first one.
Thus, in theory, and even in practice, it's perfectly possible to get into a situation where all of the following hold:
"It worked fine yesterday!"
"I didn't change anything, honest!"
And yet, "nothing works today" (because, unbeknownst to mere mortals like me, the OS happened to return things in a different order today.)
Again, please correct me if I'm wrong and there actually are some guarantees, either by virtue of the spec, or by virtue of "it just so happens that in practice you will tend to get XYZ".
But if I'm right, then I suggest the following tweak to the documentation:
Returns the address of the local host. If the local host has multiple addresses, an arbitrary one will be chosen and returned.
This is achieved by retrieving the name of the host from the system, then resolving that name into a list of one or more `InetAddress`es and then choosing an arbitrary address from that list.
(irrelevant but: really wish Javadoc had a lightweight notation for code like markdown's `code(blocks)`)
Just my two cents. Again, please redirect me if this is the wrong list, and correct me if I'm wrong re: no guarantees about which address is returned.
This message is for information purposes only. It is not a recommendation, advice, offer or solicitation to buy or sell a product or service, nor an official confirmation of any transaction. It is directed at persons who are professionals and is intended for the recipient(s) only. It is not directed at retail customers. This message is subject to the terms at: https://www.cib.barclays/disclosures/web-and-email-disclaimer.html.
For important disclosures, please see: https://www.cib.barclays/disclosures/sales-and-trading-disclaimer.html regarding marketing commentary from Barclays Sales and/or Trading desks, who are active market participants; https://www.cib.barclays/disclosures/barclays-global-markets-disclosures.html regarding our standard terms for Barclays Corporate and Investment Bank where we trade with you in principal-to-principal wholesale markets transactions; and in respect to Barclays Research, including disclosures relating to specific issuers, see: http://publicresearch.barclays.com.
__________________________________________________________________________________
If you are incorporated or operating in Australia, read these important disclosures: https://www.cib.barclays/disclosures/important-disclosures-asia-pacific.html.
__________________________________________________________________________________
For more details about how we use personal information, see our privacy notice: https://www.cib.barclays/disclosures/personal-information-use.html.
__________________________________________________________________________________
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jdk-dev/attachments/20220804/6d728fbb/attachment-0001.htm>
More information about the jdk-dev
mailing list