com.bigdata.util.config

Class NicUtil

java.lang.Object

com.bigdata.util.config.NicUtil

public class NicUtil
extends Object

Utility class that provides a set of static convenience methods related to processing information about the current node's Network Interface Card(s) (NICs) and associated IP address(es) and hostname. Although useful in general, the methods in this utility class may be particularly useful when employed from within a Jini configuration file.

This class cannot be instantiated.

Method Summary

Methods

Modifier and Type	Method and Description
static String	getDefaultIpv4Address()
static String	getDefaultIpv4Address(boolean loopbackOk) Examines each address associated with each network interface card (nic) installed on the current node, and returns the String value of the first such address that is determined to be both reachable and an address type that represents an IPv4 address.
static InetAddress	getInetAddress(String name, int index, String host, boolean localHost) Returns the instance of InetAddress that represents the i-th IP address assigned to the network interface having the given name (where i is specified by the value of the index parameter).
static Map<InetAddress,String>	getInetAddressMap() Method that returns a Map in which the key component of each element is one of the addresses of one of the network interface cards (nics) installed on the current node, and the corresponding value component is the name of the associated nic to which that address is assigned.
static String	getIpAddress(String name) Returns the String value of the 0-th IP address assigned to the network interface or host having the given name, or null if that IP address cannot be retrieved.
static String	getIpAddress(String name, boolean localHost)
static String	getIpAddress(String name, int index)
static String	getIpAddress(String name, int index, boolean localHost)
static String	getIpAddress(String name, int index, String host)
static String	getIpAddress(String name, int index, String host, boolean localHost)
static String	getIpAddress(String name, String host)
static String	getIpAddress(String systemPropertyName, String defaultNic, boolean loopbackOk) Special-purpose convenience method that returns a String value representing the ip address of the current node.
static String	getIpAddressByHost(String host)
static String	getIpAddressByHost(String host, boolean localHost)
static String	getIpAddressByLocalHost()
static String	getMacAddress(String name) Method that returns the Media Access Control (MAC) address assigned to the network interface having the given name; returning the address as a String in a human-readable format that consists of six groups of two hexadecimal digits, separated by colons (:); e.g., 01:23:45:67:89:ab.
static NetworkInterface	getNetworkInterface(String name) Method that searches for and returns the network interface having the specified name.
static NetworkInterface[]	getNetworkInterfaceArray(String name) Method that searches for and returns an array whose elements are all the network interface(s) that correspond to the specified name.
static void	main(String[] args) Intended for use by scripts.

Methods inherited from class java.lang.Object

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

Method Detail

getNetworkInterface

public static NetworkInterface getNetworkInterface(String name)
                                            throws SocketException

Method that searches for and returns the network interface having the specified name.

Parameters:

name - String referencing the name of the network interface to return (for example, typical values for this parameter might be, "eth0", "eth1", "hme01", "lo", etc., depending on how the underlying platform is configured).

Returns:

an instance of NetworkInterface that represents the network interface corresponding to the given name, or null if there is no network interface with that name value.

Throws:

SocketException - if there is an error in the underlying I/O subsystem and/or protocol.

NullPointerException - if null is input for name.

getInetAddressMap

public static Map<InetAddress,String> getInetAddressMap()
                                                 throws SocketException

Method that returns a Map in which the key component of each element is one of the addresses of one of the network interface cards (nics) installed on the current node, and the corresponding value component is the name of the associated nic to which that address is assigned.

Returns:

a Map of key-value pairs in which the key is an instance of InetAddress referencing the address of one of the network interface cards installed on the current node, and the corresponding value is a String referencing the name of the associated network interface to which the address is assigned.

Throws:

SocketException - if there is an error in the underlying I/O subsystem and/or protocol.

getNetworkInterfaceArray

public static NetworkInterface[] getNetworkInterfaceArray(String name)
                                                   throws SocketException

Method that searches for and returns an array whose elements are all the network interface(s) that correspond to the specified name.

Parameters:

name - String referencing the name to which the desired network interface(s) correspond.

Returns:

an array whose elements are each instances of NetworkInterface[], in which each such instance corresponds to the given name, or null if there is no network interface corresponding to that name value. Note that if the value given for the name parameter is the String "all", then this method will return an array containing all of the network interfaces installed on the current node, regardless of each interface's name.

Throws:

SocketException - if there is an error in the underlying I/O subsystem and/or protocol.

NullPointerException - if null is input for name.

getInetAddress

public static InetAddress getInetAddress(String name,
                         int index,
                         String host,
                         boolean localHost)

Returns the instance of InetAddress that represents the i-th IP address assigned to the network interface having the given name (where i is specified by the value of the index parameter).

If this method fails to retrieve the desired value for the given network interface name -- either because of a system error, or because a network interface with that name doesn't exist -- then this method provides the following optional fallback strategies, which will be executed in the order documented below:

• if the host parameter is non-null
• return the InetAddress for the given host name (or IP address string value)

If the previous fallback strategy fails, then

• if the localHost parameter is true
• return the InetAddress for system local host

Thus, although this method gives priority to the network interface name, if one wishes to force this method to return the InetAddress for a given host name rather than for a network interface, then null (or a name value known to not exist on the system) should be input for the name parameter. Similarly, if one wishes to force this method to return the InetAddress of the local host, then null should be input for both the name parameter and the host parameter.

If each of the strategies described above fail, then this method returns null.

Parameters:

name - String referencing the name of the network interface to query for the desired address.

index - non-negative int value that indicates which IP address, from the list of IP address(es) assigned to the network interface, should be used when retrieving the InetAddress to return. Note that 0 is typically input for this value.

