+ * 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 + * {@linkplain InetAddress IP addresses}, zero or more {@linkplain + * InterfaceAddress 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 {@code 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. * - * Interfaces are normally known by names such as "le0". + * @apiNote Several static methods in this class are + * factory methods, returning a new instance of a {@code 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 */ @@ -87,7 +118,7 @@ public final class NetworkInterface { } /** - * Get an Enumeration with all or a subset of the InetAddresses bound to + * Get an Enumeration with all, or a subset, of the InetAddresses bound to * this network interface. *
* If there is a security manager, its {@code checkConnect} @@ -97,7 +128,12 @@ public final class NetworkInterface { * {@link NetPermission}("getNetworkInformation") permission, then all * InetAddresses are returned. * - * @return an Enumeration object with all or a subset of the InetAddresses + * @implNote + * The returned enumeration contains all, or a subset, of the InetAddresses that were + * bound to the interface at the time the {@linkplain #getNetworkInterfaces() + * interface configuration was read} + * + * @return an Enumeration object with all, or a subset, of the InetAddresses * bound to this network interface * @see #inetAddresses() */ @@ -106,7 +142,7 @@ public final class NetworkInterface { } /** - * Get a Stream of all or a subset of the InetAddresses bound to this + * Get a Stream of all, or a subset, of the InetAddresses bound to this * network interface. *
* If there is a security manager, its {@code checkConnect} @@ -116,7 +152,12 @@ public final class NetworkInterface { * {@link NetPermission}("getNetworkInformation") permission, then all * InetAddresses are returned. * - * @return a Stream object with all or a subset of the InetAddresses + * @implNote + * The stream contains all, or a subset, of the InetAddresses that were + * bound to the interface at the time the {@linkplain #getNetworkInterfaces() + * interface configuration was read} + * + * @return a Stream object with all, or a subset, of the InetAddresses * bound to this network interface * @since 9 */ @@ -150,7 +191,7 @@ public final class NetworkInterface { } /** - * Get a List of all or a subset of the {@code InterfaceAddresses} + * Get a List of all, or a subset, of the {@code InterfaceAddresses} * of this network interface. *
* If there is a security manager, its {@code checkConnect} @@ -158,7 +199,7 @@ public final class NetworkInterface { * Only InterfaceAddresses where the {@code checkConnect} doesn't throw * a SecurityException will be returned in the List. * - * @return a {@code List} object with all or a subset of the + * @return a {@code List} object with all, or a subset, of the * InterfaceAddress of this network interface * @since 1.6 */ @@ -249,6 +290,12 @@ public final class NetworkInterface { /** * Searches for the network interface with the specified name. * + * @apiNote + * The returned interface instance may reflect a snapshot of the + * configuration taken at the time the instance is created. + * See the general discussion of {@linkplain NetworkInterface##lookup + * snapshots and configuration} for the semantics of the returned interface. + * * @param name * The name of the network interface. * @@ -271,6 +318,12 @@ public final class NetworkInterface { /** * Get a network interface given its index. * + * @apiNote + * The returned interface instance may reflect a snapshot of the + * configuration taken at the time the instance is created. + * See the general discussion of {@linkplain NetworkInterface##lookup + * snapshots and configuration} for the semantics of the returned interface. + * * @param index an integer, the index of the interface * @return the NetworkInterface obtained from its index, or {@code null} if * there is no interface with such an index on the system @@ -294,6 +347,12 @@ public final class NetworkInterface { * interfaces it is not defined which network interface is * returned. * + * @apiNote + * The returned interface instance may reflect a snapshot of the + * configuration taken at the time the instance is created. + * See the general discussion of {@linkplain NetworkInterface##lookup + * snapshots and configuration} for the semantics of the returned interface. + * * @param addr * The {@code InetAddress} to search with. * @@ -334,8 +393,14 @@ public final class NetworkInterface { * a loopback interface that only supports communication between entities on * this machine. * - * @apiNote this method can be used in combination with - * {@link #getInetAddresses()} to obtain all IP addresses for this node + * @apiNote + * This method can be used in combination with + * {@link #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 {@linkplain NetworkInterface##lookup + * snapshots and configuration} for the semantics of the returned interface. * * @return an Enumeration of NetworkInterfaces found on this machine * @throws SocketException if an I/O error occurs, @@ -359,13 +424,18 @@ public final class NetworkInterface { * loopback interface that only supports communication between entities on * this machine. * - * @apiNote this method can be used in combination with + * @apiNote This method can be used in combination with * {@link #inetAddresses()}} to obtain a stream of all IP addresses for * this node, for example: *
{@code
* Stream 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 {@linkplain NetworkInterface##lookup + * snapshots and configuration} for the semantics of the returned interface. * * @return a Stream of NetworkInterfaces found on this machine * @throws SocketException if an I/O error occurs,