suggest improvement for java doc for getting address of local host

[David Holmes]

On 5/08/2022 8:24 am, mark.yagnatinsky at barclays.com wrote:
> I suspect that this is the wrong list; please redirect me if so.

Redirected to net-dev

Cheers,
David

> The docs for this method:
> 
> https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/net/InetAddress.html#getLocalHost() 
> <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 
> <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 
> <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 
> <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 
> <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 
> <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 
> <https://www.cib.barclays/disclosures/personal-information-use.html>.
> __________________________________________________________________________________
>