Top Description Fields Constructors Methods
java.net

public final Class NetworkInterface

extends Object
Class Inheritance
Imports
java.util.Arrays, .Enumeration, .List, .NoSuchElementException, .Objects, .Spliterator, .Spliterators, java.util.stream.Stream, .StreamSupport
This class represents a Network Interface.

A Network Interface is an abstraction encapsulating the characteristics of a Network Interface Controller, or Virtual Network adapter, which is a system hardware/software component connecting a computer, or host system, to a computer network. A Network Interface can be physical or virtual. A Network Interface has a name, zero or more assigned IP addresses, zero or more MAC Addresses, and may have an index. The name is highly platform specific but a name such as "le0" is typical; it may not be unique. The index is a highly platform specific number that identifies the interface. The network configuration may change during the lifetime of the JVM. For example, the set of IP addresses assigned to a network interface can be transient and dynamically allocated, and may change at any time.

When obtaining a NetworkInterface instance, part of its configuration (such as its name and the list of assigned IP addresses), is reflective of its configuration at creation time. Obtaining an updated view of the network configuration may require looking up a network interface again in order to obtain a new instance.

Network interface instances are typically used to identify the local interface on which a multicast group is joined.

API Note

Several static methods in this class are factory methods, returning a new instance of a NetworkInterface, reflecting the configuration at the time of instantiation. The network configuration may change at any time, and as such, these methods may need to be invoked again in order to obtain a more up-to-date view of the network interfaces. In particular, there is no guarantee that the same interface will be found at the same index, or that the same network addresses will be bound to the interface, if the network configuration of the system has changed.

Since
1.4

Field Summary

Modifier and TypeField and Description
private InetAddress[]
addrs

private InterfaceAddress[]
bindings

private NetworkInterface[]
childs

private static final NetworkInterface
defaultInterface

private String
displayName

private int
index

private String
name

private NetworkInterface
parent

private boolean
virtual

Constructor Summary

AccessConstructor and Description
pack-priv
NetworkInterface()

Returns an NetworkInterface object with index set to 0 and name to null.

pack-priv
NetworkInterface(String name, int index, InetAddress[] addrs)

Method Summary

Modifier and TypeMethod and Description
private static native boolean
boundInetAddress0(InetAddress addr)

private static <T> Enumeration<T>
enumerationFromArray(T[] a)

public boolean

Returns:

true if the objects are the same; false otherwise.
equals(Object
the object to compare against.
obj)

Overrides java.lang.Object.equals.

Compares this object against the specified object.

private static native NetworkInterface[]
getAll()

public static NetworkInterface

Returns:

the NetworkInterface obtained from its index, or null if there is no interface with such an index on the system
getByIndex(int
an integer, the index of the interface
index)

Get a network interface given its index.

private static native NetworkInterface
getByIndex0(int index)

public static NetworkInterface

Returns:

A NetworkInterface or null if there is no network interface with the specified IP address.
getByInetAddress(InetAddress
The InetAddress to search with.
addr)

Convenience method to search for a network interface that has the specified Internet Protocol (IP) address bound to it.

private static native NetworkInterface
getByInetAddress0(InetAddress addr)

public static NetworkInterface

Returns:

A NetworkInterface with the specified name, or null if there is no network interface with the specified name.
getByName(String
The name of the network interface.
name)

Searches for the network interface with the specified name.

private static native NetworkInterface
getByName0(String name)

pack-priv static NetworkInterface

Returns:

the default interface
getDefault()

Returns the default network interface of this system

public String

Returns:

a non-empty string representing the display name of this network interface, or null if no display name is available.
getDisplayName()

Get the display name of this network interface.

public byte[]

Returns:

a byte array containing the address, or null if the address doesn't exist or is not accessible
getHardwareAddress()

Returns the hardware address (usually MAC) of the interface if it has one and if it can be accessed given the current privileges.

public int

Returns:

the index of this network interface or -1 if the index is unknown
getIndex()

Returns the index of this network interface.

public Enumeration<InetAddress>

Returns:

an Enumeration object with the InetAddresses bound to this network interface
getInetAddresses()

Get an Enumeration of the InetAddresses bound to this network interface.

public List<InterfaceAddress>

Returns:

a List object with the InterfaceAddress of this network interface
getInterfaceAddresses()

Get a List of the InterfaceAddresses of this network interface.

private static native byte[]
getMacAddr0(byte[] inAddr, String name, int ind)

public int

Returns:

the value of the MTU for that interface.
getMTU()

Returns the Maximum Transmission Unit (MTU) of this interface.

