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

[Mark Sheppard]

On Mon, 2 Sep 2024 13:48:55 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

> Please find here a change that adds a few `@apiNote` and `@implNote` to `NetworkInterface` to clarify user expectation and implementation.

Also, I think it would be useful and helpful to allude to the "snapshot" characteristics of a NetworkInterface instance in the opening description of the class

public final class NetworkInterface
extends [Object](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/lang/Object.html)
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".

Add to this description,  some explanation to the fact that an instance of a NetworkInterface is reflective of its configuration at the time it was created, and that it is possible for that configuration to change due to dynamic reconfiguration policies within a host environment i.e. your "snapshot" details.

These  additions of implNote and apiNote to various methods will be helpful

-------------

PR Comment: https://git.openjdk.org/jdk/pull/20822#issuecomment-2324988339