jdk.dio

Class DeviceManager

java.lang.Object

jdk.dio.DeviceManager

public class DeviceManager
extends java.lang.Object

The DeviceManager class provides methods for opening and registering devices that can then be handled as Device instances. A device of a particular type can be opened using its platform-specific numeric ID or name as well as its properties or using an ad-hoc configuration (in which case, its hardware addressing information must be explicitly provided).

A device may be identified by a numeric ID. This ID is unrelated to the hardware number (hardware addressing information) that may be used to identify a device such as a GPIO pin number or an I2C slave device address. A device ID typically corresponds to a registered configuration for a device. The numeric ID of a device must be greater than or equal to 0 and must be unique. Yet the same device may be directly and indirectly mapped through several IDs; each ID may correspond to a different configuration, representation or abstraction for the same underlying device hardware resource.
A device opened with an ad-hoc configuration - that is: not through one of its registered configurations - is not assigned a numeric ID nor a name. Its numeric ID and name are both undefined and set respectively to UNDEFINED_ID and null.

Devices may be opened in either exclusive or shared mode. By default, devices are opened in exclusive mode. Whether a device can be opened in shared mode depends on the underlying device hardware as well as on the underlying device driver. It also depends on whether the provided Device implementation is a dedicated, virtualized or shared abstraction of the underlying device resource.
When a device is open with an ad-hoc configuration in shared mode then the Device implementation (or driver) may throw a InvalidDeviceConfigException if the device is already open and the requested adhoc configuration is incompatible with the current configuration of the device.
When a device is open in shared mode then some explicit means of access synchronization may have to be used such as by invoking Device.tryLock and Device.unlock. Device locks are held on a per Device instance basis. When the same device is open twice in shared access mode by the same application, locking one of the Device instances will prevent the other from being accessed/used.

Opening a device of a specific type with a registered configuration is subject to permission checks (see DeviceMgmtPermission.OPEN).
Opening a device of a specific type with an ad-hoc configuration is subject to permission checks specific for that type (for example see GPIOPinPermission.OPEN). This permission check should be implemented by the DeviceProvider.open method.
Registration and unregistration of devices are subject to permission checks (see DeviceMgmtPermission.REGISTER and DeviceMgmtPermission.UNREGISTER).
For more details see Security Model.

Device Probing

For some peripheral hardware such as I2C bus or SPI bus, opening (or registering) a device such as a slave device on a bus does not necessarily entail immediately accessing the device. Upon opening the device the underlying platform or driver may probe for the device to check whether the device exists and is addressable and whether the requested configuration is valid; if the probing for device determines that the device does not exist or is not addressable or, that it does not support the requested configuration a DeviceNotFoundException or respectively an InvalidDeviceConfigException is thrown. When the underlying platform or driver does not implement any probing facility a Device instance is returned, but I/O operations on the device will later fail - typically with an IOException - if the device does not exist, is not addressable, or does not support the requested configuration.

Since:

1.0

See Also:

UnavailableDeviceException, DeviceMgmtPermission, Device, DeviceProvider, DeviceConfig

Field Summary

Fields

Modifier and Type	Field and Description
static int	EXCLUSIVE Exclusive access mode.
static int	SHARED Shared access mode.
static int	UNSPECIFIED_ID Unspecified device numeric ID - requesting the allocation of a free ID.

Method Summary

Methods