private static native int
getMTU0(String name, int ind)

public String

Returns:

the name of this network interface
getName()

Get the name of this network interface.

public static Enumeration<NetworkInterface>

Returns:

an Enumeration of NetworkInterfaces found on this machine
getNetworkInterfaces()

Returns an Enumeration of all the interfaces on this machine.

public NetworkInterface

Returns:

The NetworkInterface this interface is attached to.
getParent()

Returns the parent NetworkInterface of this interface if this is a subinterface, or null if it is a physical (non virtual) interface or has no parent.

public Enumeration<NetworkInterface>

Returns:

an Enumeration object with all of the subinterfaces of this network interface
getSubInterfaces()

Get an Enumeration with all the subinterfaces (also known as virtual interfaces) attached to this network interface.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

public Stream<InetAddress>

Returns:

a Stream object with the InetAddresses bound to this network interface
inetAddresses()

Get a Stream of the InetAddresses bound to this network interface.

private static native void
init()

pack-priv static boolean

Returns:

true iff the addr parameter is currently bound to one of the interfaces on this machine.
isBoundInetAddress(InetAddress
The InetAddress to search with.
addr)

Checks if the given address is bound to any of the interfaces on this machine.

public boolean

Returns:

true if the interface is a loopback interface.
isLoopback()

Returns whether a network interface is a loopback interface.

private static native boolean
isLoopback0(String name, int ind)

private static native boolean
isP2P0(String name, int ind)

public boolean

Returns:

true if the interface is a point to point interface.
isPointToPoint()

Returns whether a network interface is a point to point interface.

public boolean

Returns:

true if the interface is up and running.
isUp()

Returns whether a network interface is up and running.

private static native boolean
isUp0(String name, int ind)

public boolean

Returns:

true if this interface is a virtual interface.
isVirtual()

Returns whether this interface is a virtual interface (also called subinterface).

public static Stream<NetworkInterface>

Returns:

a Stream of NetworkInterfaces found on this machine
networkInterfaces()

Returns a Stream of all the interfaces on this machine.

private static <T> Stream<T>
streamFromArray(T[] a)

public Stream<NetworkInterface>

Returns:

a Stream object with all of the subinterfaces of this network interface
subInterfaces()

Get a Stream of all subinterfaces (also known as virtual interfaces) attached to this network interface.

public boolean

Returns:

true if the interface supports Multicasting.
supportsMulticast()

Returns whether a network interface supports multicasting or not.

private static native boolean
supportsMulticast0(String name, int ind)

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

addrsback to summary
private InetAddress[] addrs
bindingsback to summary
private InterfaceAddress[] bindings
childsback to summary
private NetworkInterface[] childs
defaultInterfaceback to summary
private static final NetworkInterface defaultInterface
displayNameback to summary
private String displayName
indexback to summary
private int index
nameback to summary
private String name
parentback to summary
private NetworkInterface parent
virtualback to summary
private boolean virtual

Constructor Detail

NetworkInterfaceback to summary
pack-priv NetworkInterface()

Returns an NetworkInterface object with index set to 0 and name to null. Setting such an interface on a MulticastSocket will cause the kernel to choose one interface for sending multicast packets.

NetworkInterfaceback to summary
pack-priv NetworkInterface(String name, int index, InetAddress[] addrs)

Method Detail

boundInetAddress0back to summary
private static native boolean boundInetAddress0(InetAddress addr) throws SocketException
enumerationFromArrayback to summary
private static <T> Enumeration<T> enumerationFromArray(T[] a)
equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Compares this object against the specified object. The result is true if and only if the argument is not null and it represents the same NetworkInterface as this object.

Two instances of NetworkInterface represent the same NetworkInterface if both the name and the set of InetAddresses bound to the interfaces are equal.

API Note

two NetworkInterface objects referring to the same underlying interface may not compare equal if the addresses of the underlying interface are being dynamically updated by the system.

Parameters
obj:Object

the object to compare against.

Returns:boolean

true if the objects are the same; false otherwise.

Annotations
@Override
See Also
java.net.InetAddress#getAddress()
getAllback to summary
private static native NetworkInterface[] getAll() throws SocketException
getByIndexback to summary
public static NetworkInterface getByIndex(int index) throws SocketException

Get a network interface given its index.

API Note

The returned interface instance may reflect a snapshot of the configuration taken at the time the instance is created. See the general discussion of snapshots and configuration for the semantics of the returned interface.

Parameters
index:int

an integer, the index of the interface

Returns:NetworkInterface

the NetworkInterface obtained from its index, or null if there is no interface with such an index on the system

