docs: public static String tryResolveHostName(final String nameToResolve, final boolean preferIPv6) {
  
          if (TraceComponent.isAnyTracingEnabled() && tc.isDebugEnabled()) {
              Tr.debug(tc, "Trying to resolve hostname : " + nameToResolve + ", prefer IPv6 : " + preferIPv6);
          }
  
          return AccessController.doPrivileged(new PrivilegedAction<String>() {
              @Override
              @FFDCIgnore({ SocketException.class, UnknownHostException.class })
              public String run() {
                  InetAddress resultAddr = null;
  
                  if (LOCALHOST.equalsIgnoreCase(nameToResolve)) {
                      return LOCALHOST;
                  } else if (WILDCARD.equals(nameToResolve) || nameToResolve == null || nameToResolve.isEmpty()) {
                      InetAddressResult result = new InetAddressResult(preferIPv6); // preferred and fallback
  
                      if (TraceComponent.isAnyTracingEnabled() && tc.isDebugEnabled()) {
                          Tr.debug(tc, "Result : " + result);
                          if (result != null) {
                              Tr.debug(tc, "Address : " + result.getAddress() + ", needs preferred address : " + result.needsPreferredAddr());
                          }
                      }
  
                      List<NetworkInterface> p2p = new ArrayList<NetworkInterface>();
  
                      try {
                          // '*', so let's pick the first interface that is not
                          // a loopback, or virtual interface, and use that if we can.
                          // NOTE: findPreferredAddress excludes link local addresses
                          Enumeration<NetworkInterface> nicEnum = NetworkInterface.getNetworkInterfaces();
                          for (NetworkInterface nic : Collections.list(nicEnum)) {
  
                              if (TraceComponent.isAnyTracingEnabled() && tc.isDebugEnabled()) {
                                  Tr.debug(tc, "NIC : " + nic);
                                  Tr.debug(tc, "isUp : " + nic.isUp());
                                  Tr.debug(tc, "isVirtual : " + nic.isVirtual());
                                  Tr.debug(tc, "isLoopback : " + nic.isLoopback());
                                  Tr.debug(tc, "isPointToPoint : " + nic.isPointToPoint());
                              }
  
                              Enumeration<InetAddress> addrs = nic.getInetAddresses();
  
                              if (TraceComponent.isAnyTracingEnabled() && tc.isDebugEnabled()) {
                                  for (InetAddress addr : Collections.list(addrs)) {
                                      Tr.debug(tc, "Address : " + addr + ", isLinkLocal : " + addr.isLinkLocalAddress());
                                  }
                              }
  
                              if (nic.isUp() && !nic.isVirtual() && !nic.isLoopback()) {
                                  if (nic.isPointToPoint()) {
                                      // remember p2p to try later.
                                      p2p.add(nic);
                                  } else if (findPreferredAddress(nic, result, preferIPv6)) {
                                      if (TraceComponent.isAnyTracingEnabled() && tc.isDebugEnabled()) {
                                          Tr.debug(tc, "Found preferred address");
                                      }
                                      break;
                                  }
                              }
                          }
  
                          // If we haven't found our preferred protocol yet, try any p2p interfaces.
                          // This is required on z/OS (RTC Java Defect 125337), which for some reason has 
                          // many of it's network interfaces configured as point-to-point.
                          // NOTE: findPreferredAddress excludes link local addresses
                          if (result.needsPreferredAddr() && !p2p.isEmpty()) {
                              for (NetworkInterface nic : p2p) {
                                  if (findPreferredAddress(nic, result, preferIPv6)) {
                                      if (TraceComponent.isAnyTracingEnabled() && tc.isDebugEnabled()) {
                                          Tr.debug(tc, "Found preferred address in point to point list");
                                      }
                                      break;
                                  }
                              }
                          }
                      } catch (SocketException e) {
                          if (TraceComponent.isAnyTracingEnabled() && tc.isDebugEnabled()) {
                              Tr.debug(tc, "Exception while finding preferred address : " + e);
                          }
                      }
  
                      // get the address we found (if there is one). The result class
                      // manages preferred vs. fallback protocol version
                      resultAddr = result.getAddress();
                  } else {
                      // We were given a specific host name or IP address to verify.
                      resultAddr = findLocalHostAddress(nameToResolve, preferIPv6);
                  }
  
                  // Woo-hoo we found an address to use.
                  if (resultAddr != null) {
                      String hostAddr = resultAddr.getHostAddress();
                      // preserve lower case: required for matching all kinds of things later.. 
                      String hostName = resultAddr.getCanonicalHostName().toLowerCase();
  
                      // If this is an IPv6 address, we need extra text to make it usable in messages
                      // IPv6 addresses can be compressed: ::1 vs. 0:0:0:0:0:0:0:1, some OS will use the long
                      // form as the canonicalized result when the short form was provided.
                      if (resultAddr instanceof Inet6Address && hostName.contains(":") && !hostName.startsWith("[")) {
                          hostName = "[" + hostAddr + "]";
                      }
  
                      if (TraceComponent.isAnyTracingEnabled() && tc.isDebugEnabled()) {
                          Tr.debug(tc, "tryResolveHostName returning : " + hostName);
                      }
                      return hostName;
                  }
  
                  if (TraceComponent.isAnyTracingEnabled() && tc.isDebugEnabled()) {
                      Tr.debug(tc, "tryResolveHostName returning null");
                  }
  
                  // Bummer. return null to disambiguate resolved localhost from unresolvable address.
                  // The caller may fallback to localhost in this case.
                  return null;
              }
  
              /**
               * Look at the InetAddresses associated with a NetworkInterface. Ignoring LinkLocal addresses,
               * return at the first instance of an InetAddress of the preferred protocol, and
               * remember the first address found for the fallback protocol (if we get there).
               * 
               * @param nic NetworkInterface to inspect
               * @param result small inner class that stores results (most importantly the fallback address)
               * @param preferIPv6 if true, prefer IPv6 InetAddresses
               * @return true if we found an InetAddress for the preferred protocol, otherwise return false so we keep looking
               */
              private boolean findPreferredAddress(NetworkInterface nic, InetAddressResult result, boolean preferIPv6) {
                  Enumeration<InetAddress> addrs = nic.getInetAddresses();
                  for (InetAddress addr : Collections.list(addrs)) {
                      // skip linklocal addrs -- remember this is called when we're trying to 
                      // generate an address to use in URLs when listening on all interfaces.
                      // Link local is not always usable, so we'll avoid it, and allow the caller
                      // to fallback to localhost, which is more likely to work.
                      if (!addr.isLinkLocalAddress() && result.setAddressIsPreferred(addr))
                          return true;
                  }
                  return false;
              }
          });
      }