8283779: Clarify API documentation of NetworkInterface with respect to configuration changes
Reviewed-by: alanb, msheppar
This commit is contained in:
Daniel Fuchs
parent
92431049fd
commit
c8e64cb7a5
@ -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,43 @@ import java.util.stream.Stream;
|
||||
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.
|
||||
* This class represents a Network Interface.
|
||||
* <p>
|
||||
* 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.
|
||||
* <p>
|
||||
* 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.
|
||||
* <p>
|
||||
* 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 <a id="lookup"></a>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.
|
||||
* <p>
|
||||
* 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.
|
||||
* <p>
|
||||
* 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.
|
||||
* <p>
|
||||
* 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.
|
||||
* <p>
|
||||
* 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:
|
||||
* <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.
|
||||
* 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,
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user