Modifier and Type	Method and Description
static <P extends Device<? super P>> void	addRegistrationListener(RegistrationListener<P> listener, java.lang.Class<P> intf) Adds the specified registration listener to receive notification of registration and unregistration of devices of the specified type.
static <P extends Device<? super P>> java.util.Iterator<DeviceDescriptor<P>>	list() List all platform- and user-registered devices.
static <P extends Device<? super P>> java.util.Iterator<DeviceDescriptor<P>>	list(java.lang.Class<P> intf) List all platform- and user-registered devices of the designated type.
static <P extends Device<? super P>> P	open(java.lang.Class<P> intf, DeviceConfig<? super P> config) Opens a device, returning a Device instance of the specified type to access it.
static <P extends Device<? super P>> P	open(java.lang.Class<P> intf, DeviceConfig<? super P> config, int mode) Opens a device, returning a Device instance of the specified type to access it.
static <P extends Device<? super P>> P	open(DeviceConfig<? super P> config) Opens a device, returning a Device instance of the specified type to access it.
static <P extends Device<? super P>> P	open(DeviceConfig<? super P> config, int mode) Opens a device, returning a Device instance of the specified type to access it.
static <P extends Device<? super P>> P	open(int id) Looks up then opens the device designated by the provided numeric ID, returning a Device instance to access it.
static <P extends Device<? super P>> P	open(int id, java.lang.Class<P> intf) Looks up then opens the device designated by the provided numeric ID and type, returning a Device instance of the specified type to access it.
static <P extends Device<? super P>> P	open(int id, java.lang.Class<P> intf, int mode) Looks up then opens the device designated by the provided numeric ID and type, returning a Device instance of the specified type to access it.
static <P extends Device<? super P>> P	open(int id, int mode) Looks up then opens the device designated by the provided numeric ID, returning a Device instance to access it.
static <P extends Device<? super P>> P	open(java.lang.String name, java.lang.Class<P> intf, int mode, java.lang.String... properties) Looks up then opens a device designated by the provided name, type and properties, returning a Device instance of the specified type to access it.
static <P extends Device<? super P>> P	open(java.lang.String name, java.lang.Class<P> intf, java.lang.String... properties) Looks up then opens a device designated by the provided name, type and properties, returning a Device instance of the specified type to access it.
static <P extends Device<? super P>> int	register(int id, java.lang.Class<P> intf, DeviceConfig<? super P> config, java.lang.String name, java.lang.String... properties) Registers under the specified ID and name (as well as optional properties) a new device supporting the provided configuration.
static <P extends Device<? super P>> void	removeRegistrationListener(RegistrationListener<P> listener, java.lang.Class<P> intf) Removes the specified registration listener so that it no longer receives notification of registration and unregistration of devices of the specified type.
static void	unregister(int id) Unregisters the device associated with the specified ID.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EXCLUSIVE

public static final int EXCLUSIVE

Exclusive access mode.

This bit flag can be bitwise-combined (OR) with other access mode bit flags.

See Also:

Constant Field Values

SHARED

public static final int SHARED

Shared access mode.

This bit flag can be bitwise-combined (OR) with other access mode bit flags.

See Also:

Constant Field Values

UNSPECIFIED_ID

public static final int UNSPECIFIED_ID

Unspecified device numeric ID - requesting the allocation of a free ID.

See Also:

register, Constant Field Values

Method Detail

list

public static <P extends Device<? super P>> java.util.Iterator<DeviceDescriptor<P>> list()

List all platform- and user-registered devices.

Type Parameters:

P - the type of devices listed.

Returns:

an enumeration of the descriptors of all registered devices.

list

public static <P extends Device<? super P>> java.util.Iterator<DeviceDescriptor<P>> list(java.lang.Class<P> intf)

List all platform- and user-registered devices of the designated type.

Type Parameters:

P - the type of devices to list.

Parameters:

intf - the interface (sub-interface of Device) of the device to be registered.

Returns:

an enumeration of the descriptors of all registered devices of the designated type.

Throws:

java.lang.NullPointerException - if intf is null.

open

public static <P extends Device<? super P>> P open(java.lang.Class<P> intf,
                                   DeviceConfig<? super P> config)
                             throws java.io.IOException,
                                    InvalidDeviceConfigException,
                                    UnsupportedDeviceTypeException,
                                    DeviceNotFoundException,
                                    UnavailableDeviceException

Opens a device, returning a Device instance of the specified type to access it. The device to open is designated by the provided hardware addressing information and is initially set-up according to the specified configuration. The specified device type and specified configuration type must be compatible.

Opening a device from its hardware addressing information and with an ad-hoc configuration may be subject to device probing limitations .

The device is opened in exclusive access mode.