Exceptions
SocketException:
if an I/O error occurs.
IllegalArgumentException:
if index has a negative value
Since
1.7
See Also
getIndex()
getByIndex0back to summary
private static native NetworkInterface getByIndex0(int index) throws SocketException
getByInetAddressback to summary
public static NetworkInterface getByInetAddress(InetAddress addr) throws SocketException

Convenience method to search for a network interface that has the specified Internet Protocol (IP) address bound to it.

If the specified IP address is bound to multiple network interfaces it is not defined which network interface is returned.

API Note

The returned interface instance may reflect a snapshot of the configuration taken at the time the instance is created. See the general discussion of snapshots and configuration for the semantics of the returned interface.

Parameters
addr:InetAddress

The InetAddress to search with.

Returns:NetworkInterface

A NetworkInterface or null if there is no network interface with the specified IP address.

Exceptions
SocketException:
If an I/O error occurs.
NullPointerException:
If the specified address is null.
getByInetAddress0back to summary
private static native NetworkInterface getByInetAddress0(InetAddress addr) throws SocketException
getByNameback to summary
public static NetworkInterface getByName(String name) throws SocketException

Searches for the network interface with the specified name.

API Note

The returned interface instance may reflect a snapshot of the configuration taken at the time the instance is created. See the general discussion of snapshots and configuration for the semantics of the returned interface.

Parameters
name:String

The name of the network interface.

Returns:NetworkInterface

A NetworkInterface with the specified name, or null if there is no network interface with the specified name.

Exceptions
SocketException:
If an I/O error occurs.
NullPointerException:
If the specified name is null.
getByName0back to summary
private static native NetworkInterface getByName0(String name) throws SocketException
getDefaultback to summary
pack-priv static NetworkInterface getDefault()

Returns the default network interface of this system

Returns:NetworkInterface

the default interface

getDisplayNameback to summary
public String getDisplayName()

Get the display name of this network interface. A display name is a human readable String describing the network device.

Returns:String

a non-empty string representing the display name of this network interface, or null if no display name is available.

getHardwareAddressback to summary
public byte[] getHardwareAddress() throws SocketException

Returns the hardware address (usually MAC) of the interface if it has one and if it can be accessed given the current privileges.

Returns:byte[]

a byte array containing the address, or null if the address doesn't exist or is not accessible

Exceptions
SocketException:
if an I/O error occurs.
Since
1.6
getIndexback to summary
public int getIndex()

Returns the index of this network interface. The index is an integer greater or equal to zero, or -1 for unknown. This is a system specific value and interfaces with the same name can have different indexes on different machines.

Returns:int

the index of this network interface or -1 if the index is unknown

Since
1.7
See Also
getByIndex(int)
getInetAddressesback to summary
public Enumeration<InetAddress> getInetAddresses()

Get an Enumeration of the InetAddresses bound to this network interface.

Implementation Note

The returned enumeration contains the InetAddresses that were bound to the interface at the time the interface configuration was read

Returns:Enumeration<InetAddress>

an Enumeration object with the InetAddresses bound to this network interface

See Also
inetAddresses()
getInterfaceAddressesback to summary
public List<InterfaceAddress> getInterfaceAddresses()

Get a List of the InterfaceAddresses of this network interface.

Returns:List<InterfaceAddress>

a List object with the InterfaceAddress of this network interface

Since
1.6
getMacAddr0back to summary
private static native byte[] getMacAddr0(byte[] inAddr, String name, int ind) throws SocketException
getMTUback to summary
public int getMTU() throws SocketException

Returns the Maximum Transmission Unit (MTU) of this interface.

Returns:int

the value of the MTU for that interface.

Exceptions
SocketException:
if an I/O error occurs.
Since
1.6
getMTU0back to summary
private static native int getMTU0(String name, int ind) throws SocketException
getNameback to summary
public String getName()

Get the name of this network interface.

Returns:String

the name of this network interface

getNetworkInterfacesback to summary
public static Enumeration<NetworkInterface> getNetworkInterfaces() throws SocketException

Returns an Enumeration of all the interfaces on this machine. The Enumeration contains at least one element, possibly representing a loopback interface that only supports communication between entities on this machine.

API Note

This method can be used in combination with getInetAddresses() to obtain all IP addresses for this node.

The returned interface instances may reflect a snapshot of the configuration taken at the time the instance is created. See the general discussion of snapshots and configuration for the semantics of the returned interface.

Returns:Enumeration<NetworkInterface>

an Enumeration of NetworkInterfaces found on this machine

