suggest improvement for java doc for getting address of local host

Fri Aug 5 15:51:31 UTC 2022

Thanks for the re-direct.  Following up on what Alan Bateman said, it seems that Java prefers to return an IPv4 address if it can.
However, if there are multiple IPv4 addresses, then there are no guarantees about which one is returned, either in theory or in practice, right?
Java is at the whims of whatever order the OS returned things in, which could change essentially at random, correct?  Or not quite?

-----Original Message-----
From: David Holmes <david.holmes at oracle.com> 
Sent: Friday, August 5, 2022 12:20 AM
To: Yagnatinsky, Mark : Markets Pre Trade <mark.yagnatinsky at barclays.com>; net-dev at openjdk.org
Subject: Re: suggest improvement for java doc for getting address of local host

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://clicktime.symantec.com/15siKxwAAWWL3eZqGu9Fo?h=L5Cz6B7AzyisGrH
> 4l0L4X529kjHrv3YxbQf5lwngdkA=&u=https://docs.oracle.com/en/java/javase
> /18/docs/api/java.base/java/net/InetAddress.html%23getLocalHost%28%29
> <https://clicktime.symantec.com/15siKxwAAWWL3eZqGu9Fo?h=L5Cz6B7AzyisGr
> H4l0L4X529kjHrv3YxbQf5lwngdkA=&u=https://docs.oracle.com/en/java/javas
> e/18/docs/api/java.base/java/net/InetAddress.html%23getLocalHost%28%29
> >
> 
> 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://clicktime.symantec.com/15sik7uaTavJ7NhSzh8zu?h=UFavxUN5tRXok_m
> DIiHpRn1sKq3VCMvcydEs2vqbobo=&u=https://www.cib.barclays/disclosures/w
> eb-and-email-disclaimer.html 
> <https://clicktime.symantec.com/15sik7uaTavJ7NhSzh8zu?h=UFavxUN5tRXok_mDIiHpRn1sKq3VCMvcydEs2vqbobo=&u=https://www.cib.barclays/disclosures/web-and-email-disclaimer.html>.
> 
> For important disclosures, please see: 
> https://clicktime.symantec.com/15sifHiHzyEhhRsXT8jrH?h=PMnjVEVgXtFVmub
> VHUM1o5rz9HttKMX21Vj--npgdy8=&u=https://www.cib.barclays/disclosures/s
> ales-and-trading-disclaimer.html 
> <https://clicktime.symantec.com/15sifHiHzyEhhRsXT8jrH?h=PMnjVEVgXtFVmu
> bVHUM1o5rz9HttKMX21Vj--npgdy8=&u=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://clicktime.symantec.com/15siQo8Sd8BvTbPkpTYQR?h=dTU42MaVNvEtaL2
> Zps0lVBQhdL0MI1vM6M424uokAn8=&u=https://www.cib.barclays/disclosures/b
> arclays-global-markets-disclosures.html
> <https://clicktime.symantec.com/15siQo8Sd8BvTbPkpTYQR?h=dTU42MaVNvEtaL
> 2Zps0lVBQhdL0MI1vM6M424uokAn8=&u=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: 
> https://clicktime.symantec.com/15siF8jshtpjdhjujLk7B?h=Vye4w2dUPWGVTc4
> IewZFvicgToVcwQkkW7f_FGsXy0I=&u=http://publicresearch.barclays.com
> <https://clicktime.symantec.com/15siF8jshtpjdhjujLk7B?h=Vye4w2dUPWGVTc4IewZFvicgToVcwQkkW7f_FGsXy0I=&u=http://publicresearch.barclays.com>.
> ______________________________________________________________________
> ____________
> 
> If you are incorporated or operating in Australia, read these 
> important
> disclosures: 
> https://clicktime.symantec.com/15siVdKj5jsWsYDgN1wZ3?h=DzbCBWu_nsLuzLp
> PP-9b-JAqm7eBanb1titrjDf8FVo=&u=https://www.cib.barclays/disclosures/i
> mportant-disclosures-asia-pacific.html
> <https://clicktime.symantec.com/15siVdKj5jsWsYDgN1wZ3?h=DzbCBWu_nsLuzLpPP-9b-JAqm7eBanb1titrjDf8FVo=&u=https://www.cib.barclays/disclosures/important-disclosures-asia-pacific.html>.
> ______________________________________________________________________
> ____________ For more details about how we use personal information, 
> see our privacy
> notice: 
> https://clicktime.symantec.com/15siaTX1YMZ7HV3buaLhf?h=sN0ZV8UZPICPbPw
> rFJrH-fcw1UO7qb7GwyHX4WRTmOU=&u=https://www.cib.barclays/disclosures/p
> ersonal-information-use.html 
> <https://clicktime.symantec.com/15siaTX1YMZ7HV3buaLhf?h=sN0ZV8UZPICPbPwrFJrH-fcw1UO7qb7GwyHX4WRTmOU=&u=https://www.cib.barclays/disclosures/personal-information-use.html>.
> ______________________________________________________________________
> ____________
> 

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. 
__________________________________________________________________________________