The returned Device instance's ID and name are undefined. A new instance is returned upon each call.

Type Parameters:

P - the type of the device to open.

Parameters:

intf - the interface (sub-interface of Device) of the device to open.

config - the device configuration (which includes hardware addressing information as well as configuration parameters).

Returns:

a new Device instance to access the designated device.

Throws:

UnsupportedDeviceTypeException - if the designated device type is not supported.

InvalidDeviceConfigException - if the provided device configuration (as defined by the configuration parameters) is not valid/supported.

DeviceNotFoundException - if the device designated by the hardware addressing information is not found.

UnavailableDeviceException - if the designated device is not currently available - such as if it is already open with exclusive access.

java.io.IOException - if any other I/O error occurred.

java.lang.SecurityException - if the caller has no permission to access the designated device (see DevicePermission.OPEN).

java.lang.NullPointerException - if intf or config is null.

java.lang.ClassCastException - if the device configuration type specified by config is not applicable to the device type specified by intf.

open

public static <P extends Device<? super P>> P open(java.lang.Class<P> intf,
                                   DeviceConfig<? super P> config,
                                   int mode)
                             throws java.io.IOException,
                                    InvalidDeviceConfigException,
                                    UnsupportedDeviceTypeException,
                                    DeviceNotFoundException,
                                    UnavailableDeviceException,
                                    UnsupportedAccessModeException

Opens a device, returning a Device instance of the specified type to access it. The device to open is designated by the provided hardware addressing information and is initially set-up according to the specified configuration. The specified device type and specified configuration type must be compatible.

Opening a device from its hardware addressing information and with an ad-hoc configuration may be subject to device probing limitations .

The device is opened in the designated access mode. A device may be opened in shared mode if supported by the underlying driver and hardware and if it is not already opened in exclusive mode. A device may be opened in exclusive mode if supported by the underlying driver and hardware and if it is not already opened.

The returned Device instance's ID and name are undefined. A new instance is returned upon each call.

Type Parameters:

P - the type of the device to open.

Parameters:

intf - the interface (sub-interface of Device) of the device to open.

config - the device configuration (which includes hardware addressing information as well as configuration parameters).

mode - the access mode, one of: EXCLUSIVE or SHARED.

Returns:

a new Device instance to access the designated device.

Throws:

UnsupportedDeviceTypeException - if the designated device type is not supported.

InvalidDeviceConfigException - if the provided device configuration (as defined by the configuration parameters) is not valid/supported or when opened in shared mode, if the provided device configuration is incompatible with the currently open configuration of the device.

DeviceNotFoundException - if the device designated by the hardware addressing information is not found.

UnavailableDeviceException - if the designated device is not currently available - such as if it is already open with exclusive access.

UnsupportedAccessModeException - if the requested access mode is not supported.

java.io.IOException - if any other I/O error occurred.

java.lang.SecurityException - if the caller has no permission to access the designated device (see DevicePermission.OPEN).

java.lang.NullPointerException - if intf or config is null.

java.lang.ClassCastException - if the device configuration type specified by config is not applicable to the device type specified by intf.

open

public static <P extends Device<? super P>> P open(int id)
                             throws java.io.IOException,
                                    DeviceNotFoundException,
                                    UnavailableDeviceException

Looks up then opens the device designated by the provided numeric ID, returning a Device instance to access it. The device configuration registered for the provided ID is first looked up; the device designated by the retrieved hardware addressing information is open and is initially set-up according to the registered configuration.

The device is opened in exclusive access mode. A new instance is returned upon each call.

Type Parameters:

P - the type of the device to open.

Parameters:

id - the numeric device id.

Returns:

a new Device instance to access the designated device.

Throws:

DeviceNotFoundException - if the designated device is not found.

UnavailableDeviceException - if the designated device is not currently available - such as if it is already open with exclusive access.

java.io.IOException - if any other I/O error occurred.

java.lang.SecurityException - if the caller has no permission to access the designated device (see DeviceMgmtPermission.OPEN).

java.lang.IllegalArgumentException - if id is less than 0.

open