Exceptions
SocketException:
if an I/O error occurs, or if the platform does not have at least one configured network interface.
See Also
networkInterfaces()
getParentback to summary
public NetworkInterface getParent()

Returns the parent NetworkInterface of this interface if this is a subinterface, or null if it is a physical (non virtual) interface or has no parent.

Returns:NetworkInterface

The NetworkInterface this interface is attached to.

Since
1.6
getSubInterfacesback to summary
public Enumeration<NetworkInterface> getSubInterfaces()

Get an Enumeration with all the subinterfaces (also known as virtual interfaces) attached to this network interface.

For instance eth0:1 will be a subinterface to eth0.

Returns:Enumeration<NetworkInterface>

an Enumeration object with all of the subinterfaces of this network interface

Since
1.6
See Also
subInterfaces()
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
inetAddressesback to summary
public Stream<InetAddress> inetAddresses()

Get a Stream of the InetAddresses bound to this network interface.

Implementation Note

The stream contains the InetAddresses that were bound to the interface at the time the interface configuration was read

Returns:Stream<InetAddress>

a Stream object with the InetAddresses bound to this network interface

Since
9
initback to summary
private static native void init()
isBoundInetAddressback to summary
pack-priv static boolean isBoundInetAddress(InetAddress addr) throws SocketException

Checks if the given address is bound to any of the interfaces on this machine.

Parameters
addr:InetAddress

The InetAddress to search with.

Returns:boolean

true iff the addr parameter is currently bound to one of the interfaces on this machine.

Exceptions
SocketException:
If an I/O error occurs.
isLoopbackback to summary
public boolean isLoopback() throws SocketException

Returns whether a network interface is a loopback interface.

Returns:boolean

true if the interface is a loopback interface.

Exceptions
SocketException:
if an I/O error occurs.
Since
1.6
isLoopback0back to summary
private static native boolean isLoopback0(String name, int ind) throws SocketException
isP2P0back to summary
private static native boolean isP2P0(String name, int ind) throws SocketException
isPointToPointback to summary
public boolean isPointToPoint() throws SocketException

Returns whether a network interface is a point to point interface. A typical point to point interface would be a PPP connection through a modem.

Returns:boolean

true if the interface is a point to point interface.

Exceptions
SocketException:
if an I/O error occurs.
Since
1.6
isUpback to summary
public boolean isUp() throws SocketException

Returns whether a network interface is up and running.

Returns:boolean

true if the interface is up and running.

Exceptions
SocketException:
if an I/O error occurs.
Since
1.6
isUp0back to summary
private static native boolean isUp0(String name, int ind) throws SocketException
isVirtualback to summary
public boolean isVirtual()

Returns whether this interface is a virtual interface (also called subinterface). Virtual interfaces are, on some systems, interfaces created as a child of a physical interface and given different settings (like address or MTU). Usually the name of the interface will the name of the parent followed by a colon (:) and a number identifying the child since there can be several virtual interfaces attached to a single physical interface.

Returns:boolean

true if this interface is a virtual interface.

Since
1.6
networkInterfacesback to summary
public static Stream<NetworkInterface> networkInterfaces() throws SocketException

Returns a Stream of all the interfaces on this machine. The Stream contains at least one interface, possibly representing a loopback interface that only supports communication between entities on this machine.

API Note

This method can be used in combination with inetAddresses()} to obtain a stream of all IP addresses for this node, for example: 

 Stream<InetAddress> addrs = NetworkInterface.networkInterfaces()
    .flatMap(NetworkInterface::inetAddresses);

The returned interface instances may reflect a snapshot of the configuration taken at the time the instance is created. See the general discussion of snapshots and configuration for the semantics of the returned interface.

Returns:Stream<NetworkInterface>

a Stream of NetworkInterfaces found on this machine

Exceptions
SocketException:
if an I/O error occurs, or if the platform does not have at least one configured network interface.
Since
9
streamFromArrayback to summary
private static <T> Stream<T> streamFromArray(T[] a)
subInterfacesback to summary
public Stream<NetworkInterface> subInterfaces()

Get a Stream of all subinterfaces (also known as virtual interfaces) attached to this network interface.

Returns:Stream<NetworkInterface>

a Stream object with all of the subinterfaces of this network interface

Since
9
supportsMulticastback to summary
public boolean supportsMulticast() throws SocketException

Returns whether a network interface supports multicasting or not.

Returns:boolean

true if the interface supports Multicasting.

Exceptions
SocketException:
if an I/O error occurs.
Since
1.6
supportsMulticast0back to summary
private static native boolean supportsMulticast0(String name, int ind) throws SocketException
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object