com.oracle.deviceaccess.spi

Interface PeripheralProvider<P extends Peripheral<? super P>>

Type Parameters:

P - the peripheral type the provider is defined for.

public interface PeripheralProvider<P extends Peripheral<? super P>>

The PeripheralProvider interface provides methods to open Peripheral instances of a certain type and optionally with a specific configuration and a list of properties.

PeripheralProvider classes are Service Provider classes that must conform to the Service-Provider Loading facility requirements so that they can be located and instantiated on demand when they are deployed as part of libraries.

When a peripheral device of a specific type (or configuration type) is looked up using a specific set of properties the PeripheralManager looks up a suitable PeripheralProvider using the Service-Provider Loading facility. It iterates over all the PeripheralProvider classes registered as Service Providers until all the following steps succeed:

1. check that the PeripheralProvider is of the proper type by first invoking its getType method and/or is supporting the proper configuration type by invoking its getConfigType method
2. check if the PeripheralProvider can open a Peripheral instance with the specified properties by invoking the matches method,
3. invoke the open method with the specified configuration, properties and access mode; note that this step may fail with an exception.

Classes implementing the PeripheralProvider interface MUST have a zero-argument constructor so that they can be instantiated by the peripheral manager (as per the Service-Provider Loading facility specification requirements).

A library JAR file containing a PeripheralProvider implementation MUST contain a file named:

META-INF/services/com.oracle.deviceaccess.spi.PeripheralProvider

This file MUST contain the fully qualified name of the class implementing the PeripheralProvider interface. For example, for a JAR file containing the driver for the Real-Time Clock sample, this file may contain the following single line:

com.oracle.deviceaccess.samples.rtc.RealTimeClockProvider #Real-Time Clock sample

See Also:

PeripheralManager.open(com.oracle.deviceaccess.PeripheralConfig), PeripheralManager.open(com.oracle.deviceaccess.PeripheralConfig, int), PeripheralManager.open(java.lang.Class, com.oracle.deviceaccess.PeripheralConfig), PeripheralManager.open(java.lang.Class, com.oracle.deviceaccess.PeripheralConfig, int), PeripheralManager.register

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.Class<? extends PeripheralConfig<? super P>>	getConfigType() Returns the type of the PeripheralConfig this provider can handle.
java.lang.Class<P>	getType() Returns the type of the Peripheral instance this provider opens.
boolean	matches(java.lang.String[] properties) Checks whether this PeripheralProvider can open an instance of Peripheral with the specified properties.
AbstractPeripheral<? super P>	open(PeripheralConfig<? super P> config, java.lang.String[] properties, int mode) Opens a Peripheral instance with the specified properties, configuration and access mode.

Method Detail

open

AbstractPeripheral<? super P> open(PeripheralConfig<? super P> config,
                                 java.lang.String[] properties,
                                 int mode)
                                                                 throws PeripheralNotFoundException,
                                                                        UnavailablePeripheralException,
                                                                        PeripheralConfigInvalidException,
                                                                        UnsupportedAccessModeException,
                                                                        java.io.IOException

Opens a Peripheral instance with the specified properties, configuration and access mode.

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

Prior to opening the Peripheral instance the permission (subclass of PeripheralPermission) specific to that Peripheral instance must be checked, if any defined. For example, if this provider opens GPIOPin instances the GPIOPinPermission must be checked with a target name composed of the relevant hardware addressing information (the device name or device number and the pin number) and with the action GPIOPinPermission.OPEN.

Parameters:

config - the peripheral device configuration or null if none is defined.

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

properties - the peripheral device properties or null if none is defined.

Returns:

a Peripheral instance with the specified configuration.

Throws:

PeripheralNotFoundException - if the designated peripheral is not found, such as if the hardware addressing information or the properties do not match a supported peripheral.

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.

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

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.

getConfigType

java.lang.Class<? extends PeripheralConfig<? super P>> getConfigType()

Returns the type of the PeripheralConfig this provider can handle.

Returns:

the type of the PeripheralConfig this provider can handle; null if none is defined.

getType

java.lang.Class<P> getType()

Returns the type of the Peripheral instance this provider opens.

Returns:

the type of the Peripheral instance this provider opens.

matches

boolean matches(java.lang.String[] properties)

Checks whether this PeripheralProvider can open an instance of Peripheral with the specified properties.

The properties, if specified, are matched against the properties of the peripheral devices this PeripheralProvider can open instances of.

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

Parameters:

properties - the peripheral device properties or null to stand for any properties.

Returns:

true if this PeripheralProvider can open an instance of Peripheral with the specified properties; false otherwise.