public static <P extends Device<? super P>> P open(int id,
                                   java.lang.Class<P> intf)
                             throws java.io.IOException,
                                    UnsupportedDeviceTypeException,
                                    DeviceNotFoundException,
                                    UnavailableDeviceException

Looks up then opens the device designated by the provided numeric ID and type, returning a Device instance of the specified type to access it. The device configuration registered for the provided ID is first looked up; the device designated by the retrieved hardware addressing information is open and is initially set-up according to the registered configuration. The specified device type and retrieved configuration type must be compatible.

The device is opened in exclusive access mode. A new instance is returned upon each call.

Type Parameters:

P - the type of the device to open.

Parameters:

id - the numeric device id.

intf - the interface (sub-interface of Device) of the device being looked up.

Returns:

a new Device instance to access the designated device.

Throws:

DeviceNotFoundException - if the designated device is not found.

UnsupportedDeviceTypeException - if the designated device type is not supported.

UnavailableDeviceException - if the designated device is not currently available - such as if it is already open with exclusive access.

java.io.IOException - if any other I/O error occurred.

java.lang.SecurityException - if the caller has no permission to access the designated device (see DeviceMgmtPermission.OPEN).

java.lang.IllegalArgumentException - if id is less than 0.

java.lang.NullPointerException - if intf is null.

open

public static <P extends Device<? super P>> P open(int id,
                                   java.lang.Class<P> intf,
                                   int mode)
                             throws java.io.IOException,
                                    UnsupportedDeviceTypeException,
                                    DeviceNotFoundException,
                                    UnavailableDeviceException,
                                    UnsupportedAccessModeException

Looks up then opens the device designated by the provided numeric ID and type, returning a Device instance of the specified type to access it. The device configuration registered for the provided ID is first looked up; the device designated by the retrieved hardware addressing information is open and is initially set-up according to the registered configuration. The specified device type and retrieved configuration type must be compatible.

The device is opened in the designated access mode. A device may be opened in shared mode if supported by the underlying driver and hardware and if it is not already opened in exclusive mode. A device may be opened in exclusive mode if supported by the underlying driver and hardware and if it is not already opened.

A new instance is returned upon each call.

Type Parameters:

P - the type of the device to open.

Parameters:

id - the numeric device id.

intf - the interface (sub-interface of Device) of the device being looked up.

mode - the access mode, one of: EXCLUSIVE or SHARED.

Returns:

a new Device instance to access the designated device.

Throws:

UnsupportedDeviceTypeException - if the designated device type is not supported.

DeviceNotFoundException - if the designated device is not found.

UnavailableDeviceException - if the designated device is not currently available - such as when it is already open in an access mode incompatible with the requested access mode.

UnsupportedAccessModeException - if the requested access mode is not supported.

java.io.IOException - if any other I/O error occurred.

java.lang.SecurityException - if the caller has no permission to access the designated device (see DeviceMgmtPermission.OPEN).

java.lang.IllegalArgumentException - if id is less than 0.

java.lang.NullPointerException - if intf is null.

open

public static <P extends Device<? super P>> P open(int id,
                                   int mode)
                             throws java.io.IOException,
                                    DeviceNotFoundException,
                                    UnavailableDeviceException,
                                    UnsupportedAccessModeException

Looks up then opens the device designated by the provided numeric ID, returning a Device instance to access it. The device configuration registered for the provided ID is first looked up; the device designated by the retrieved hardware addressing information is open and is initially set-up according to the registered configuration.

The device is opened in the designated access mode. A device may be opened in shared mode if supported by the underlying driver and hardware and if it is not already opened in exclusive mode. A device may be opened in exclusive mode if supported by the underlying driver and hardware and if it is not already opened.

The device is opened in exclusive access mode. A new instance is returned upon each call.

Type Parameters:

P - the type of the device to open.

Parameters:

id - the numeric device id.

mode - the access mode, one of: EXCLUSIVE or SHARED.

Returns:

a new Device instance to access the designated device.

Throws:

DeviceNotFoundException - if the designated device is not found.

