The Network Interface Information Service is a service that provides a standard way for bundles to receive notification about changes in the network interface and IP address.
When the IP address has changed, bundles utilizing the IP address
information need to detect this change. When using the standard Java API,
such as java.net.NetworkInterface and
java.net.InetAddress, calls to confirm the IP address at
regular intervals are required. Since this is a process common to all
bundles that need to detect any change in IP address information, this
specification defines a notification feature for all available network
interfaces, including the IP address. In addition, this specification
defines an API that provides the function to obtain the network interface
information and the information about the IP address bound to a network
interface.
The name of a network interface can be Operating System specific. In order for bundles to refer to the network interface it is necessary to distinguish the network interface in a form that it is independent of the Operating System.
This specification defines the NetworkAdapter Service
and NetworkAddress Service. These services provide
information about the network interface and IP addresses.
-
Network Interface - Available and activated network interfaces provided in the execution environment. In this specification, the unit of the network interface is the logical interface, not the physical interface.
-
NetworkAdapter - The OSGi service that provides information related to the Network Interface. This service provides function similar to
java.net.NetworkInterface. -
NetworkAddress - The OSGi service that provides information of IP addresses available on the execution environment in which a Network Interface Information Service bundle is running.
-
Network Interface Information Service bundle - The OSGi bundle that implements NetworkAdapter and NetworkAddress services. Network Interface Information Service bundle registers NetworkAdapter and NetworkAddress services with the Framework.
-
Network Interface Type - An identifier of the network interface. It is independent of the operating system. The two type of identifier string is specified in this specification. This specification allows that Network Interface type other than them can be defined by the platform provider in each environment. This identifier is used by user bundle to specify the network interface to be monitored.
-
IPAddressVersion - An identifier indicating the IP address version. For example, IPv4, IPv6. This identifier is defined in this specification. This identifier is used by a bundle to specify the network interface to be monitored.
-
IPAddressScope - An identifier indicating the scope of IP address. For example, GLOBAL, PRIVATE. This identifier is defined in this specification. This identifier is used by a bundle to specify the network interface to be monitored.
The NetworkAdapter service provides the network interface
information for a logical interface. NetworkAddress service provides the IP address information for
an IP address. A NetworkAddress service is associated with
a NetworkAdapter service.
When network interface information is changed, the service
properties of the corresponing NetworkAdapter service and
NetworkAddress service are changed. It is necessary for the
bundle using these services to track these services and be advised of
changes in the network interface information through Service
Events.
NetworkAdapter is an interface that provides information about a
single network interface provided by the execution environment. If
multiple network interfaces are present, NetworkAdapter
services that correspond to each network interface must be registered.
NetworkAdapter services must be registered with service
properties as shown in the following table.
Table 143.1 Service properties of NetworkAdapter service
| The key of service property | Type | Description |
|---|---|---|
networkAdapter.type |
String |
Required property. Network interface type is set to a value. |
networkAdapter.hardwareAddress |
byte[] |
Required property. Hardware address (MAC address) is set to a value. This property can also be obtained from getHardwareAddress(). |
networkAdapter.name |
String |
Required property. Network interface name is set to a value. This property can also be obtained from getName(). |
networkAdapter.displayName |
String |
Required property. Network interface display name is set to a value. This property can also be obtained from getDisplayName(). |
networkAdapter.isUp |
boolean |
Required property. The value is true when a network interface is up and running, otherwise it is false. |
networkAdapter.isLoopback |
boolean |
Required property. The value is true when a network interface is a loopback interface, otherwise it is false. |
networkAdapter.isPointToPoint |
boolean |
Required property. The value is true when a network interface is a point to point interface, otherwise it is false. |
networkAdapter.isVirtual |
boolean |
Required property. The value is true when a network interface is a virtual interface, otherwise it is false. |
networkAdapter.supportsMulticast |
boolean |
Required property. The value is true when a network interface supports multicasting, otherwise it is false. |
networkAdapter.parent |
String |
Required property. Service PID of the NetworkAdapter service which is parent of this NetworkAdapter is specified. |
networkAdapter.subInterface |
String[] |
Required property. Service PID of the NetworkAdapter service which is subinterface of this NetworkAdapter is specified. |
When a network interface becomes available, a
NetworkAdapter service associated with the network interface
is registered with the service registry. If the network interface becomes
unavailable, the corresponding NetworkAdapter service is
unregistered.
When the attribute values of the network interface change, the
NetworkAdapter service is updated with changed service
properties. NetworkAdapter interface provides a method
corresponding to java.net.NetworkInterface in order to
provide information on the associated network interface.
Identifying the network interface is possible by using the network
interface name. However, since the network interface name is an
identifier that is dependent on the operating system, if network
interface name is used as identifier, bundles must be implemented to be
aware of the operating system. Therefore, in this specification,
"network interface type” which is independent of the operating system,
is used to identify the network interface. The network interface type
string of "LAN" and "WAN" are defined in this specification. This
specification allows that Network Interface type other than "LAN"and
"WAN" can be defined by the platform provider in each environment. It is
provided by the platform provider on which Network Interface Information
Service bundle is running. Network Interface type "LAN"indicates the
network interface connects to a local area network. Network Interface
type "WAN" indicates the network interface connects to an external
network (i.e. Internet). If a bundle wants to obtain the information of
the network interface connected to the Internet, the bundle is able to
get it by obtaining NetworkAdapter service with the
networkAdapter.type service property set to the value
"WAN".
This specification allows that Network Interface type other than "LAN"and "WAN" can be defined by the platform provider in each environment. It may be provided by the platform provider on which Network Interface Information Service bundle is running.
Table 143.2 Network Interface Type
| Network Interface Type | Description |
|---|---|
LAN |
The network interface to connect to a local area
network. |
WAN |
The network interface to connect to an external
network (i.e. Internet). |
NetworkAddress interface provides information about an IP address
available in the execution environment in which the a Network Interface
Information Service bundle is running. NetworkAddress service
is registered with the service registry together with service properties
as shown in the following table.
Table 143.3 Service properties of NetworkAddress service
| The key of service property | Type | Description |
|---|---|---|
networkAdapter.type |
String |
Required property. Network interface type is set to a value. |
ipAddress.version |
String |
Required property. IP address version is set to a value. |
ipAddress.scope |
String |
Required property. IP address scope is set to a value. |
ipAddress |
String |
Required property. IP address String is set to a value. |
subnetmask.length |
int |
Required property. Subnet mask length of the required properties IPv4, or IPv6 prefix length is set to a value. |
networkAdapter.pid |
String |
Required property. Service PID of the NetworkAdapterService corresponding to the network interface binding this IP address is set to a value. |
A NetworkAddress service is registered with the service
registry for each available IP address. When an associated IP address is
deleted, or the network interface to which the IP address is bound becomes
unavailable, the NetworkAddress service is unregistered. When
the associated IP address changes, the NetworkAddress service
is updated with updated service properties. A bundle can detect the change
of IP address by monitoring the registration or unregistering, updating of
the NetworkAddress service. When registering a NetworkAdapter
service, the Network Interface Information Service bundle must register it
with a unique service PID. Because IP addresses are bound to a network
interface, the service PID of the associated NetworkAdapter
service and its network interface type are set in the service properties
of the NetworkAddress service.
Defines the version of the IP address. A bundle can select
NetworkAddress services using the following IP address
version.
Table 143.4 IP Address Version
| IP Address Version | Description |
|---|---|
IPV4 |
IP address version which means IPv4 address.
|
IPV6 |
IP address version which means IPv6 address.
|
Defins the scope of the IP address. A bundle can select
NetworkAddress services using the following IP address
scope.
Table 143.5 IP Address Scope
| IP Address Scope | Description |
|---|---|
GLOBAL |
IP address scope which means global
address. |
PRIVATE_USE |
IP address scope which means private
address. |
LOOPBACK |
IP address scope which means loopback
address. |
LINKLOCAL |
IP address scope which means link local
address. |
UNIQUE_LOCAL |
IP address scope which means
unique-localaddress. |
UNSPECIFIED |
IP address scope which means the absence of an
address. |
If a bundle which wants to check for an IP address of the IPv4
global, the bundle is able to confirm by obtaining
NetworkAddress service with the
ipAddress.version service property set to the value
"IPV4" and the ipAddress.scope service
property set to the value "GLOBAL".
The following example shows the usage of NetworkAddress
service. The sample Controller class extends the
ServiceTracker class so that it can track
NetworkAddress services.
class Controller extends ServiceTracker {
Controller(BundleContext context) {
super(context, NetworkAdapter.class.getName(), null);
}
public Object addingService(ServiceReference ref) {
NetworkAdapter addAdapter = (NetworkAdapter)super.addingService(ref);
String type = addAdapter.getNetworkAdapterType();
String displayName = addAdapter.getDisplayName();
// ...
String servicePID = (String)ref.getProperty(Constants.SERVICE_PID);
try {
String filter
= "(" + NetworkAddress.NETWORKADAPTER_PID + "=" + servicePID + ")";
ServiceReference[] refs
= context.getServiceReferences(NetworkAddress.class.getName(), filter);
for (int i = 0; i < refs.length; i++) {
NetworkAddress address = (NetworkAddress) context.getService(refs[i]);
String ipAddress = address.getIpAddress();
int subnetMaskLength = address.getSubnetMaskLength();
// ...
}
} catch (InvalidSyntaxException e) {
e.printStackTrace();
}
return addAdapter;
}
}To acquire network interface information, a bundle needs
ServicePermission[NetworkAdapter, GET] and
ServicePermission[NetworkAddress, GET]. It can use Filter
Based Permissions. When a platform provider performs access control of the
bundle, It can set ServicePermission like the following example.
ServicePermission["(&(objectClass=org.osgi.service.networkadapter.NetworkAdapter)(networkAdapter.type=LAN))",GET]
ServicePermission["(&(objectClass=org.osgi.service.networkadapter.NetworkAddress)(networkAdapter.type=LAN)
(ipAddress.version=IPV4)(ipAddress.scope=PRIVATE_USE))", GET]
The NetworkAdapter service and the
NetworkAddress service should only be implemented by trusted
bundles. This bundle requires ServicePermission[NetworkAdapter,
REGISTER] and ServicePermission[NetworkAddress,
REGISTER].
Network Interface Information Service Specification Package Version 1.0.
Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.
Example import for consumers using the API in this package:
Import-Package: org.osgi.service.networkadapter; version="[1.0,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.service.networkadapter; version="[1.0,1.1)"
-
NetworkAdapter- NetworkAdapter is an interface that provides information about single network interfaces provided by the execution environment. -
NetworkAddress- This interface represents an IP address information.
NetworkAdapter is an interface that provides information about single network interfaces provided by the execution environment.
If multiple network interfaces are present, NetworkAdapter Services that correspond to each network interface must be registered. Network interface information service is set the following information as service property.
-
NETWORKADAPTER_TYPE : Network Interface Type
-
NETWORKADAPTER_DISPLAYNAME : Network Interface Display Name
-
NETWORKADAPTER_NAME : Network Interface Name
-
NETWORKADAPTER_HARDWAREADDRESS : Hardware Address
-
NETWORKADAPTER_IS_UP : Running status of Network Interface
-
NETWORKADAPTER_IS_LOOPBACK : To check loopback interface
-
NETWORKADAPTER_IS_POINTTOPOINT : To check point to point interface
-
NETWORKADAPTER_IS_VIRTUAL : To check virtual interface
-
NETWORKADAPTER_SUPPORTS_MULTICAST : To check supports multicasting
-
NETWORKADAPTER_PARENT : The PID of parent Network Interface
-
NETWORKADAPTER_SUBINTERFACE : The PID of sub Network Interface
When a network interface becomes available, NetworkAdapter service associated with the network interface is registered with the service registry. If the network interface becomes unavailable, the corresponding NetworkAdapter service is unregistered.
When the attribute values of the network interface are set to the service property changes, NetworkAdapter service is updated. NetworkAdapter interface provides a method corresponding to java.net.NetworkInterface in order to provide information on the associated network interface. However, this interface method does not support the Static method. In addition, because NetworkInterface object or InetAddress object is registered in the service registry as NetworkAdapter and NetworkAddress, the NetworkAdapter interface does not provide a method to get those objects. NetworkAdapter provides a method to retrieve the value of an attribute of a network interface.
Thread-safe
The value byte array of service property, when information is not available.
The value string of service property, when information is not available.
The value string array of service property, when information is not available.
The string of network interface type which means the network interface to connect to a local area network.
The key string of "networkAdapter.displayName" service property.
Network Interface display name is specified. EMPTY_STRING if no display name is available.
The key string of "networkAdapter.hardwareAddress" service property.
Hardware Address is specified. EMPTY_BYTE_ARRAY if no hardware address is available.
The key string of "networkAdapter.isLoopback" service property.
The value is true when a network interface is a loopback interface, otherwise it is false.
The key string of "networkAdapter.isPointToPoint" service property.
The value is true when a network interface is a point to point interface, otherwise it is false.
The key string of "networkAdapter.isUp" service property.
The value is true when a network interface is up and running, otherwise it is false.
The key string of "networkAdapter.isVirtual" service property.
The value is true when a network interface is a virtual interface, otherwise it is false.
The key string of "networkAdapter.name" service property.
Network Interface Name is specified. EMPTY_STRING if no name is available.
The key string of "networkAdapter.parent" service property.
Service PID of the NetworkAdapter service which is parent of this NetworkAdapter is specified. EMPTY_STRING if no parent is available.
The key string of "networkAdapter.subInterface" service property.
Service PID of the NetworkAdapter service which is subinterface of this NetworkAdapter is specified. EMPTY_STRING_ARRAY if no subinterface is available.
The key string of "networkAdapter.supportsMulticast" service property.
The value is true when a network interface supports multicasting, otherwise it is false.
The key string of "networkAdapter.type" service property.
Network Interface Type is specified.
The string of network interface type which means the network interface to connect to an external network (i.e. Internet).
Returns the network interface display name of "networkAdapter.displayname" service property value.
Network Interface display name, or null if "networkAdapter.displayname" service property value is empty.
Returns the MAC address of "networkAdapter.hardwareAddress" service property value.
Hardware Address, or null if "networkAdapter.hardwareAddress" service property value is empty.
Returns the Maximum Transmission Unit (MTU) of this interface.
The value of the MTU for that interface.
SocketException– If an I/O error occurs.
Returns the network interface name of "networkAdapter.name" service property value.
Network Interface Name, or null if "networkAdapter.name" service property value is empty.
Returns the network interface type of "networkAdapter.type" service property value.
Network Interface Type, or null if "networkAdapter.type" service property value is empty.
Returns whether a network interface is a loopback interface.
true if the interface is a loopback interface.
SocketException– If an I/O error occurs.
Returns whether a network interface is a point to point interface.
true if the interface is a point to point interface.
SocketException– If an I/O error occurs.
Returns whether a network interface is up and running.
true if the interface is up and running.
SocketException– If an I/O error occurs.
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.
true if this interface is a virtual interface.
This interface represents an IP address information.
NetworkAddress interface provides information of IP addresses available in which execution environment on a Network Interface Information Service bundle is running. IP address information service is set the following information as service property.
-
NETWORKADAPTER_TYPE : Network Interface Type
-
IPADDRESS_VERSION : IP Address Version
-
IPADDRESS_SCOPE : IP Address Scope
-
IPADDRESS : IP Address
-
SUBNETMASK_LENGTH : Subnet Mask Length(IPv4) or Prefix Length(IPv6)
-
NETWORKADAPTER_PID : Service PID of the NetworkAdapter service to which this service belongs
NetworkAddress service is registered with the service registry for each available IP address. When associated IP addresses are deleted, or the network interface to which the IP address is bound becomes unavailable, the NetworkAddress service is unregistered. When the associated IP address changes, NetworkAddress service is updated. The user bundle can detect the change of IP address by monitoring the registration or unregistering, updating of NetworkAddress service. Because IP addresses are bound to the network interface, if any, Service PID of the associated NetworkAdapter service and its network interface type are set to service property. NetworkAdapter service MUST be registered after the all associated NetworkAddress services are registered. On the other hand, when unregistering services, after associated NetworkAdapter service is unregistered, NetworkAddress of all related services are unregistered.
Thread-safe
The value integer of service property, when information is not available.
The key string of "ipAddress" service property. IP Address is specified.
The key string of "ipAddress.scope" service property. IP Address scope is specified.
The string of IP address scope which means global address.
The global address is defined as the address other than the address defined in the RFC6890.
The string of IP address scope which means "This host on this network".
See RFC6890 for the definition of "This host on this network".
The string of IP address scope which means "Linked-Scoped Unicast".
See RFC6890 for the definition of "Linked-Scoped Unicast".
The string of IP address scope which means "Link Local".
See RFC6890 for the definition of "Link Local".
The string of IP address scope which means "Loopback".
See RFC6890 for the definition of "Loopback".
The string of IP address scope which means "Private-Use Networks".
See RFC6890 for the definition of "Private-Use Networks".
The string of IP address scope which means "Shared Address Space".
See RFC6890 for the definition of "Shared Address Space".
The string of IP address scope which means "Unique-Local".
See RFC6890 for the definition of "Unique-Local".
The string of IP address scope which means "Unspecified Address".
See RFC6890 for the definition of "Unspecified Address".
The key string of "ipAddress.version" service property. IP Address version is specified.
The string of IP address version which means IP address version 4.
The string of IP address version which means IP address version 6.
The key string of "networkAdapter.pid" service property.
Service PID of the interface information service to which it belongs is specified.
The key string of "networkAdapter.type" service property. Network Interface Type is specified.
The key string of "subnetmask.length" service property.
Subnet Mask Length(IPv4) or Prefix Length(IPv6) is specified. EMPTY_INTEGER if no length is available.
Returns the InetAddress object of this IP address.
Returned object is created from "ipaddress" service property value.
InetAddress, or null if "ipaddress" service property value is empty.
Returns the IP address of "ipaddress" service property value.
IP Address string, or null if "ipaddress" service property value is empty.
Returns the IP address scope of "ipaddress.scope" service property value.
IP Address Scope, or null if "ipaddress.scope" service property value is empty.
Returns the IP address version of "ipaddress.version" service property value.
IP Address Version, or null if "ipaddress.version" service property value is empty.
Returns the "networkadapter.pid" service property value.
Service ID of the interface information service to which it belongs, or null if "networkadapter.pid" service property value is empty.
Returns the network interface type of "networkAdapter.type" service property value.
Network Interface Type, or null if "networkAdapter.type" service property value is empty.
[1]RFC 6890 : Special-Purpose IP Address Registrieshttp://www.ietf.org/rfc/rfc6890.txt, April 2013