NetworkInterface Class

Factory Methods

Since NetworkInterface objects represent physical hardware and virtual addresses, they cannot be constructed arbitrarily. As with the InetAddress class, there are static factory methods that return the NetworkInterface object associated with a particular network interface. You can ask for a NetworkInterface by IP address, by name, or by enumeration.

public static NetworkInterface getByName(String name) throws SocketException

The getByName( ) method returns a NetworkInterface object representing the network interface with the particular name. If there's no interface with that name, it returns null. If the underlying network stack encounters a problem while locating the relevant network interface, a SocketException is thrown, but this isn't too likely to happen. The format of the names is platform-dependent. On a typical Unix system, the Ethernet interface names have the form eth0, eth1, and so forth. The local loopback address is probably named something like "lo". On Windows, the names are strings like "CE31" and "ELX100" that are derived from the name of the vendor and model of hardware on that particular network interface. For example, this code fragment attempts to find the primary Ethernet interface on a Unix system:

try {
 NetworkInterface ni = NetworkInterface.getByName("eth0");
 if (ni == null) {
 System.err.println("No such interface: eth0" );
 }
}
catch (SocketException ex) {
 System.err.println("Could not list sockets." );
}

public static NetworkInterface getByInetAddress(InetAddress address) throws SocketException

The getByInetAddress() method returns a NetworkInterface object representing the network interface bound to the specified IP address. If no network interface is bound to that IP address on the local host, then it returns null. If anything goes wrong, it throws a SocketException. For example, this code fragment finds the network interface for the local loopback address:

try {
 InetAddress local = InetAddress.getByName("127.0.0.1");
 NetworkInterface ni = NetworkInterface.getByName(local);
 if (ni == null) {
 System.err.println("That's weird. No local loopback address.");
 }
}
catch (SocketException ex) {
 System.err.println("Could not list sockets." );
}
catch (UnknownHostException ex) {
 System.err.println("That's weird. No local loopback address.");
}

public static Enumeration getNetworkInterfaces( ) throws SocketException

The getNetworkInterfaces() method returns a java.util.Enumeration listing all the network interfaces on the local host. Example 6-10 is a simple program to list all network interfaces on the local host:

Example 6-10. A program that lists all the network interfaces

import java.net.*;
import java.util.*;
public class InterfaceLister {
 public static void main(String[] args) throws Exception {
 Enumeration interfaces = NetworkInterface.getNetworkInterfaces( );
 while (interfaces.hasMoreElements( )) {
 NetworkInterface ni = (NetworkInterface) interfaces.nextElement( );
 System.out.println(ni); } }
}

Here's the result of running this on the IBiblio login server:

% java InterfaceLister
name:eth1 (eth1) index: 3 addresses:
/192.168.210.122;
name:eth0 (eth0) index: 2 addresses:
/152.2.210.122;
name:lo (lo) index: 1 addresses:
/127.0.0.1;

You can see that this host has two separate Ethernet cards plus the local loopback address. Ignore the number of addresses (3, 2, and 1). It's a meaningless number, not the actual number of IP addresses bound to each interface.

Getter Methods

Once you have a NetworkInterface object, you can inquire about its IP address and name. This is pretty much the only thing you can do with these objects.

public Enumeration getInetAddresses( )

A single network interface may be bound to more than one IP address. This situation isn't common these days, but it does happen. The getInetAddresses( ) method returns a java.util.Enumeration containing an InetAddress object for each IP address the interface is bound to. For example, this code fragment lists all the IP addresses for the eth0 interface:

NetworkInterface eth0 = NetworkInterrface.getByName("eth0");
Enumeration addresses = eth0.getInetAddresses( );
while (addresses.hasMoreElements( )) {
 System.out.println(addresses.nextElement( )); }

public String getName( )

The getName( ) method returns the name of a particular NetworkInterface object, such as eth0 or lo.

public String getDisplayName( )

The getDisplayName( ) method allegedly returns a more human-friendly name for the particular NetworkInterface-something like "Ethernet Card 0". However, in my tests on Unix, it always returned the same string as getName( ). On Windows, you may see slightly friendlier names such as "Local Area Connection" or "Local Area Connection 2".

Object Methods

The NetworkInterface class defines the equals(), hashCode( ), and toString( ) methods with the usual semantics:

public boolean equals( )
public int hashCode( )
public String toString( )

Two NetworkInterface objects are equal if they represent the same physical network interface (e.g., both point to the same Ethernet port, modem, or wireless card) and they have the same IP address. Otherwise, they are not equal. NetworkInterface does not implement Cloneable, Serializable, or Comparable. NetworkInterface objects cannot be cloned, compared, or serialized.