org.netbeans.core.network.utils

Class LocalAddressUtils

java.lang.Object

org.netbeans.core.network.utils.LocalAddressUtils

public class LocalAddressUtils
extends Object

Methods for determining the local host's own address. The methods provide two benefits over the core JDK classes.:

• Caching. Results from the methods are cached and can therefore be returned without blocking. An application should call LocalAddressUtils.warmUp() during the application's startup phase so that results are readily available when needed.
• IP protocol preference. All methods allow to state an explicit preference for IPv4 vs IPv6. (without relation to the JVM's overall protocol preference settings).

The main method is getMostLikelyLocalInetAddress(). The other methods essentially exist to provide input to this method but are exposed nevertheless if anyone wants them.

These utility methods are in particular relevant in relation to the PAC helper method myIpAddress(). However, the class may indeed be used for any use case.

Note, that there is no single correct answer to the question about determining the local host's IP address in an environment with multiple network interfaces or multiple addresses on each network interface.

Method Summary

Modifier and Type	Method and Description
static List<InetAddress>	getDatagramLocalInetAddress(IpAddressUtils.IpTypePreference ipTypePref) Returns the address of the local host, found by using UDP method.
static InetAddress	getLocalHost() Returns the address of the local host.
static InetAddress[]	getLocalHostAddresses(IpAddressUtils.IpTypePreference ipTypePref) Returns the addresses of the local host.
static InetAddress	getLoopbackAddress(IpAddressUtils.IpTypePreference ipTypePref) Returns the loopback address.
static InetAddress	getMostLikelyLocalInetAddress(IpAddressUtils.IpTypePreference ipTypePref) Returns the host's IP address.
static InetAddress[]	getMostLikelyLocalInetAddresses(IpAddressUtils.IpTypePreference ipTypePref) Returns the host's IP addresses.
static List<InetAddress>	getPrioritizedLocalHostAddresses(IpAddressUtils.IpTypePreference ipTypePref) Returns a prioritized list of local host addresses.
static boolean	isSoftwareVirtualAdapter(NetworkInterface nif) Tries to guess if the network interface is a virtual adapter by one of the makers of virtualization solutions (e.g.
static void	refreshNetworkInfo(boolean await) Refreshes the cached network information.
static void	warmUp() Starts collecting network information in a background task.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

warmUp

public static void warmUp()

Starts collecting network information in a background task. This method is ideal for calling once during application startup phase. Calling this method during startup means that later calls to methods in this class will perform very fast, because they will then return a cached result and thus will never block.

refreshNetworkInfo

public static void refreshNetworkInfo(boolean await)

Refreshes the cached network information. Normally there is no reason to call this method as a computer's network information is unlikely to change during the lifetime of the application, unless the computer connects to a different network than was the case when the information was first cached.

Parameters:

await - if true, waits for the refresh to complete

getLocalHost

@NonNull
public static InetAddress getLocalHost()
                                         throws UnknownHostException

Returns the address of the local host.

This method returns a cached result of calling InetAddress.getLocalHost() and is therefore likely not to block (unlike the underlying method) unless this is the first time this class is being referenced.

Note that InetAddress#getLocalHost() is known to return unpredictable results for hosts with multiple network adapters. The getMostLikelyLocalInetAddresses() method is much more likely to return an acceptable result.

Returns:

Throws:

UnknownHostException

See Also:

LocalAddressUtils.getMostLikelyLocalInetAddresses(IpAddressUtils.IpTypePreference)

getLocalHostAddresses

@NonNull
public static InetAddress[] getLocalHostAddresses(IpAddressUtils.IpTypePreference ipTypePref)
                                                    throws UnknownHostException

Returns the addresses of the local host.

This is achieved by retrieving the name-of-the-host from the system, then resolving that name into a list of InetAddresses.

This method returns a cached result and is therefore likely not to block unless this is the first time this class is being referenced.

Parameters:

ipTypePref - filter

Returns:

Throws:

UnknownHostException - if no IP address for the host name could be found

See Also:

network.hname.HostnameUtils, InetAddress.getAllByName(java.lang.String)

getPrioritizedLocalHostAddresses

@NonNull
public static List<InetAddress> getPrioritizedLocalHostAddresses(IpAddressUtils.IpTypePreference ipTypePref)

Returns a prioritized list of local host addresses. The further up on this list, the more likely it is that the address is the host's IP address.

Prioritization is done on the following basis:

• IPv4 addresses are prioritized higher than IPv6 addresses.
• Addresses belonging to a non-virtual interface are prioritized higher than addresses belonging to a virtual interface.
• Addresses belonging to an interface which supports multicast are prioritized higher than addresses belonging to an interface which doesn't support multicast.
• Addresses belonging to an interface which look like a software virtual adapters are prioritized lower than addresses belonging to interfaces which don't look software virtual adapters.
• Addresses with a broadcast address are prioritized higher than addresses with no broadcast address.

The method returns a cached result and is therefore likely not to block, unless this is the first time this class is being referenced.

Parameters:

ipTypePref - filter

Returns:

prioritized list of addresses

getDatagramLocalInetAddress

@NonNull
public static List<InetAddress> getDatagramLocalInetAddress(IpAddressUtils.IpTypePreference ipTypePref)

Returns the address of the local host, found by using UDP method.

This method works by creating a 'connected' UDP socket. Upon the connect operation, the Berkeley sockets API will populate the local endpoint (own host) according to the host's routing information. Hence we can use this for finding the IP of the local host. Note, that there is never any actual UDP connection created. We only use the socket to see how its metadata has been populated.

This method is known not to work on Mac OSX. It will most likely return an empty list if on Mac OSX.

This method returns a cached result and is therefore likely not to block unless this is the first time this class is being referenced.

Parameters:

ipTypePref - IP protocol filter

Returns:

list of IP addresses, either of length 1 or length 0, never null.

See Also:

LocalAddressUtils.getMostLikelyLocalInetAddresses(IpAddressUtils.IpTypePreference)

getMostLikelyLocalInetAddresses

@NonNull
public static InetAddress[] getMostLikelyLocalInetAddresses(IpAddressUtils.IpTypePreference ipTypePref)

Returns the host's IP addresses. Or rather the IP addresses most likely to be the ones the host is known by. This method is much more likely to return a correct result than the JDKs InetAddress.getLocalHost(), in particular on hosts with multiple network interfaces or hosts that are virtualized or operating in a PaaS environment.

The method uses the following prioritization for determining what to return, by continously moving to the next step if the previous step yielded an empty result:

1. The list from getLocalHostAddresses() (List A) is compared to getPrioritizedLocalHostAddresses() (List B), picking the ones from List B list which is also on List A.
2. Use List B.
3. Use List A.
4. Use the result from LocalAddressUtils.getLocalHost() if it matches the ipTypePref filter.
5. Use the result from getDatagramLocalInetAddress() if it matches the ipTypePref filter.
6. Finally, if everything else fails, return the result of getLoopbackAddress().

The method uses the other methods in the class and is therefore likely not to block, unless this is the first time this class is being referenced.

Parameters:

ipTypePref - IP protocol filter

Returns:

IP addresses, never null

See Also:

LocalAddressUtils.getMostLikelyLocalInetAddress(IpAddressUtils.IpTypePreference)

getMostLikelyLocalInetAddress

@NonNull
public static InetAddress getMostLikelyLocalInetAddress(IpAddressUtils.IpTypePreference ipTypePref)

Returns the host's IP address. Same as getMostLikelyLocalInetAddresses() but only returns a single IP address.

Parameters:

ipTypePref - IP protocol filter

Returns:

IP address, never null

See Also:

LocalAddressUtils.getMostLikelyLocalInetAddresses(IpAddressUtils.IpTypePreference)

getLoopbackAddress

@NonNull
public static InetAddress getLoopbackAddress(IpAddressUtils.IpTypePreference ipTypePref)

Returns the loopback address.

This method is similar to InetAddress.getLoopbackAddress() except that the preference for IPv4 vs IPv6 can be explicitly stated.

For IPv4 the returned address is always 127.0.0.1 and for IPv6 it is ::1.

Parameters:

ipTypePref - IPv4 vs IP4v6 preference

Returns:

isSoftwareVirtualAdapter

public static boolean isSoftwareVirtualAdapter(NetworkInterface nif)

Tries to guess if the network interface is a virtual adapter by one of the makers of virtualization solutions (e.g. VirtualBox, VMware, etc). This is by no means a bullet proof method which is why it errs on the side of caution.

Parameters:

nif - network interface

Returns: