public class PeripheralManager
extends java.lang.Object
PeripheralManager
class provides methods for opening and registering peripheral devices that can then be
handled as Peripheral
instances. A Peripheral
instance of a particular type can be opened using its
platform-specific numerical ID or name as well as its properties or using an adhoc configuration (in which case,
its hardware addressing information must be explicitly provided).
A Peripheral
instance may be identified by a numerical 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 peripheral ID typically corresponds to a registered configuration for a peripheral device. The
numerical ID of a peripheral device must be greater than or equal to 0
and must be unique. Yet the same
peripheral 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 peripheral device hardware resource.
Peripheral
instance opened with an adhoc configuration - that is: not through one of its registered
configurations - is not assigned a numerical ID nor a name. Its numerical ID and name are both undefined and set respectively
to UNDEFINED_ID
and null
.
Peripheral devices may be opened in either exclusive or shared mode. By default, peripheral devices
are opened in exclusive mode. Whether a peripheral device can be opened in shared mode depends on the
underlying peripheral device hardware as well as on the underlying device driver. It also depends on whether the
provided Peripheral
implementation is a dedicated, virtualized or shared
abstraction of the underlying peripheral device resource.
Peripheral
implementation (or driver)
may throw a PeripheralConfigInvalidException
if the peripheral device is already open and the requested adhoc configuration
is incompatible with the current configuration of the peripheral device.
Peripheral.tryLock(int)
and
Peripheral.unlock()
. Peripheral locks are held on a per Peripheral
instance basis. When the same peripheral device
is open twice in shared access mode by the same application, locking one of the Peripheral
instances will prevent
the other form being accessed/used.
Opening a Peripheral
instance of a specific type with a registered configuration is subject to permission
checks (see PeripheralMgmtPermission.OPEN
).
Peripheral
instance of a specific type with an ad-hoc configuration is subject to permission
checks specific for that type (for example see GPIOPinPermission.OPEN
). When a previously
registered custom Peripheral
is being opened this additional permission check should be implemented by the
PeripheralProvider.open
method.
PeripheralMgmtPermission.REGISTER
and PeripheralMgmtPermission.UNREGISTER
).Modifier and Type | Field and Description |
---|---|
static int |
EXCLUSIVE
Exclusive access mode.
|
static int |
SHARED
Shared access mode.
|
static int |
UNSPECIFIED_ID
Unspecified peripheral numerical ID - requesting the allocation of a free ID.
|
Constructor and Description |
---|
PeripheralManager() |
Modifier and Type | Method and Description |
---|---|
static <P extends Peripheral<? super P>> |
addRegistrationListener(RegistrationListener<P> listener,
java.lang.Class<P> intf)
Adds the specified registration listener to receive notification of registration and
unregistration of peripherals of the specified type.
|
static <P extends Peripheral<? super P>> |
list()
List all platform- and user-registered peripheral devices.
|
static <P extends Peripheral<? super P>> |
list(java.lang.Class<P> intf)
List all platform- and user-registered peripheral devices of the designated type.
|
static <P extends Peripheral<? super P>> |
open(java.lang.Class<P> intf,
PeripheralConfig<? super P> config)
Opens a
Peripheral instance of the specified type with the specified hardware addressing information and
configuration. |
static <P extends Peripheral<? super P>> |
open(java.lang.Class<P> intf,
PeripheralConfig<? super P> config,
int mode)
Opens a
Peripheral instance of the specified type with the specified hardware addressing information and
configuration. |
static <P extends Peripheral<? super P>> |
open(int id)
Looks up and opens a
Peripheral instance for the provided numerical ID. |
static <P extends Peripheral<? super P>> |
open(int id,
java.lang.Class<P> intf)
Looks up and opens a
Peripheral instance for the provided numerical ID and type. |
static <P extends Peripheral<? super P>> |
open(int id,
java.lang.Class<P> intf,
int mode)
Looks up and opens a
Peripheral instance for the provided numerical ID and type. |
static <P extends Peripheral<? super P>> |
open(int id,
int mode)
Looks up and opens a
Peripheral instance for the provided numerical ID. |
static <P extends Peripheral<? super P>> |
open(PeripheralConfig<? super P> config)
Opens a
Peripheral instance with the specified hardware addressing information and configuration. |
static <P extends Peripheral<? super P>> |
open(PeripheralConfig<? super P> config,
int mode)
Opens a
Peripheral instance with the specified hardware addressing information and
configuration. |
static <P extends Peripheral<? super P>> |
open(java.lang.String name,
java.lang.Class<P> intf,
int mode,
java.lang.String... properties)
Looks up and opens a
Peripheral instance for the specified name, type and/or properties. |
static <P extends Peripheral<? super P>> |
open(java.lang.String name,
java.lang.Class<P> intf,
java.lang.String... properties)
Looks up and opens a
Peripheral instance for the specified name, type and/or properties. |
static <P extends Peripheral<? super P>> |
register(int id,
java.lang.Class<P> intf,
PeripheralConfig<? super P> config,
java.lang.String name,
java.lang.String... properties)
Registers under the specified ID (and optionally name and properties) a new peripheral device supporting the
provided configuration.
|
static <P extends Peripheral<? super P>> |
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 peripherals of the specified type.
|
static void |
unregister(int id)
Unregisters the peripheral device associated with the specified ID.
|
public static final int EXCLUSIVE
public static final int SHARED
public static final int UNSPECIFIED_ID
public static <P extends Peripheral<? super P>> java.util.Iterator<PeripheralDescriptor<P>> list()
P
- the type of peripherals listed.public static <P extends Peripheral<? super P>> java.util.Iterator<PeripheralDescriptor<P>> list(java.lang.Class<P> intf) throws PeripheralTypeNotSupportedException
P
- the type of peripherals to list.intf
- the interface (sub-interface of Peripheral
) of the peripheral to be registered.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.java.lang.NullPointerException
- if intf
is null
.public static <P extends Peripheral<? super P>> P open(java.lang.Class<P> intf, PeripheralConfig<? super P> config) throws java.io.IOException, PeripheralConfigInvalidException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, UnavailablePeripheralException
Peripheral
instance of the specified type with the specified hardware addressing information and
configuration. An instance of the first
available matching Peripheral
is returned. If a matching Peripheral
is already open (therefore not available) the next
matching Peripheral
is considered.
The peripheral device is opened in exclusive access mode.
Note that the returned Peripheral
instance's ID and name are undefined.
A new instance is returned upon each call.P
- the type of the peripheral to open.intf
- the interface (sub-interface of Peripheral
) of the peripheral being looked up.config
- the peripheral configuration (which includes hardware addressing information as well as configuration
parameters).Peripheral
instance for the specified configuration.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.PeripheralConfigInvalidException
- if the provided peripheral configuration (as defined by the configuration parameters) is not valid/supported.PeripheralNotFoundException
- if the peripheral designated by the hardware addressing information is not found.UnavailablePeripheralException
- if the designated peripheral 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 peripheral (see PeripheralPermission.OPEN
).java.lang.NullPointerException
- if intf
or config
is null
.public static <P extends Peripheral<? super P>> P open(java.lang.Class<P> intf, PeripheralConfig<? super P> config, int mode) throws java.io.IOException, PeripheralConfigInvalidException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, UnavailablePeripheralException, UnsupportedAccessModeException
Peripheral
instance of the specified type with the specified hardware addressing information and
configuration. The type of the peripheral is inferred from the configuration type. An instance of the first
available matching Peripheral
is returned. If a matching Peripheral
is already open in a mode that is not
compatible with the requested mode the next matching Peripheral
is considered.
The peripheral device is
opened in the designated access mode. A peripheral 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 peripheral device may be
opened in exclusive mode if supported by the underlying driver and hardware and if it is not already opened.
Note that the returned Peripheral
instance's ID and name are undefined.
A new instance is returned upon each call.P
- the type of the peripheral to open.intf
- the interface (sub-interface of Peripheral
) of the peripheral being looked up.config
- the peripheral configuration (which includes hardware addressing information as well as configuration
parameters).mode
- the access mode, one of: EXCLUSIVE
or SHARED
.Peripheral
instance for the specified configuration.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.PeripheralConfigInvalidException
- if the provided peripheral configuration (as defined by the configuration parameters) is not valid/supported
or when opened in shared mode, if the provided peripheral configuration is incompatible with the currently open configuration of the peripheral.PeripheralNotFoundException
- if the peripheral designated by the hardware addressing information is not found.UnavailablePeripheralException
- if the designated peripheral 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 peripheral (see PeripheralPermission.OPEN
).java.lang.NullPointerException
- if intf
or config
is null
.public static <P extends Peripheral<? super P>> P open(int id) throws java.io.IOException, PeripheralNotFoundException, UnavailablePeripheralException
Peripheral
instance for the provided numerical ID.
The peripheral device is opened in exclusive access mode.
A new instance is returned upon each call.P
- the type of the peripheral to open.id
- the numerical peripheral id.Peripheral
instance for the given numerical ID.PeripheralNotFoundException
- if the designated peripheral is not found.UnavailablePeripheralException
- if the designated peripheral 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 peripheral (see PeripheralMgmtPermission.OPEN
).java.lang.IllegalArgumentException
- if id
is less than 0
.public static <P extends Peripheral<? super P>> P open(int id, java.lang.Class<P> intf) throws java.io.IOException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, UnavailablePeripheralException
Peripheral
instance for the provided numerical ID and type.
The peripheral device is opened in exclusive access mode.
A new instance is returned upon each call.P
- the type of the peripheral to open.id
- the numerical peripheral id.intf
- the interface (sub-interface of Peripheral
) of the peripheral being looked up.Peripheral
instance for the given numerical ID.PeripheralNotFoundException
- if the designated peripheral is not found.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.UnavailablePeripheralException
- if the designated peripheral 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 peripheral (see PeripheralMgmtPermission.OPEN
).java.lang.IllegalArgumentException
- if id
is less than 0
.java.lang.NullPointerException
- if intf
is null
.public static <P extends Peripheral<? super P>> P open(int id, java.lang.Class<P> intf, int mode) throws java.io.IOException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, UnavailablePeripheralException, UnsupportedAccessModeException
Peripheral
instance for the provided numerical ID and type.
The peripheral device is
opened in the designated access mode. A peripheral 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 peripheral 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.P
- the type of the peripheral to open.id
- the numerical peripheral id.intf
- the interface (sub-interface of Peripheral
) of the peripheral being looked up.mode
- the access mode, one of: EXCLUSIVE
or SHARED
.Peripheral
instance for the given numerical ID.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.PeripheralNotFoundException
- if the designated peripheral is not found.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.UnavailablePeripheralException
- if the designated peripheral 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 peripheral (see PeripheralMgmtPermission.OPEN
).java.lang.IllegalArgumentException
- if id
is less than 0
.java.lang.NullPointerException
- if intf
is null
.public static <P extends Peripheral<? super P>> P open(int id, int mode) throws java.io.IOException, PeripheralNotFoundException, UnavailablePeripheralException, UnsupportedAccessModeException
Peripheral
instance for the provided numerical ID.
The peripheral device is opened
in the designated access mode. A peripheral 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 peripheral 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.P
- the type of the peripheral to open.id
- the numerical peripheral id.mode
- the access mode, one of: EXCLUSIVE
or SHARED
.Peripheral
instance for the given numerical ID.PeripheralNotFoundException
- if the designated peripheral is not found.UnavailablePeripheralException
- if the designated peripheral 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 peripheral (see PeripheralMgmtPermission.OPEN
).java.lang.IllegalArgumentException
- if id
is less than 0
.public static <P extends Peripheral<? super P>> P open(PeripheralConfig<? super P> config) throws java.io.IOException, PeripheralConfigInvalidException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, UnavailablePeripheralException
Peripheral
instance with the specified hardware addressing information and configuration. The
type of the peripheral is inferred from the configuration type. An instance of the first
available matching Peripheral
. If a matching Peripheral
is already open (therefore not available) the next matching
Peripheral
is considered.
The peripheral device is opened in exclusive access mode.
Note that the returned Peripheral
instance's ID and name are undefined.
A new instance is returned upon each call.P
- the type of the peripheral to open.config
- the peripheral configuration (which includes hardware addressing information as well as configuration
parameters).Peripheral
instance for the specified configuration.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.PeripheralConfigInvalidException
- if the provided peripheral configuration (as defined by the configuration parameters) is not valid/supported.PeripheralNotFoundException
- if the peripheral designated by the hardware addressing information is not found.UnavailablePeripheralException
- if the designated peripheral 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 peripheral (see PeripheralPermission.OPEN
).java.lang.NullPointerException
- if config
is null
.public static <P extends Peripheral<? super P>> P open(PeripheralConfig<? super P> config, int mode) throws java.io.IOException, PeripheralConfigInvalidException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, UnavailablePeripheralException, UnsupportedAccessModeException
Peripheral
instance with the specified hardware addressing information and
configuration. The type of the peripheral is inferred from the configuration type. An instance of the first
available matching Peripheral
is returned. If a matching Peripheral
is already open in a mode that is not
compatible with the requested mode the next matching Peripheral
is considered.
The peripheral device is
opened in the designated access mode. A peripheral 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 peripheral device may be
opened in exclusive mode if supported by the underlying driver and hardware and if it is not already opened.
Note that the returned Peripheral
instance's ID and name are undefined.
A new instance is returned upon each call.config
- the peripheral configuration (which includes hardware addressing information as well as configuration
parameters).mode
- the access mode, one of: EXCLUSIVE
or SHARED
.Peripheral
instance for the specified configuration.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.PeripheralConfigInvalidException
- if the provided peripheral configuration (as defined by the configuration parameters) is not valid/supported
or when opened in shared mode, if the provided peripheral configuration is incompatible with the currently open configuration of the peripheral.PeripheralNotFoundException
- if the peripheral designated by the hardware addressing information is not found.UnavailablePeripheralException
- if the designated peripheral 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 peripheral (see PeripheralPermission.OPEN
).java.lang.NullPointerException
- if config
is null
.public static <P extends Peripheral<? super P>> P open(java.lang.String name, java.lang.Class<P> intf, int mode, java.lang.String... properties) throws java.io.IOException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, UnavailablePeripheralException, UnsupportedAccessModeException
Peripheral
instance for the specified name, type and/or properties. An instance of the first
available matching Peripheral
is returned. If a matching Peripheral
is already open in a mode that is not
compatible with the requested mode the next matching Peripheral
is considered.
The peripheral
device is opened in the designated access mode. A peripheral 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 peripheral 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.P
- the type of the peripheral to open.name
- the peripheral name; may be null
.intf
- the interface (sub-interface of Peripheral
) of the peripheral being looked up.mode
- the access mode, one of: EXCLUSIVE
or SHARED
.properties
- the list of required properties; may be null
.Peripheral
instance for the given name and required properties.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.PeripheralNotFoundException
- if the designated peripheral is not found.UnavailablePeripheralException
- if the designated peripheral 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 peripheral (see PeripheralMgmtPermission.OPEN
).java.lang.IllegalArgumentException
- if both name
and properties
are null
.java.lang.NullPointerException
- if intf
is null
.public static <P extends Peripheral<? super P>> P open(java.lang.String name, java.lang.Class<P> intf, java.lang.String... properties) throws java.io.IOException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, UnavailablePeripheralException
Peripheral
instance for the specified name, type and/or properties. An instance of the first
available matching Peripheral
is returned. If a matching Peripheral
is already open (therefore not available) the next matching
Peripheral
is considered.
The peripheral 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.P
- the type of the peripheral to open.name
- the peripheral name; may be null
.intf
- the interface (sub-interface of Peripheral
) of the peripheral being looked up.properties
- the list of required properties; may be null
.Peripheral
instance for the given name and required properties.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.PeripheralNotFoundException
- if the designated peripheral is not found.UnavailablePeripheralException
- if the designated peripheral 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 peripheral (see PeripheralMgmtPermission.OPEN
).java.lang.IllegalArgumentException
- if both name
and properties
are null
.java.lang.NullPointerException
- if intf
is null
.public static <P extends Peripheral<? super P>> int register(int id, java.lang.Class<P> intf, PeripheralConfig<? super P> config, java.lang.String name, java.lang.String... properties) throws java.io.IOException, PeripheralTypeNotSupportedException, PeripheralConfigInvalidException, PeripheralNotFoundException, PeripheralExistsException
RegistrationListener
instances registered for the type of the registered peripheral are notified.
An implementation of the PeripheralManager
must guarantee that an application registering a
peripheral is the first one to get notified (in the event it has
registered a RegistrationListener
for that type of peripherals).
The designated peripheral may be probed to check if the provided configuration is valid.
Prior to registering a new peripheral device of a certain type the PeripheralMgmtPermission
is checked with the action PeripheralMgmtPermission.REGISTER
.
GPIOPin
is to be registered the
PeripheralMgmtPermission
is checked with a target name composed of the requested peripheral name and ID
and with the action PeripheralMgmtPermission.REGISTER
.
The following is an example of how this method may be used to register a new UART with Modem control lines:
Note that this method cannot be used to register a peripheral device of a custom type. If an attempt is made to register a custom implementation ofPeripheralManager.register(10, // the peripheral device ID ModemUART.class, // the peripheral device type/interface new UARTConfig(0, 2400, UARTConfig.DATABITS_8, UARTConfig.PARITY_EVEN, UARTConfig.STOPBITS_1, UARTConfig.FLOWCONTROL_NONE), // the peripheral device configuration "MODEM", // the peripheral device name "com.foobar.modem.xxx=true", "com.foobar.modem.yyy=true" // the peripheral device capabilities );
PeripheralConfig
a PeripheralTypeNotSupportedException
will
be thrown.P
- the type of the peripheral to be registered.id
- the peripheral ID; if id
is equal to UNSPECIFIED_ID
a free ID will be allocated.intf
- the interface (sub-interface of Peripheral
) of the peripheral to be registered.config
- the peripheral configuration.name
- the name of the peripheral to be registered; may be null
.properties
- the list of properties/capabilities of the peripheral to be registered; may be null
.PeripheralConfigInvalidException
- if the provided peripheral configuration (as defined by the configuration parameters) is not valid/supported.PeripheralTypeNotSupportedException
- if the designated peripheral type is not supported.PeripheralNotFoundException
- if the peripheral designated by the hardware addressing information is not found.PeripheralExistsException
- if id
is already assigned to a peripheral device.java.io.IOException
- if any other I/O error occurred.java.lang.NullPointerException
- if 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 peripheral device is not supported - such as may be the case on a platform supporting
only a closed peripheral device topology.java.lang.SecurityException
- if the caller does not have the required permission (see PeripheralMgmtPermission.REGISTER
).public static void unregister(int id)
RegistrationListener
instances registered for the type of the peripheral that has been unregistered are notified.
Some peripheral devices are registered by the underlying platform and cannot be unregistered.
Unregistration of a peripheral device has no side effect on its currently open
Peripheral
instances. These Peripheral
instances especially retain the
peripheral 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 peripheral.id
- the ID of the peripheral device to unregister.java.lang.IllegalArgumentException
- if id
is less than 0
or if id
corresponds to a peripheral
device registered by the platform.java.lang.SecurityException
- if the caller does not have the required permission (see PeripheralMgmtPermission.UNREGISTER
).public static <P extends Peripheral<? super P>> void addRegistrationListener(RegistrationListener<P> listener, java.lang.Class<P> intf)
P
- the type of the peripheral to be listened for.listener
- the registration listener.intf
- the interface (sub-interface of Peripheral
) of the peripherals to be listened for.java.lang.NullPointerException
- if listener
or intf
is null
.public static <P extends Peripheral<? super P>> void removeRegistrationListener(RegistrationListener<P> listener, java.lang.Class<P> intf)
P
- the type of the peripheral listened for.listener
- the registration listener.intf
- the interface (sub-interface of Peripheral
) of the peripherals listened for.java.lang.NullPointerException
- if listener
or intf
is null
.Copyright © 2012, 2013, Oracle and/or its affiliates. All rights reserved.
Legal Notices