RFR: 8244202: Implementation of JEP 418: Internet-Address Resolution SPI [v3]

[Mark Sheppard]

On Sun, 17 Oct 2021 16:33:57 GMT, Aleksei Efimov <aefimov at openjdk.org> wrote:

> > What’s in a name? I find the method names of the InetAddressResolver interface a bit ambiguous. Typically in this DNS problem space one speaks of lookup to resolve a hostname to its associated addresses and reverse lookup to resolve an IP address to a hostname (or names) associated with it.
> 
> I'm not sure that I see an ambiguity here: Interface has two methods, both are for lookup operations. That is why `lookup` word is used in both names. Then we put a description of a returned result after operation name: `Addresses` and `HostName` are the results. In cases when we want to highlight a parameter type in a method name we can use ‘by’/‘with’ prepositions: for instance, `InetAddress.getByName` `InetAddress.getByAddress` `ScheduledExecutorService.scheduleWithFixedDelay`.
> 
> We can try and apply this approach to the description of DNS operations above:
> 
> > lookup to resolve a hostname to its associated addresses
> 
> operation: `lookup` result: `addresses` -> methodName: `lookupAddresses`
> 
> > reverse lookup to resolve an IP address to a hostname
> 
> operation: `lookup` (we've dropped reverse word here) result: `hostname` -> methodName: `lookupHostName`

Yes, ambiguity wasn’t quite the word I was looking for. Maybe contradictory or oxymoron might do !!
Let me try and clarify the rational behind the suggestion.

To re-iterate, the parlance of the DNS domain in context of address resolution is lookup for hostname to IP address resolution and reverse lookup for address to hostname mapping. For me, the natural verb to method translation is lookup and **reverseLookup OR resolveHostname and resolveAddress. The latter names are pretty definitive and unambiguous. It clear and obvious without the need to pursue the full signature of the method, what the semantics of the methods should be.

At the java InetAddress API level there is getByName(String host) and getByAddress(byte[] addr).
At the native OS level there is gethostbyname, gethostbyaddr and the evolved api getnameinfo and getaddrinfo.

getByName requires a hostname lookup and getByAdress requires (eventually - I know the docs says there’s no reverse lookup) an address reverse lookup. Thus, a logical mapping is getByName —> lookupHostname, and getByAddr —> lookupAddress, but the opposite will occur getByName --> lookupAddresses and getByAddress --> lookupHostname.  Therfore  I proffer maps neatly to rename methods to resolveHostname and resolveAddress such that the mapping are getByName --> resolveHostname and getByAddress --> resolveAddress.

I will concede that it can be reasonable argued that the native library functions getnameinfo and getaddrinfo may better abstract to lookupHostname and lookupAddresses respectively. But, I have always found these two library calls a bit contorted and the legacy gethostbyname and gethostbyaddress were more logical.

In you proposition above:

> operation: `lookup` result: `addresses` -> methodName: `lookupAddresses`

> operation: `lookup` (we've dropped reverse word here) result: `hostname` -> methodName: `lookupHostName`

You are generating the name from the result of the action. I’m arguing that it should be based on the operation on the subject i.e. the parameter being passed.
If this was hashmap lookup, then it is an operation of mapping hostname to addresses mapHostnameToAddresses, i.e. looking up a hostname, and mapping an address to a hostname mapAddressToHostname i.e. looking up an address.

Of course, it is possible to just **overload**  a lookup method, one taking Sting and t’other taking byte adder in the method’s parameters, respectively. Then, you don’t have to concede too much in this argument.
But, for me as an ordinary developer, resolveAddress and resolveHostname are crystal clear and unambiguous.

-------------

PR: https://git.openjdk.java.net/jdk/pull/5822