host - String referencing the name of the host whose InetAddress should be returned if failure occurs for the name parameter.

localHost - if true, then upon failure to retrieve a valid value for the given name and the given host (in that order), attempt to return the InetAddress of the local host.

Returns:

the instance of InetAddress that represents the index-th IP address assigned to the network interface having the given name, or the given host name, or the local host.

Throws:

NullPointerException - if null is input for both name and host, and localHost is false.

IllegalArgumentException - if the value input for index is negtive.

IndexOutOfBoundsException - if the value input for index is out of range; that is if the value input is greater than or equal to the number of IP address(es) assigned to the corresponding network interface.

getMacAddress

public static String getMacAddress(String name)
                            throws SocketException

Method that returns the Media Access Control (MAC) address assigned to the network interface having the given name; returning the address as a String in a human-readable format that consists of six groups of two hexadecimal digits, separated by colons (:); e.g., 01:23:45:67:89:ab.

If this method fails to retrieve the desired MAC address for the given network interface name -- either because of a system error, or because a network interface with the given name does not exist -- then null is returned.

Parameters:

name - String referencing the name of the network interface whose MAC address should be returned.

Returns:

a String, in human-readable format, whose value is constructed from the MAC address assigned to the network interface having the given name; or null if the MAC address of the desired network interface cannot be retrieved.

Throws:

SocketException - if there is an error in the underlying I/O subsystem and/or protocol.

NullPointerException - if null is input for name.

getIpAddress

public static String getIpAddress(String name)

Returns the String value of the 0-th IP address assigned to the network interface or host having the given name, or null if that IP address cannot be retrieved.

getIpAddress

public static String getIpAddress(String name,
                  int index)

getIpAddress

public static String getIpAddress(String name,
                  String host)

getIpAddress

public static String getIpAddress(String name,
                  int index,
                  String host)

getIpAddress

public static String getIpAddress(String name,
                  int index,
                  String host,
                  boolean localHost)

getIpAddress

public static String getIpAddress(String name,
                  boolean localHost)

getIpAddress

public static String getIpAddress(String name,
                  int index,
                  boolean localHost)

getIpAddressByHost

public static String getIpAddressByHost(String host)

getIpAddressByHost

public static String getIpAddressByHost(String host,
                        boolean localHost)

getIpAddressByLocalHost

public static String getIpAddressByLocalHost()

getIpAddress

public static String getIpAddress(String systemPropertyName,
                  String defaultNic,
                  boolean loopbackOk)
                           throws SocketException,
                                  IOException

Special-purpose convenience method that returns a String value representing the ip address of the current node.

If a non-null value is input for the systemPropertyName parameter, then this method first determines if a system property with name equivalent to the given value has been set and, if it has, returns the ip address of the nic whose name is equivalent to that system property value; or null if there is no nic with the desired name installed on the node.

If there is no system property whose name is the value of the systemPropertyName parameter, and if the value "default" is input for the defaultNic parameter, then this method will return the IPV4 based address of the first reachable nic that can be found on the node; otherwise, if a non-null value not equal to "default" is input for the the defaultNic parameter, then this method returns the ip address of the nic corresponding to that given name; or null if there is no such nic name installed on the node.

If, on the other hand, null is input for the systemPropertyName parameter, then this method will attempt to find the desired ip address using only the value of the defaultNic, and applying the same search criteria as described above.

Note that in all cases, if true is input for the loopOk parameter, then upon failing to find a valid ip address using the specified search mechanism, this method will return the loop back address; otherwise, null is returned.

This method can be called from within a configuration as well as from within program control.

Parameters:

systemPropertyName - String value containing the name of a system property whose value is the network interface name whose ip address should be returned. May be null.

defaultNic - String value containing the name of the network interface whose ip address should be returned if null is input for the systemPropertyName parameter, or if there is no system property with name equivalent the value of the systemPropertyName parameter.

loopbackOk - if true, then return the loop back address upon failure to find a valid ip address using the search criteria specified through the systemPropertyName and defaultNic parameters.

Returns:

a String representing an ip address associated with the current node; where the value that is returned is determined according to the criteria described above.

Throws:

SocketException

IOException

getDefaultIpv4Address

public static String getDefaultIpv4Address(boolean loopbackOk)
                                    throws SocketException,
                                           IOException

Examines each address associated with each network interface card (nic) installed on the current node, and returns the String value of the first such address that is determined to be both reachable and an address type that represents an IPv4 address. This method will always first examine addresses that are not the loopback address (local host); returning a loopback adddress only if true is input for the loopbackOk parameter, and none of the non-loopback addresses satisfy this method's search criteria. If this method fails to find any address that satisfies the above criteria, then this method returns null.

Parameters:

loopbackOk - if true, then upon failure find an non-loopback address that satisfies this method's search criteria (an IPv4 type address and reachable), the first loopback address that is found to be reachable is returned. If false is input for this parameter, then this method will examine only those addresses that do not correspond to the corresponding nic's loopback address.

Returns:

a String value representing the first network interface address installed on the current node that is determined to be both reachable and an IPv4 type address; where the return value corresponds to a loopback address only if true is input for the loopbackOk parameter, and no non-loopback address satisfying the desired criteria can be found. If this method fails to find any address that satisfies the desired criteria, then null is returned.

Throws:

SocketException - if there is an error in the underlying I/O subsystem and/or protocol while retrieving the the network interfaces currently installed on the node.

IOException - if a network error occurs while determining if a candidate return address is reachable.

getDefaultIpv4Address

public static String getDefaultIpv4Address()
                                    throws SocketException,
                                           IOException

Throws:

SocketException

IOException

main

public static void main(String[] args)

Intended for use by scripts.