8283779: Clarify API documentation of NetworkInterface with respect to configuration changes

src/java.base/share/classes/java/net/NetworkInterface.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -35,12 +35,29 @@
 import java.util.stream.StreamSupport;
 
 /**
- * This class represents a Network Interface made up of a name,
- * and a list of IP addresses assigned to this interface.
- * It is used to identify the local interface on which a multicast group
- * is joined.
- *
- * Interfaces are normally known by names such as "le0".
+ * This class represents a Network Interface.
+ * <p>
+ * A Network Interface is the point of interconnection
+ * between a computer and a private or public network.
+ * A Network Interface can be physical or logical.
+ * A network interface has a name, an index, zero or more assigned
+ * {@linkplain InetAddress IP addresses}, and zero or more {@linkplain
+ * InterfaceAddress MAC Addresses}. 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:
+ * typically, the set of IP addresses assigned to a network
+ * interface may change.
+ * <p>
+ * When obtaining a {@code NetworkInterface} instance, part of its
+ * configuration (such as its name and the list of assigned IP addresses),
+ * may be snapshot 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.
+ * <p>
+ * Network interface instances are typically used to identify the local
+ * interface on which a multicast group is joined.
  *
  * @since 1.4
  */
@@ -97,6 +114,11 @@ public String getName() {
      * {@link NetPermission}("getNetworkInformation") permission, then all
      * InetAddresses are returned.
      *
+     * @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()
@@ -116,6 +138,11 @@ public Enumeration<InetAddress> getInetAddresses() {
      * {@link NetPermission}("getNetworkInformation") permission, then all
      * InetAddresses are returned.
      *
+     * @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
@@ -249,6 +276,16 @@ public String getDisplayName() {
     /**
      * 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.
+     * The network configuration may change at any time, and this method may need to
+     * be invoked again to obtain a more up-to-date view of the network interface.
+     * 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.
+     *
      * @param   name
      *          The name of the network interface.
      *
@@ -271,6 +308,16 @@ public static NetworkInterface getByName(String name) throws SocketException {
     /**
      * 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.
+     * The network configuration may change at any time, and this method may need to
+     * be invoked again to obtain a more up-to-date view of the network interface.
+     * 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.
+     *
      * @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 +341,16 @@ public static NetworkInterface getByIndex(int index) throws SocketException {
      * 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.
+     * The network configuration may change at any time, and this method may need to
+     * be invoked again to obtain a more up-to-date view of the network interface.
+     * 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.
+     *
      * @param   addr
      *          The {@code InetAddress} to search with.
      *
@@ -334,8 +391,18 @@ public static NetworkInterface getByInetAddress(InetAddress addr) throws SocketE
      * 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.
+     * <p>
+     * The returned interface instances may reflect a snapshot of the
+     * configuration taken at the time the instance is created.
+     * The network configuration may change at any time, and this method may need to
+     * be invoked again 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.
      *
      * @return an Enumeration of NetworkInterfaces found on this machine
      * @throws     SocketException  if an I/O error occurs,
@@ -359,13 +426,22 @@ public static Enumeration<NetworkInterface> getNetworkInterfaces()
      * 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:
      * <pre> {@code
      * Stream<InetAddress> addrs = NetworkInterface.networkInterfaces()
      *     .flatMap(NetworkInterface::inetAddresses);
      * }</pre>
+     * <p>
+     * The returned interface instances may reflect a snapshot of the
+     * configuration taken at the time the instance is created.
+     * The network configuration may change at any time, and this method may need to
+     * be invoked again 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.
      *
      * @return a Stream of NetworkInterfaces found on this machine
      * @throws     SocketException  if an I/O error occurs,