UnavailableDeviceException - if the designated device is not currently available - such as when it is already open in an access mode incompatible with the requested access mode.

UnsupportedAccessModeException - if the requested access mode is not supported.

java.io.IOException - if any other I/O error occurred.

java.lang.SecurityException - if the caller has no permission to access the designated device (see DeviceMgmtPermission.OPEN).

java.lang.IllegalArgumentException - if id is less than 0.

open

public static <P extends Device<? super P>> P open(DeviceConfig<? super P> config)
                             throws java.io.IOException,
                                    InvalidDeviceConfigException,
                                    UnsupportedDeviceTypeException,
                                    DeviceNotFoundException,
                                    UnavailableDeviceException

Opens a device, returning a Device instance of the specified type to access it. The device to open is designated by the provided hardware addressing information and is initially set-up according to the specified configuration. The type of the device is inferred from the configuration type.

Opening a device from its hardware addressing information and with an ad-hoc configuration may be subject to device probing limitations .

The device is opened in exclusive access mode.

The returned Device instance's ID and name are undefined. A new instance is returned upon each call.

Type Parameters:

P - the type of the device to open.

Parameters:

config - the device configuration (which includes hardware addressing information as well as configuration parameters).

Returns:

a new Device instance to access the designated device.

Throws:

UnsupportedDeviceTypeException - if the designated device type is not supported.

InvalidDeviceConfigException - if the provided device configuration (as defined by the configuration parameters) is not valid/supported.

DeviceNotFoundException - if the device designated by the hardware addressing information is not found.

UnavailableDeviceException - if the designated device is not currently available - such as if it is already open with exclusive access.

java.io.IOException - if any other I/O error occurred.

java.lang.SecurityException - if the caller has no permission to access the designated device (see DevicePermission.OPEN).

java.lang.NullPointerException - if config is null.

open

public static <P extends Device<? super P>> P open(DeviceConfig<? super P> config,
                                   int mode)
                             throws java.io.IOException,
                                    InvalidDeviceConfigException,
                                    UnsupportedDeviceTypeException,
                                    DeviceNotFoundException,
                                    UnavailableDeviceException,
                                    UnsupportedAccessModeException

Opens a device, returning a Device instance of the specified type to access it. The device to open is designated by the provided hardware addressing information and is initially set-up according to the specified configuration. The type of the device is inferred from the configuration type.

Opening a device from its hardware addressing information and with an ad-hoc configuration may be subject to device probing limitations.

The device is opened in the designated access mode. A device may be opened in shared mode if supported by the underlying driver and hardware and if it is not already opened in exclusive mode. A device may be opened in exclusive mode if supported by the underlying driver and hardware and if it is not already opened.

The returned Device instance's ID and name are undefined. A new instance is returned upon each call.

Type Parameters:

P - the type of the device to open.

Parameters:

config - the device configuration (which includes hardware addressing information as well as configuration parameters).

mode - the access mode, one of: EXCLUSIVE or SHARED.

Returns:

a new Device instance to access the designated device.

Throws:

UnsupportedDeviceTypeException - if the designated device type is not supported.

InvalidDeviceConfigException - if the provided device configuration (as defined by the configuration parameters) is not valid/supported or when opened in shared mode, if the provided device configuration is incompatible with the currently open configuration of the device.

DeviceNotFoundException - if the device designated by the hardware addressing information is not found.

UnavailableDeviceException - if the designated device is not currently available - such as if it is already open with exclusive access.

UnsupportedAccessModeException - if the requested access mode is not supported.

java.io.IOException - if any other I/O error occurred.

java.lang.SecurityException - if the caller has no permission to access the designated device (see DevicePermission.OPEN).

java.lang.NullPointerException - if config is null.

open

public static <P extends Device<? super P>> P open(java.lang.String name,
                                   java.lang.Class<P> intf,
                                   int mode,
                                   java.lang.String... properties)
                             throws java.io.IOException,
                                    UnsupportedDeviceTypeException,
                                    DeviceNotFoundException,
                                    UnavailableDeviceException,
                                    UnsupportedAccessModeException

