jdk.dio.spi

Interface DeviceProvider<P extends Device<? super P>>

Type Parameters:

P - the device type the provider is defined for.

public interface DeviceProvider<P extends Device<? super P>>

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

DeviceProvider 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 device of a specific type (or configuration type) is looked up using a specific set of properties the DeviceManager looks up a suitable DeviceProvider using the Service-Provider Loading facility. It iterates over all the DeviceProvider classes registered as Service Providers until all the following steps succeed:

1. check that the DeviceProvider 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 DeviceProvider can open a Device 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.

A compliant implementation of the DeviceManager specification MUST catch undeclared unchecked exceptions, unexpected values (such as null) or mismatching value types that may be thrown or respectively returned at any of these steps and MUST report these conditions to the caller:

• as a UnsupportedDeviceTypeException when occurring at step 1;
• as a DeviceNotFoundException when occurring at step 2 or 3.

When iterating over DeviceProviders as per the iterative lookup procedure described above a compliant implementation of the DeviceManager specification MUST, upon failure to locate a device, ultimately report to the caller by throwing the most suitable exception that occurred during the iterative process according to the following priority order UnavailableDeviceException, InvalidDeviceConfigException, UnsupportedAccessModeException, DeviceNotFoundException, IOException, SecurityException.

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

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

META-INF/services/jdk.dio.spi.DeviceProvider

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

jdk.dio.samples.rtc.RealTimeClockProvider #Real-Time Clock sample

Since:

1.0

See Also:

DeviceManager.open(jdk.dio.DeviceConfig), DeviceManager.open(jdk.dio.DeviceConfig, int), DeviceManager.open(java.lang.Class, jdk.dio.DeviceConfig), DeviceManager.open(java.lang.Class, jdk.dio.DeviceConfig, int), DeviceManager.register

Method Summary

Methods

Modifier and Type	Method and Description
DeviceConfig<? super P>	deserialize(java.io.InputStream in) De-serializes a DeviceConfig object from the specified InputStream.
java.lang.Class<? extends DeviceConfig<? super P>>	getConfigType() Returns the type of the DeviceConfig this provider can handle.
java.lang.Class<P>	getType() Returns the type of the Device instance this provider opens.
boolean	matches(java.lang.String[] properties) Checks whether this DeviceProvider can open an instance of Device with the specified properties.
AbstractDevice<? super P>	open(DeviceConfig<? super P> config, java.lang.String[] properties, int mode) Opens a Device instance with the specified properties, configuration and access mode.

Method Detail

open

AbstractDevice<? super P> open(DeviceConfig<? super P> config,
                             java.lang.String[] properties,
                             int mode)
                                                         throws DeviceNotFoundException,
                                                                UnavailableDeviceException,
                                                                InvalidDeviceConfigException,
                                                                UnsupportedAccessModeException,
                                                                java.io.IOException

Opens a Device 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 Device instance the permission (subclass of DevicePermission) specific to that Device 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 device configuration or null if none is defined.

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

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

Returns:

a Device instance with the specified configuration.

Throws:

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

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.

InvalidDeviceConfigException - if the provided device 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 device.

getConfigType

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

Returns the type of the DeviceConfig this provider can handle.

Returns:

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

getType

java.lang.Class<P> getType()

Returns the type of the Device instance this provider opens.

Returns:

the type of the Device instance this provider opens.

matches

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

Checks whether this DeviceProvider can open an instance of Device with the specified properties.

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

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

Parameters:

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

Returns:

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

deserialize

DeviceConfig<? super P> deserialize(java.io.InputStream in)
                                                              throws java.io.IOException

De-serializes a DeviceConfig object from the specified InputStream. This method may be invoked by the DeviceManager to restore the state of a DeviceConfig object from a persistent store.

Parameters:

in - the stream to read from.

Returns:

the DeviceConfig object read from the stream.

Throws:

java.io.IOException - if an I/O error occurs or if the provided stream does not contain a representation of a DeviceConfig object of the type supported by this DeviceProvider.

Since:

1.1

See Also:

DeviceConfig.serialize(java.io.OutputStream)