Looks up then opens a device designated by the provided name, type and properties, returning a Device instance of the specified type to access it. A registered device configuration matching the provided name, type and properties is first looked up; if the device designated by the retrieved hardware addressing information is available it is open and initially set-up according to the matching configuration; if the device is already open in a mode that is not compatible with the requested mode the next matching registered device configuration is considered.
A provided null name matches all registered device names; an empty string name can only be matched by an empty string name or a by a null name.

The device is opened in the designated access mode. A device may be opened in shared mode if supported by the underlying driver and hardware and if it is not already opened in exclusive mode. A device may be opened in exclusive mode if supported by the underlying driver and hardware and if it is not already opened.

A new instance is returned upon each call.

Property-based lookup only uses exact (case-insensitive) matching and does not perform any semantic interpretation.

Type Parameters:

P - the type of the device to open.

Parameters:

name - the device name; may be null.

intf - the interface (sub-interface of Device) of the device being looked up.

mode - the access mode, one of: EXCLUSIVE or SHARED.

properties - the list of required properties; may be null.

Returns:

a new Device instance to access the designated device.

Throws:

UnsupportedDeviceTypeException - if the designated device type is not supported.

DeviceNotFoundException - if the designated device is not found.

UnavailableDeviceException - if the designated device is not currently available - such as when it is already open in an access mode incompatible with the requested access mode.

UnsupportedAccessModeException - if the requested access mode is not supported.

java.io.IOException - if any other I/O error occurred.

java.lang.SecurityException - if the caller has no permission to access the designated device (see DeviceMgmtPermission.OPEN).

java.lang.IllegalArgumentException - if both name is null and properties is empty.

java.lang.NullPointerException - if intf is null.

open

public static <P extends Device<? super P>> P open(java.lang.String name,
                                   java.lang.Class<P> intf,
                                   java.lang.String... properties)
                             throws java.io.IOException,
                                    UnsupportedDeviceTypeException,
                                    DeviceNotFoundException,
                                    UnavailableDeviceException

Looks up then opens a device designated by the provided name, type and properties, returning a Device instance of the specified type to access it. A registered device configuration matching the provided name, type and properties is first looked up; if the device designated by the retrieved hardware addressing information is available it is open and initially set-up according to the matching configuration; if the device is already open (therefore not available) the next matching registered device configuration is considered.
A provided null name matches all registered device names; an empty string name can only be matched by an empty string name or a by a null name.

The device is opened in exclusive access mode.

A new instance is returned upon each call.

Property-based lookup only uses exact (case-insensitive) matching and does not perform any semantic interpretation.

Type Parameters:

P - the type of the device to open.

Parameters:

name - the device name; may be null.

intf - the interface (sub-interface of Device) of the device being looked up.

properties - the list of required properties; may be null.

Returns:

a new Device instance to access the designated device.

Throws:

UnsupportedDeviceTypeException - if the designated device type is not supported.

DeviceNotFoundException - if the designated device is not found.

UnavailableDeviceException - if the designated device is not currently available - such as if it is already open with exclusive access.

java.io.IOException - if any other I/O error occurred.

java.lang.SecurityException - if the caller has no permission to access the designated device (see DeviceMgmtPermission.OPEN).

java.lang.IllegalArgumentException - if both name is null and properties is empty.

java.lang.NullPointerException - if intf is null.

register

public static <P extends Device<? super P>> int register(int id,
                                         java.lang.Class<P> intf,
                                         DeviceConfig<? super P> config,
                                         java.lang.String name,
                                         java.lang.String... properties)
                    throws java.io.IOException,
                           UnsupportedDeviceTypeException,
                           InvalidDeviceConfigException,
                           DeviceNotFoundException,
                           DeviceAlreadyExistsException

Registers under the specified ID and name (as well as optional properties) a new device supporting the provided configuration. Upon successful registration all RegistrationListener instances registered for the type of the registered device are notified.

An implementation of the DeviceManager MUST guarantee that an application registering a device is the first one to get notified (in the event it has registered a RegistrationListener for that type of devices).

The designated device may be probed to check if the provided configuration is valid (see device probing limitations ).

Prior to registering a new device of a certain type the DeviceMgmtPermission is checked with the action DeviceMgmtPermission.REGISTER.
For example, if a device of type GPIOPin is to be registered the DeviceMgmtPermission is checked with a target name composed of the requested device name and ID and with the action DeviceMgmtPermission.REGISTER.

The following is an example of how this method may be used to register a new UART with Modem control lines:

 DeviceManager.register(10, // the device ID
         ModemUART.class, // the device type/interface
         new UARTConfig.Builder()
             .setControllerNumber(0)
             .setChannelNumber(0)
             .setBaudRate(2400)
             .setDataBits(UARTConfig.DATABITS_8)
             .setParity(UARTConfig.PARITY_EVEN)
             .setStopBits(UARTConfig.STOPBITS_1)
             .setFlowControlMode(UARTConfig.FLOWCONTROL_NONE)
             .build(), // the device configuration
         "MODEM", // the device name
         "com.foobar.modem.xxx=true", "com.foobar.modem.yyy=true" // the device capabilities
 );
 

Type Parameters:

P - the type of the device to be registered.

Parameters:

id - the device ID; if id is equal to UNSPECIFIED_ID a free ID will be allocated.

intf - the interface (sub-interface of Device) of the device to be registered.

config - the device configuration.

name - the name of the device to be registered.

properties - the list of properties/capabilities of the device to be registered; may be null.

Returns:

the assigned device ID.

Throws:

InvalidDeviceConfigException - if the provided device configuration (as defined by the configuration parameters) is not valid/supported.

UnsupportedDeviceTypeException - if the designated device type is not supported.

DeviceNotFoundException - if the device designated by the hardware addressing information is not found.

DeviceAlreadyExistsException - if id is already assigned to a device.

java.io.IOException - if any other I/O error occurred.

java.lang.NullPointerException - if name, intf or config is null.

java.lang.IllegalArgumentException - if id is less than 0 and is not equal to UNSPECIFIED_ID.

java.lang.UnsupportedOperationException - if registering a new device is not supported - such as may be the case on a platform supporting only a closed device topology.

java.lang.SecurityException - if the caller does not have the required permission (see DeviceMgmtPermission.REGISTER).

java.lang.ClassCastException - if the device configuration type specified by config is not applicable to the device type specified by intf.

unregister

public static void unregister(int id)

Unregisters the device associated with the specified ID. Upon successful unregistration all RegistrationListener instances registered for the type of the device that has been unregistered are notified.

Some devices are registered by the underlying platform and cannot be unregistered.

Unregistration of a device has no side effect on its currently open Device instances. These Device instances especially retain the device ID that was assigned to them at the time they were open.

This method returns silently if the provided ID does not correspond to a registered device.

Parameters:

id - the ID of the device to unregister.

Throws:

java.lang.IllegalArgumentException - if id is less than 0 or if id corresponds to a device device registered by the platform.

java.lang.SecurityException - if the caller does not have the required permission (see DeviceMgmtPermission.UNREGISTER).

addRegistrationListener

public static <P extends Device<? super P>> void addRegistrationListener(RegistrationListener<P> listener,
                                                         java.lang.Class<P> intf)

Adds the specified registration listener to receive notification of registration and unregistration of devices of the specified type.

Type Parameters:

P - the type of the device to be listened for.

Parameters:

listener - the registration listener.

intf - the interface (sub-interface of Device) of the devices to be listened for.

Throws:

java.lang.NullPointerException - if listener or intf is null.

removeRegistrationListener

public static <P extends Device<? super P>> void removeRegistrationListener(RegistrationListener<P> listener,
                                                            java.lang.Class<P> intf)

Removes the specified registration listener so that it no longer receives notification of registration and unregistration of devices of the specified type.

Type Parameters:

P - the type of the device listened for.

Parameters:

listener - the registration listener.

intf - the interface (sub-interface of Device) of the devices listened for.

Throws:

java.lang.NullPointerException - if listener or intf is null.