The Internet-of-Things (IoT) has a major impact in the IT industry. It requires backend systems to receive information from sensors, actuators, and appliances in various vertical markets such as Smart Home, eHealth, industrial automation, logistics, and automotive telematics. Application developers have to face the still increasing amount of communication protocols which are the major hurdle for interoperability.
The Device Abstraction Layer specification provides a unified interface for application developers to interact with sensor, devices, etc. connected to a gateway. Application developers don't have to deal with protocol specific details which simplifies the development of their applications.
The remote device control provides an opportunity to save energy, to
support better security, to save your time during daily tasks and more.
The devices can play different roles in their networks as event reporters,
controllers, etc. That dynamic behavior is well mappable to the dynamic
OSGi service registry. When a new device is available in the network,
there is a registration of a Device service. It realizes
basic set of management operations and provides a rich set of properties.
The applications can track the device status, read descriptive information
and follow the device relations. A set of functions can belong to a single
device. They represent the device operations and related properties in an
atomic way. The device functions can be found in the OSGi service
registry. The applications are allowed to get directly the required
functions if they don't need information about the device. For example,
light device is registered as Device service and there is
Function service to turn on and turn off the light. The
application can operate with the light control service without access to
the device service.
-
Device - represents the device in the OSGi service registry. It's described with a set of service properties and provides basic management operations.
-
Function - atomic functional entity like switch or sensor. The function can belong to a device. The function provides a set of properties and operations.
-
FunctionEvent - asynchronous event. It's posted through
EventAdminservice and notifies forFunctionproperty change. -
FunctionData - data structure which carries
Functionproperty value with extra metadata. -
PropertyMetadata and OperationMetadata - contain metadata about the
Functionproperties and operations.
The device category defined in the scope of the Device Access
service specification is called DAL. DEVICE_CATEGORY constant contains the category name.
The Device interface is dedicated to a common access to the devices provided by different protocols. It can be mapped one to one with the physical device, but can be mapped only with a given functional part of the device. Another mapping can be a device realized with a set of Device services and different relations between them. Device service can represent pure software unit. For example, it can simulate the real device work. There are basic management operations for removal and property access. New protocol devices can be supported with the registration of new Device services.
If the underlying protocol and the implementation allow, the Device services must be registered again after the OSGi framework restarts. The service properties must be restored, the supported functions must be registered and Device relations must be visible to the applications.
The OSGi service registry has the advantage of being easily accessible. The services can be filtered and accessed with their properties. The Device service has a rich set of such properties:
-
SERVICE_UID – Specifies the device unique identifier. It's a mandatory property. The value type is
java.lang.String. To simplify the unique identifier generation, the property value must follow the rule:UID ::= driver-name ':' device-id-
UID – device unique identifier
-
driver-name – the value of the
Device.SERVICE_DRIVERservice property -
device-id – device unique identifier in the scope of the driver
-
-
SERVICE_REFERENCE_UIDS – Specifies the reference device unique identifiers. It's an optional property. The value type is
java.lang.String[]. It can be used to represent different relationships between the devices. For example, The EnOcean controller can have a reference to the USB dongle. -
SERVICE_DRIVER – Specifies the device driver name. For example, EnOcean, Z-Wave, Bluetooth, etc. It's a mandatory property. The value type is
java.lang.String. -
SERVICE_NAME – Specifies the device name. It's an optional property. The value type is
java.lang.String. -
SERVICE_STATUS – Specifies the current device status. It's a mandatory property. The value type
java.lang.Integer. The possible values are:-
STATUS_REMOVED – Indicates that the device has been removed from the network. That status must be set as the last device status and after that the device service can be unregistered from the service registry. The status is available for stale device services too. All transitions to this status are described in Removed.
-
STATUS_OFFLINE – Indicates that the device is currently not available for operations. The end device is available in the network and can become online later. The controller is unplugged or there is no connection. All transitions to and from this status are described in detail in Offline.
-
STATUS_ONLINE – Indicates that the device is currently available for operations. The recent communication with the device has been passed through. All transitions to and from this status are described in detail in Online.
-
STATUS_PROCESSING – Indicates that the device is currently busy with an operation. All transitions to and from this status are described in detail in Processing.
-
STATUS_NOT_INITIALIZED – Indicates that the device is currently not initialized. Some protocols don't provide device information right after the device is connected. The device can be initialized later when it's awakened. All transitions to and from this status are described in detail in Not Initialized.
-
STATUS_NOT_CONFIGURED – Indicates that the device is currently not configured. The device can require additional actions to become completely connected to the network. All transitions to and from this status are described in detail in Not Configured.
-
-
SERVICE_STATUS_DETAIL – Provides the reason for the current device status. It's an optional property. The property value cannot be externally set or modified. The value type is
java.lang.Integer. There are two value categories. Positive values indicate the reason for the current status like STATUS_DETAIL_CONNECTING. Negative values indicate errors related to the current device status like STATUS_DETAIL_BROKEN. The list with defined status details is:-
STATUS_DETAIL_CONNECTING – The device is currently connecting to the network. The status detail indicates the reason with a positive value
1. The device status must be STATUS_PROCESSING. -
STATUS_DETAIL_INITIALIZING – The device is currently in process of initialization. The status detail indicates the reason with a positive value
2. The network controller initializing means that information about the network is currently read. The device status must be STATUS_PROCESSING. -
STATUS_DETAIL_REMOVING – The device is leaving the network. The status detail indicates the reason with positive value
3. The device status must be STATUS_PROCESSING. -
STATUS_DETAIL_FIRMWARE_UPDATING – The device firmware is updating. The status detail indicates the reason with positive value
4. The device status must be STATUS_PROCESSING. -
STATUS_DETAIL_CONFIGURATION_UNAPPLIED – The device configuration is not applied. The status detail indicates an error with a negative value
-1. The device status must be STATUS_NOT_CONFIGURED. -
STATUS_DETAIL_BROKEN – The device is broken. The status detail indicates an error with a negative value
-2. The device status must be STATUS_OFFLINE. -
STATUS_DETAIL_COMMUNICATION_ERROR – The device communication is problematic. The status detail indicates an error with a negative value
-3. The device status must be STATUS_ONLINE or STATUS_NOT_INITIALIZED. -
STATUS_DETAIL_DATA_INSUFFICIENT – The device doesn't provide enough information and cannot be determined. The status detail indicates an error with a negative value
-4. The device status must be STATUS_NOT_INITIALIZED. -
STATUS_DETAIL_INACCESSIBLE – The device is not accessible and further communication is not possible. The status detail indicates an error with a negative value
-5. The device status must be STATUS_OFFLINE. -
STATUS_DETAIL_CONFIGURATION_ERROR – The device cannot be configured. The status detail indicates an error with a negative value
-6. The device status must be STATUS_NOT_CONFIGURED. -
STATUS_DETAIL_DUTY_CYCLE – The device is in duty cycle. The status detail indicates an error with a negative value
-7. The device status must be STATUS_OFFLINE.
Custom status details are allowed, but they must not overlap the specified codes. To prevent possible collisions with further updates, custom codes must be greater than
100and less than-100. Table 141.1 contains the mapping of the status details to the statuses.Table 141.1 Status detail to status mapping.
Status Detail Status CONNECTINGPROCESSINGINITIALIZINGPROCESSINGREMOVINGPROCESSINGFIRMWARE_UPDATINGPROCESSINGCONFIGURATION_UNAPPLIEDNOT_CONFIGUREDBROKENOFFLINECOMMUNICATION_ERRORONLINE, NOT_INITIALIZEDDATA_INSUFFICIENTNOT_INITIALIZEDINACCESSIBLEOFFLINECONFIGURATION_ERRORNOT_CONFIGUREDDUTY_CYCLEOFFLINE -
-
SERVICE_HARDWARE_VENDOR – Specifies the device hardware vendor. It's an optional property. The value type is
java.lang.String. -
SERVICE_HARDWARE_VERSION – Specifies the device hardware version. It's an optional property. The value type is
java.lang.String. -
SERVICE_FIRMWARE_VENDOR – Specifies the device firmware vendor. It's an optional property. The value type is
java.lang.String. -
SERVICE_FIRMWARE_VERSION – Specifies the device firmware version. It's an optional property. The value type is
java.lang.String. -
SERVICE_TYPES – Specifies the device types. It's an optional property. The value type is
java.lang.String[]. -
SERVICE_MODEL – Specifies the device model. It's an optional property. The value type is
java.lang.String. -
SERVICE_SERIAL_NUMBER – Specifies the device serial number. It's an optional property. The value type is
java.lang.String.
The next code snippet prints all online devices.
ServiceReference[] deviceSRefs = context.getServiceReferences(
Device.class.getName(),
'(' + Device.SERVICE_STATUS + '=' + Device.STATUS_ONLINE + ')');
if (deviceSRefs != null) {
for (int i = 0; i < deviceSRefs.length; i++) {
printDevice(deviceSRefs[i]);
}
}Applications need to have an access to the device properties. For convenience, there are helper methods:
-
getServiceProperty(String) – Returns the current value of the specified property. The method will return the same value as
org.osgi.framework.ServiceReference.getProperty(String)for the service reference of this device. -
getServicePropertyKeys() – Returns an array with all device service property keys. The method will return the same value as
org.osgi.framework.ServiceReference.getPropertyKeys()for the service reference of this device.
The devices are registered as services in the OSGi service
registry. The service interface is
org.osgi.service.dal.Device. There is a registration order.
Device
services are registered last on start up. Before their registration,
there is Function service registration. The function registration
procedure is described in Function Registration.
The OSGi service registry provides an access to the services, but
there are no management operations like remove a given service. The
service provider is responsible to register and unregister own services.
That design doesn't provide an option to remove the device services. The
Device
interface fills this gap with remove()
method. It's a callback to the service provider to remove the device
from the network. The method can be optionally implemented.
java.lang.UnsupportedOperationException can be thrown if
the method is not supported. When the remove()
is called:
-
An appropriate command will be synchronously send to the device. As a result it can leave the network.
-
The device status will be set to STATUS_REMOVED.
-
The related device service will be unregistered from the OSGi service registry.
There is an unregistration order. The registration reverse order is used when the services are unregistered. Device services are unregistered first before Function services.
Device service can have a reference to other devices. That link can be used to represent different relationships between devices. For example, the EnOcean dongle can be used as USB Device and EnOcean network controller Device. The network controller device can have a reference to the physical USB device as it's depicted on the next diagram.
The related service property is SERVICE_REFERENCE_UIDS.
The device status reveals the device availability. It can demonstrate that device is currently not available for operations or that the device requires some additional configuration steps. The status can move between the different values according to the rules defined in this section. The status transitions are summarized in Table 141.2, visualized on Figure 141.3 and described in detail in the next sections. The initial device status is always STATUS_PROCESSING. When device info is processed, the device can go to another status. The last possible device status is STATUS_REMOVED. The status must be set when the device is removed from the network. After that status, the device service will be unregistered.
Table 141.2 Device Status Transitions
| From\To Status | PROCESSING |
ONLINE |
OFFLINE |
NOT INITIALIZED |
NOT CONFIGURED |
REMOVED |
|---|---|---|---|---|---|---|
PROCESSING |
- | Initial device data has been read. | Device is not accessible. | Initial device data has been partially read. | Device has a pending configuration. | Device has been removed. |
ONLINE |
Device data is processing. | - | Device is not accessible. | - | Device has a new pending configuration. | Device has been removed. |
OFFLINE |
Device data is processing. | Device data has been read. | - | - | Device has a pending configuration. | Device has been removed. |
NOT INITIALIZED |
Device data is processing. | - | Device is not accessible. | - | - | Device has been removed. |
NOT CONFIGURED |
Device data is processing. | Device pending configuration is satisfied. | Device is not accessible. | - | - | Device has been removed. |
REMOVED |
- | - | - | - | - | - |
The device can go to STATUS_REMOVED from any other status. Once reached, the device status cannot be updated any more. The device has been removed from the network and the device service is unregistered from the OSGi service registry. If there are stale references to the Device service, their status will be set to STATUS_REMOVED.
The common way for a given device to be removed is remove() method. When the method returns, the device status will be STATUS_REMOVED. It requires a synchronous execution of the operation.
The STATUS_OFFLINE indicates that the device is currently not available for operations. That status can be set, because of different reasons. The network controller has been unplugged, the connection to the device has been lost, etc. The device can move to this status from any other status with the exception of STATUS_REMOVED. Transitions to and from this status are:
-
From
STATUS_OFFLINEtoSTATUS_REMOVED– The device has been removed. The status can be set as a result of remove() method call. -
From
STATUS_OFFLINEtoSTATUS_PROCESSING– Device data is processing. -
From
STATUS_OFFLINEtoSTATUS_NOT_CONFIGURED– The device has a pending configuration. -
From
STATUS_OFFLINEtoSTATUS_ONLINE– Device data has been read and the device is currently available for operations. -
From
STATUS_OFFLINEtoSTATUS_NOT_INITIALIZED– That transition is not possible, because the status have to go throughSTATUS_PROCESSING. If the processing is unsuccessful,STATUS_NOT_INITIALIZEDwill be set. -
To
STATUS_OFFLINEfromSTATUS_REMOVED– That transition is not possible. If the device has been removed, the service will be unregistered from the service registry. -
To
STATUS_OFFLINEfromSTATUS_PROCESSING– The device is not accessible any more while device data is processing. -
To
STATUS_OFFLINEfromSTATUS_NOT_CONFIGURED– The device with pending configuration is not accessible any more. -
To
STATUS_OFFLINEfromSTATUS_ONLINE– The online device is not accessible any more. -
To
STATUS_OFFLINEfromSTATUS_NOT_INITIALIZED– The not initialized device is not accessible any more.
The possible transitions are summarized on Figure 141.4.
The STATUS_ONLINE indicates that the device is currently available for operations. The online devices are initialized and ready for use. Transitions to and from this status are:
-
From
STATUS_ONLINEtoSTATUS_REMOVED– The device has been removed. The status can be set as a result of remove() method call. -
From
STATUS_ONLINEtoSTATUS_PROCESSING– The device data is processing. -
From
STATUS_ONLINEtoSTATUS_NOT_CONFIGURED– The device has a pending configuration. -
From
STATUS_ONLINEtoSTATUS_OFFLINE– The online device is not accessible any more. -
From
STATUS_ONLINEtoSTATUS_NOT_INITIALIZED– That transition is not possible. Online devices are initialized. -
To
STATUS_ONLINEfromSTATUS_REMOVED– That transition is not possible. If the device has been removed, the service will be unregistered from the service registry. -
To
STATUS_ONLINEfromSTATUS_PROCESSING– Initial device data has been read. The device is available for operations. -
To
STATUS_ONLINEfromSTATUS_NOT_CONFIGURED– The device pending configuration is satisfied. -
To
STATUS_ONLINEfromSTATUS_OFFLINE– The device is accessible for operations. -
To
STATUS_ONLINEfromSTATUS_NOT_INITIALIZED– That transition is not possible. The device data has to be processed and then the device can become online. Intermediate statusSTATUS_PROCESSINGwill be used.
The possible transitions are summarized on Figure 141.5.
The status indicates that the device is currently busy with an
operation. It can be time consuming operation and can result to any
other status. The operation processing can be reached by any other
status except STATUS_REMOVED. For example, offline device requires some
data processing to become online. It will apply this status sequence:
STATUS_OFFLINE, STATUS_PROCESSING and
STATUS_ONLINE. Transitions to and from this status are:
-
From
STATUS_PROCESSINGtoSTATUS_REMOVED– The device has been removed. The status can be set as a result of remove() method call. -
From
STATUS_PROCESSINGtoSTATUS_ONLINE– Initial device data has been read. The device is available for operations. -
From
STATUS_PROCESSINGtoSTATUS_NOT_CONFIGURED– The device has a pending configuration. -
From
STATUS_PROCESSINGtoSTATUS_OFFLINE– The device is not accessible any more. -
From
STATUS_PROCESSINGtoSTATUS_NOT_INITIALIZED– The device initial data is partially read. -
To
STATUS_PROCESSINGfromSTATUS_REMOVED– That transition is not possible. If the device has been removed, the service will be unregistered from the service registry. -
To
STATUS_PROCESSINGfromSTATUS_ONLINE– The device is busy with an operation. -
To
STATUS_PROCESSINGfromSTATUS_NOT_CONFIGURED– The device pending configuration is satisfied and the device is busy with an operation. -
To
STATUS_PROCESSINGfromSTATUS_OFFLINE– The device is busy with an operation. -
To
STATUS_PROCESSINGfromSTATUS_NOT_INITIALIZED– The device initial data is processing.
The possible transitions are summarized on Figure 141.6.
The status indicates that the device is currently not initialized. Some protocols don't provide device information right after the device is connected. The device can be initialized later when it's awakened. The not initialized device requires some data processing to become online. STATUS_PROCESSING is used as an intermediate status. Transitions to and from this status are:
-
From
STATUS_NOT_INITIALIZEDtoSTATUS_REMOVED– The device has been removed. The status can be set as a result of remove() method call. -
From
STATUS_NOT_INITIALIZEDtoSTATUS_PROCESSING– The device data is processing. -
From
STATUS_NOT_INITIALIZEDtoSTATUS_NOT_CONFIGURED– That transition is not possible. Device requires some data processing. -
From
STATUS_NOT_INITIALIZEDtoSTATUS_OFFLINE– The device is not accessible any more. -
From
STATUS_NOT_INITIALIZEDtoSTATUS_ONLINE– That transition is not possible. Device requires some data processing to become online. -
To
STATUS_NOT_INITIALIZEDfromSTATUS_REMOVED– That transition is not possible. If the device has been removed, the service will be unregistered from the service registry. -
To
STATUS_NOT_INITIALIZEDfromSTATUS_PROCESSING– Device data is partially read. -
To
STATUS_NOT_INITIALIZEDfromSTATUS_NOT_CONFIGURED– That transition is not possible. When device pending configuration is satisfied, the device requires additional data processing. -
To
STATUS_NOT_INITIALIZEDfromSTATUS_OFFLINE– That transition is not possible. Device requires some data processing and then can become not initialized. -
To
STATUS_NOT_INITIALIZEDfromSTATUS_ONLINE– That transition is not possible. The online device is initialized.
The possible transitions are summarized on Figure 141.7.
Indicates that the device is currently not configured. The device can require additional actions to become completely connected to the network. For example, a given device button has to be pushed. That status doesn't have transitions with STATUS_NOT_INITIALIZED, because some data processing is required. Transitions to and from this status are:
-
From
STATUS_NOT_CONFIGUREDtoSTATUS_REMOVED– The device has been removed. The status can be set as a result of remove() method call. -
From
STATUS_NOT_CONFIGUREDtoSTATUS_PROCESSING– The device pending configuration is satisfied and some additional data processing is required. -
From
STATUS_NOT_CONFIGUREDtoSTATUS_ONLINE– The device pending configuration is satisfied. -
From
STATUS_NOT_CONFIGUREDtoSTATUS_OFFLINE– The device is not accessible any more. -
From
STATUS_NOT_CONFIGUREDtoSTATUS_NOT_INITIALIZED– That transition is not possible. When device pending configuration is satisfied, the device requires additional data processing. -
To
STATUS_NOT_CONFIGUREDfromSTATUS_REMOVED– That transition is not possible. If the device has been removed, the service will be unregistered from the service registry. -
To
STATUS_NOT_CONFIGUREDfromSTATUS_PROCESSING– Initial device data has been read but there is a pending configuration. -
To
STATUS_NOT_CONFIGUREDfromSTATUS_ONLINE– The device has a pending configuration. -
To
STATUS_NOT_CONFIGUREDfromSTATUS_OFFLINE– The device is going to be online, but has a pending configuration. -
To
STATUS_NOT_CONFIGUREDfromSTATUS_NOT_INITIALIZED– That transition is not possible. Device requires some data processing.
The possible transitions are summarized on Figure 141.8.
The user applications have full control over the device with the Function services. Synchronous or asynchronous operations can trigger different actions. For example, turn on or off the light, can change the room temperature, send an user notification, etc. The action result can be reported immediately or later in case of concurrent execution. As a result, a Function property can be updated. The property is the device value container. It can provide, sensor information, meter data, the switch current position, etc. Different property access types allow the applications to read, write or receive events.
The OSGi service registry has the advantage of being easily accessible. The services can be filtered and accessed with their properties. The function service has a rich set of such properties:
-
SERVICE_UID – mandatory service property. The property value is the function unique identifier. The value type is
java.lang.String. To simplify the unique identifier generation, the property value must follow the rule:function UID ::= device-id ':' function-id-
function UID – function unique identifier
-
device-id – the value of the Device.SERVICE_UID Device service property
-
function-id – function identifier in the scope of the device
If the function is not bound to a device, the function unique identifier can be device independent.
-
-
SERVICE_TYPE – optional service property. The service property value contains the function type. For example, the sensor function can have different types like temperature, pressure, etc. The value type is
java.lang.String.Organizations that want to use function types that do not clash with OSGi Working Group defined types should prefix their types in own namespace.
-
SERVICE_VERSION – optional service property. The service property value contains the function version. That version can point to specific implementation version and vary in the different vendor implementations. The value type is
java.lang.String. -
SERVICE_DEVICE_UID – optional service property. The property value is the device identifier. The function belongs to this device. The value type is
java.lang.String. -
SERVICE_REFERENCE_UIDS – optional service property. The service property value contains the reference function unique identifiers. The value type is
java.lang.String[]. It can be used to represent different relationships between the functions. -
SERVICE_DESCRIPTION – optional service property. The property value is the function description. The value type is
java.lang.String. -
SERVICE_OPERATION_NAMES – optional service property. The property is missing when there are no function operations and property must be set when there are function operations. The property value is the function operation names. The value type is
java.lang.String[]. It's not possible to exist two or more function operations with the same name i.e. the operation overloading is not allowed. -
SERVICE_PROPERTY_NAMES – optional service property. The property is missing when there are no function properties and property must be set when there are function properties. The property value is the function property names. The value type is
java.lang.String[]. It's not possible to exist two or more function properties with the same name.
On start up, the Function services are registered
before the Device service. It's possible that SERVICE_DEVICE_UID points to missing service at the moment of the
registration. The reverse order is used when the services are
unregistered. Device service is unregistered before the Function
services. The device registration procedure is available in Device Registration.
The Function service should be registered only under the
function class hierarchy. Other classes can be used if there are no
ambiguous representations. For example, an ambiguous representation can
be a function registered under two independent function classes like
BinarySwitch and Meter. In this example, both
functions support the same property “state” with different meaning.
getPropertyMetadata(String propertyName) method cannot
determinate which property is requested. It can be
BinarySwitch “state” or Meter “state”.
To simplify the generic function discovery, the
Function interface must be used for the service
registration. In this way, the generic applications can easily find all
services, which are functions in the service registry. Because of this
rule, this registration is not allowed:
context.registerService(MeterV1.class.getName(), this, regProps);If the implementation would like to mark that there is a function, but no specific function interface exists, the registration can be:
context.registerService(Function.class.getName(), this, regProps);Note that such functions usually don't have operations and properties.
Function is built by a set of properties and operations. The function can have unique identifier, type, version, description, link to the Device service and information about the referenced functions. Function interface must be the base interface for all functions. If the device provider defines custom functions, all of them must extend Function interface. It provides a common access to the operations and properties metadata.
There are some general type rules, which unify the access to the function data. They make easier the transfer over different protocols. All properties and operation arguments must use one of:
-
Java primitive type or corresponding reference type.
-
Numerical type i.e. the type which extends
java.lang.Number. The numerical type must follow these conventions:-
The type must provide a public static method called
valueOfthat returns an instance of the given type and takes a singleStringargument or a public constructor which takes a singleStringargument.
-
The
Stringargument from the previous bullet can be provided bytoString()method of the instance.
-
-
java.lang.String -
Java Bean, but its properties must use those rules. Java Bean is defined in [1] JavaBeans Spec.
-
java.util.Mapinstance. The map keys can bejava.lang.String. The values of a single type follow these rules. -
Array of defined types.
In order to provide common behavior, all functions must follow a set of common rules related to the implementation of their setters, getters, operations and events:
-
The setter method must be executed synchronously. If the underlying protocol can return response to the setter call, it must be awaited. It simplifies the property value modification and doesn't require asynchronous callback.
-
The operation method must be executed synchronously. If the underlying protocol can return an operation confirmation or response, it must be awaited. It simplifies the operation execution and doesn't require asynchronous callback.
-
The getter must return the last know cached property value. The device implementation is responsible to keep that value up to date. It'll speed up the applications when the function property values are collected. The same cached value can be shared between a few requests instead of a few calls to the real device.
-
The function operations, getters and setters must not override
java.lang.Objectand this interface methods. For example:-
hashCode()– it'sjava.lang.Objectmethod and invalid function operation; -
wait()– it'sjava.lang.Objectmethod and invalid function operation; -
getClass()– it'sjava.lang.Objectmethod and invalid function getter; -
getPropertyMetadata(String propertyName)– it'sorg.osgi.service.dal.Functionmethod and invalid function getter.
-
Function operations are the main callable units. They can perform a specific task on the device like turn on or turn off. They can be used by the applications to control the device. Operation names are available as a value of the service property SERVICE_OPERATION_NAMES. The operations are identified by their names. It's not possible to exist two operations with the same name i.e. overloaded operations are not allowed. They cannot override the property accessor methods. The operations are regular java methods. That implies that they have zero or more arguments and zero or one return value. The operation arguments and return value must follow the general type rules.
The operations can be optionally described with metadata. Metadata is accessible with getOperationMetadata(String) method. The result provides metadata about the operation, operation arguments and result value. Operation arguments and result value are using the same metadata as the function properties. The full details are defined in the next section.
Function properties are class fields. Their values can be read with getter methods and can be set with setter methods. The property names are available as a value of the service property SERVICE_PROPERTY_NAMES. The properties are identified by their names. It's not possible to exist two properties with the same name.
The function properties must be integrated according to these rules:
-
Getter methods must be available for all properties with ACCESS_READABLE access.
-
Getter method must return a subclass of FunctionData.
-
Setter methods must be available for all properties with ACCESS_WRITABLE access.
-
Setter methods can be any combination of:
-
Setter method which accepts a subclass of FunctionData.
-
Setter method which accepts the values used by the FunctionData subclass, if there are no equal types.
It's possible to have only one or both of them. Examples:
-
There is
MyFunctionDatabean withBigDecimalvalue for adataproperty. Valid setters aresetData(MyFunctionData data)andsetData(BigDecimal data). -
There is
MySecondFunctionDatabean withBigDecimalprefix andBigDecimalsuffix for adataproperty. The prefix and suffix are using equal types and we cannot have a setter with the values used byMySecondFunctionData. The only one possible setter issetData(MySecondFunctionData data).
-
-
No methods are required for properties with ACCESS_EVENTABLE access.
The accessor method names must be defined according to [1] JavaBeans Spec.
The properties can be optionally described with a set of metadata properties. The property values can be collected with getPropertyMetadata(String) method. The method result is PropertyMetadata with:
-
Minimum value – available through getMinValue(String). The minimum value can be different for the different units.
-
Maximum value – available through getMaxValue(String). The maximum value can be different for the different units.
-
Enumeration of values – available through getEnumValues(String). The array of the possible values is sorted in increasing order according to the given unit.
-
Step – available through getStep(String). The difference between two values in series. For example, if the range is
[0, 100], the step can be10. -
Property access – available as a value in getMetadata(String) result map. It's a bitmap of
java.lang.Integertype and doesn't depend on the given unit. The access is available only for the function properties and it's missing for the operation arguments and result metadata. The bitmap can be any combination of:-
ACCESS_READABLE – Marks the property as a readable. Function must provide a getter method for this property according to [1] JavaBeans Spec. Function operations must not be overridden by this getter method.
-
ACCESS_WRITABLE – Marks the property as writable. Function must provide a setter method for this property according to [1] JavaBeans Spec. Function operations must not be overridden by this setter method.
-
ACCESS_EVENTABLE – Marks the property as eventable. Function must not provide special methods because of this access type.
FunctionEventis sent on property change. Note that the event can be sent when there is no value change.
-
-
Units - available as a value in getMetadata(String) result map. They can be requested with key UNITS. The value contains the property supported units. The property value type is
java.lang.String[]. The array first element at index0represents the default unit. Each unit must follow those rules:-
The International System of Units must be used where it's applicable. For example, kg for kilogram and km for kilometer.
-
If the unit name matches to a Unicode symbol name, the Unicode symbol must be used. For example, the degree unit matches to the Unicode degree sign (
°). -
If the unit name doesn't match to a Unicode symbol, the unit symbol must be built by Unicode Basic Latin block of characters, superscript and subscript characters. For example, watt per square meter steradian is built by
W/(m² sr).
If those rules cannot be applied to the unit symbol, custom rules are allowed.
A set of predefined unit symbols are available in
SIUnitsinterface. -
-
Description – available as a value in getMetadata(String) result map. It can be requested with key DESCRIPTION. The property value type is
java.lang.Stringand specifies a user readable description. It doesn't depend on the given unit. -
Vendor custom properties – available as a value in getMetadata(String) result map and can depend on the given unit. Organizations that want to use custom keys that do not clash with OSGi Working Group defined should prefix their keys in own namespace.
The eventable function properties can trigger a new event on each property value modification. It doesn't require a modification of the value. For example, the motion sensor can send a few events with no property value change when motion is detected and continued to be detected. The event must use FunctionEvent class. The event properties are:
-
FUNCTION_UID – the event source function unique identifier.
-
PROPERTY_NAME – the property name.
-
PROPERTY_VALUE – the property value.
For example, there is function with an eventable
boolean property called “state”. When “state” value is changed to
false, function implementation can post:
FunctionEvent {
dal.function.UID=acme.function
dal.function.property.name=”state”
dal.function.property.value=ACMEFuntionData(java.lang.Boolean.FALSE...)
}The DevicePermission controls the bundle's authority to perform specific privileged administrative operations on the devices. There is only one action for this permission REMOVE to protect remove() method.
The name of the permission is a filter based. For more details about filter based permissions, see OSGi Core Specification, Filter Based Permissions. The filter provides an access to all device service properties. Filter attribute names are processed in a case sensitive manner. For example, the operator can give a bundle the permission to only manage devices of vendor "acme":
org.osgi.service.dal.DevicePermission("dal.device.hardware.vendor=acme", "remove")The permission action allows the operator to assign only the necessary permissions to the bundle. For example, the management bundle can have permission to remove all registered devices:
org.osgi.service.dal.DevicePermission("*", "remove")The code that needs to check the device permission must always use the constructor that takes the device as a parameter Device with a single action. For example, the implementation of remove() method must check that the caller has an access to the operation:
public class DeviceImpl implements Device {
...
public void remove() {
securityManager.checkPermission(
new DevicePermission(this, DevicePermission.REMOVE));
}
...
}The Device implementation must check the caller for
the appropriate DevicePermission before execution of the
remove operation. Once the DevicePermission is checked
against the caller the implementation will proceed with the actual
operation. The operation can require a number of other permissions to
complete. The implementation must isolate the caller from such
permission checks by use of proper privileged blocks.
DevicePermission check will keep the
Device implementation in the call stack. This requires the
implementation to have this permission to perform the operation. The
security policy should be aware of this and should grant the correct
permissions. Note that the DevicePermission is a filter
based permission, see OSGi Core Specification, Filter Based Permissions.
It provides flexibility and fine control based on the
Device service properties.
Device Abstraction Layer 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.dal; version="[1.0,2.0)"
Example import for providers implementing the API in this package:
Import-Package: org.osgi.service.dal; version="[1.0,1.1)"
-
Device- Represents the device in the OSGi service registry. -
DeviceException-DeviceExceptionis a specialIOException, which is thrown to indicate that there is a device operation fail. -
DevicePermission- A bundle's authority to perform specific privileged administrative operations on the devices. -
Function- Function service provides specific device operations and properties. -
FunctionData- AbstractFunctiondata wrapper. -
FunctionEvent- Asynchronous event, which marks a function property value modification. -
OperationMetadata- Contains metadata about function operation. -
PropertyMetadata- Contains metadata about a function property, a function operation parameter or a function operation return value. -
SIUnits- Contains most of the International System of Units unit symbols.
Represents the device in the OSGi service registry. Note that Device
services are registered last. Before their registration, there is
Function services registration. The reverse order is used when the
services are unregistered. Device services are unregistered first
before Function services.
Constant for the value of the Constants.DEVICE_CATEGORY service property. That category is used by all device services.
The service property value contains the device description. It's an
optional property. The value type is java.lang.String.
The service property value contains the device driver name. For example,
EnOcean, Z-Wave, Bluetooth, etc. It's a mandatory property. The value
type is java.lang.String.
The service property value contains the device firmware vendor. It's an
optional property. The value type is java.lang.String.
The service property value contains the device firmware version. It's an
optional property. The value type is java.lang.String.
The service property value contains the device hardware vendor. It's an
optional property. The value type is java.lang.String.
The service property value contains the device hardware version. It's an
optional property. The value type is java.lang.String.
The service property value contains the device model. It's an optional
property. The value type is java.lang.String.
The service property value contains the device name. It's an optional
property. The value type is java.lang.String.
The service property value contains the reference device unique
identifiers. It's an optional property. The value type is
java.lang.String[]. It can be used to represent different
relationships between the devices. For example, the EnOcean controller
can have a reference to the USB dongle.
The service property value contains the device serial number. It's an
optional property. The value type is java.lang.String.
The service property value contains the device status. It's a mandatory
property. The value type is java.lang.Integer. The possible
values are:
The service property value contains the device status detail. It holds
the reason for the current device status. It's an optional property. The
value type is java.lang.Integer. There are two value categories:
-
positive values - those values contain details related to the current status. Examples: STATUS_DETAIL_CONNECTING and STATUS_DETAIL_INITIALIZING.
-
negative values - those values contain errors related to the current status. Examples: STATUS_DETAIL_CONFIGURATION_UNAPPLIED, STATUS_DETAIL_BROKEN and STATUS_DETAIL_COMMUNICATION_ERROR.
The service property value contains the device types like DVD, TV, etc.
It's an optional property. The value type is java.lang.String[].
The service property value contains the device unique identifier. It's a
mandatory property. The value type is java.lang.String. To
simplify the unique identifier generation, the property value must follow
the rule:
UID ::= driver-name ':' device-id
UID - device unique identifier
driver-name - the value of the SERVICE_DRIVER service property
device-id - device unique identifier in the scope of the driver
Device status detail indicates that the device is broken. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_OFFLINE.
Device status detail indicates that the device communication is problematic. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_ONLINE or STATUS_NOT_INITIALIZED.
Device status detail indicates that the device cannot be configured. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_NOT_CONFIGURED.
Device status detail indicates that the device configuration is not applied. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_NOT_CONFIGURED.
Device status detail indicates that the device is currently connecting to the network. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_PROCESSING.
Device status detail indicates that the device doesn't provide enough information and cannot be determined. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_NOT_INITIALIZED.
Device status detail indicates that the device is in duty cycle. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_OFFLINE.
Device status detail indicates that the device firmware is updating. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_PROCESSING.
Device status detail indicates that the device is not accessible and further communication is not possible. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_OFFLINE.
Device status detail indicates that the device is currently in process of initialization. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_PROCESSING.
Device status detail indicates that the device is leaving the network. It can be used as a value of SERVICE_STATUS_DETAIL service property. The device status must be STATUS_PROCESSING.
Device status indicates that the device is currently not configured. The device can require additional actions to become completely connected to the network. It can be used as a value of SERVICE_STATUS service property.
Device status indicates that the device is currently not initialized. Some protocols don't provide device information right after the device is connected. The device can be initialized later when it's awakened. It can be used as a value of SERVICE_STATUS service property.
Device status indicates that the device is currently not available for operations. It can be used as a value of SERVICE_STATUS service property.
Device status indicates that the device is currently available for operations. The recent communication with the device has been passed through. It can be used as a value of SERVICE_STATUS service property.
Device status indicates that the device is currently busy with an operation. It can be used as a value of SERVICE_STATUS service property.
Device status indicates that the device has been removed from the network. That status must be set as the last device status. After that the device service can be unregistered from the service registry. It can be used as a value of SERVICE_STATUS service property.
The property key.
Returns the current value of the specified property. The method will
return the same value as ServiceReference.getProperty(String) for
the service reference of this device.
This method must continue to return property values after the device service has been unregistered.
The property value or null if the property key cannot be
mapped to a value.
Returns an array with all device service property keys. The method will
return the same value as ServiceReference.getPropertyKeys() for
the service reference of this device. The result cannot be null.
An array with all device service property keys, cannot be
null.
Removes this device.
The method must synchronously:
-
Remove the device from the device network.
-
Set the device status to STATUS_REMOVED.
-
Unregister the device service from the OSGi service registry.
The caller should release the device service after successful execution, because the device will not be operational.
DeviceException– If an operation error is available.
UnsupportedOperationException– If the operation is not supported
over this device.
SecurityException– If the caller does not have the appropriate
DevicePermission(this device,
DevicePermission.REMOVE
) and the Java Runtime
Environment supports permissions.
IllegalStateException– If this device service object has already
been unregistered.
DeviceException is a special IOException, which is thrown to
indicate that there is a device operation fail. The error reason can be
located with getCode() method. The cause is available with
getCause().
An exception code indicates that there is an error in the communication.
An exception code indicates that the requested value is currently not available.
An exception code indicates that the device is not initialized. The device status is Device.STATUS_NOT_INITIALIZED or Device.STATUS_PROCESSING.
An exception code indicates that there is expired timeout without any processing.
An exception code indicates that the error is unknown.
Construct a new device exception with null message. The cause is
not initialized and the exception code is set to UNKNOWN.
The exception message.
Constructs a new device exception with the given message. The cause is not initialized and the exception code is set to UNKNOWN.
The exception message.
The exception cause.
Constructs a new device exception with the given message and cause. The exception code is set to UNKNOWN.
The exception message.
The exception cause.
The exception code.
Constructs a new device exception with the given message, cause and code.
Returns the exception code. It indicates the reason for this exception. The code can be:
-
custom code
Zero and positive values are reserved for this definition and further extensions of the device exception codes. Custom codes can be used only as negative values to prevent potential collisions.
An exception code.
A bundle's authority to perform specific privileged administrative operations on the devices. The method Device.remove() is protected with REMOVE permission action.
The name of the permission is a filter based. See OSGi Core Specification, Filter Based Permissions. The filter gives an access to all device service properties. Filter attribute names are processed in a case sensitive manner.
A filter expression that can use any device service property. The filter attribute names are processed in a case insensitive manner. A special value of "*" can be used to match all devices.
REMOVE action.
Creates a new DevicePermission with the given filter and actions.
The constructor must only be used to create a permission that is going to
be checked.
A filter example: (dal.device.hardware.vendor=acme)
An action: remove
IllegalArgumentException– If the filter syntax is not correct or
invalid action is specified.
NullPointerException– If the filter or action is null.
The device that needs to be checked for a permission.
REMOVE action.
Creates a new DevicePermission with the given device and actions.
The permission must be used for the security checks like:
securityManager.checkPermission(new DevicePermission(this, "remove"))
. The permissions constructed by this constructor must not be added to
the DevicePermission permission collections.
IllegalArgumentException– If an invalid action is specified.
NullPointerException– If the device or action is null.
The object being compared for equality with this object.
Two DevicePermission instances are equal if:
-
Represents the same filter and action.
-
Represents the same device (in respect to device unique identifier) and action.
true if two permissions are equal, false
otherwise.
Returns the canonical string representation of REMOVE action.
The canonical string representation of the actions.
Returns the hash code value for this object.
Hash code value for this object.
The permission to be implied. It must be constructed by DevicePermission(Device, String).
Determines if the specified permission is implied by this object. The
method will return false if the specified permission was not
constructed by DevicePermission(Device, String).
Returns true if the specified permission is a
DevicePermission and this permission filter matches the specified
permission device properties.
true if the specified permission is implied by this
permission, false otherwise.
IllegalArgumentException– If the specified permission is not
constructed by DevicePermission(Device, String).
Function service provides specific device operations and properties. Each function service must implement this interface. In additional to this interface, the implementation can provide own:
-
properties;
-
operations.
The function service is registered in the service registry with these service properties:
-
SERVICE_UID - mandatory service property. The property value contains the function unique identifier.
-
SERVICE_DEVICE_UID - optional service property. The property value is the Functional Device identifiers. The function belongs to those devices.
-
SERVICE_REFERENCE_UIDS - optional service property. The property value contains the reference function unique identifiers.
-
SERVICE_TYPE - mandatory service property. The property value is the function type.
-
SERVICE_VERSION - optional service property. The property value contains the function version.
-
SERVICE_DESCRIPTION - optional service property. The property value is the function description.
-
SERVICE_OPERATION_NAMES - optional service property. The property is missing when there are no function operations and property must be set when there are function operations. The property value is the function operation names.
-
SERVICE_PROPERTY_NAMES - optional service property. The property is missing when there are no function properties and property must be set when there are function properties. The property value is the function property names.
On start up, the Function services are registered before the
Device services. It's possible that SERVICE_DEVICE_UID point
to missing services at the moment of the registration. The reverse order is
used when the services are unregistered. Function services are
unregistered last after Device services.
The Function service should be registered only under the function
class hierarchy. Other classes can be used if there are no ambiguous
representations. For example, an ambiguous representation can be a function
registered under two independent function classes like BinarySwitch
and Meter. In this example, both functions support the same property
state with different meaning.
getPropertyMetadata(String propertyName) method cannot determinate
which property is requested. It can be BinarySwitch state or
Meter state.
To simplify the generic function discovery, the Function interface
must be used for the service registration. In this way, the generic
applications can easily find all services, which are functions in the service
registry. Because of this rule, this registration is not allowed:
context.registerService(MeterV1.class.getName(), this, regProps);
If the implementation would like to mark that there is a function, but no specific function interface exists, the registration can be:
context.registerService(Function.class.getName(), this, regProps);
Note that such functions usually don't have operations and properties.
The function properties must be integrated according to these rules:
-
Getter methods must be available for all properties with PropertyMetadata.ACCESS_READABLE access.
-
Getter method must return a subclass of FunctionData.
-
Setter methods must be available for all properties with PropertyMetadata.ACCESS_WRITABLE access.
-
Setter methods can be any combination of:
-
Setter method which accepts a subclass of FunctionData.
-
Setter method which accepts the values used by the FunctionData subclass, if there are no equal types.
It's possible to have only one or both of them. Examples:
-
There is
MyFunctionDatabean withBigDecimalvalue for adataproperty. Valid setters aresetData(MyFunctionData data)andsetData(BigDecimal data). -
There is
MySecondFunctionDatabean withBigDecimalprefix andBigDecimalsuffix for adataproperty. The prefix and suffix are using equal types and we cannot have a setter with the values used byMySecondFunctionData. The only one possible setter issetData(MySecondFunctionData data).
-
-
No methods are required for properties with PropertyMetadata.ACCESS_EVENTABLE access.
The accessor method names must be defined according JavaBeans specification.
The function operations are java methods, which cannot override the property accessor methods. They can have zero or more parameters and zero or one return value.
Operation arguments and function properties are restricted by the same set of rules. The data type can be one of the following types:
-
Java primitive type or corresponding reference type.
-
java.lang.String. -
Numerical type i.e. the type which extends
java.lang.Number. The numerical type must follow these conventions:-
The type must provide a public static method called
valueOfthat returns an instance of the given type and takes a singleStringargument or a public constructor which takes a singleStringargument. -
The
Stringargument from the previous bullet can be provided bytoString()method of the instance.
-
-
Beans, but the beans properties must use those rules. Java Beans are defined in JavaBeans specification. -
java.util.Maps. The keys can bejava.lang.String. The values of a single type follow these rules. -
Arrays of defined types.
The properties metadata is accessible with getPropertyMetadata(String). The operations metadata is accessible with getOperationMetadata(String).
In order to provide common behavior, all functions must follow a set of common rules related to the implementation of their setters, getters, operations and events:
-
The setter method must be executed synchronously. If the underlying protocol can return response to the setter call, it must be awaited. It simplifies the property value modifications and doesn't require asynchronous callback.
-
The operation method must be executed synchronously. If the underlying protocol can return an operation confirmation or response, they must be awaited. It simplifies the operation execution and doesn't require asynchronous callback.
-
The getter must return the last know cached property value. The device implementation is responsible to keep that value up to date. It'll speed up the applications when the function property values are collected. The same cached value can be shared between a few requests instead of a few calls to the real device.
-
The function operations, getters and setters must not override
java.lang.Objectand this interface methods.
The service property value contains the function description. It's an
optional property. The value type is java.lang.String.
The service property value contains the device unique identifier. The
function belongs to this device. It's an optional property. The value
type is java.lang.String.
The service property value contains the function operation names. It's an
optional property. The property is missing when there are no function
operations and property must be set when there are function operations.
The value type is java.lang.String[]. It's not possible to exist
two or more function operations with the same name i.e. the operation
overloading is not allowed.
The service property value contains the function property names. It's an
optional property. The property is missing when there are no function
properties and property must be set when there are function properties.
The value type is java.lang.String[]. It's not possible to exist
two or more function properties with the same name.
The service property value contains the reference function unique
identifiers. It's an optional property. The value type is
java.lang.String[]. It can be used to represent different
relationships between the functions.
The service property value contains the function type. It's an optional
property. For example, the sensor function can have different types like
temperature, pressure, etc. The value type is java.lang.String.
Organizations that want to use function types that do not clash with OSGi Working Group defined types should prefix their types in own namespace.
The type doesn't mandate specific function interface. It can be used with different functions.
The service property value contains the function unique identifier. It's
a mandatory property. The value type is java.lang.String. To
simplify the unique identifier generation, the property value must follow
the rule:
function UID ::= device-id ':' function-id
function UID - function unique identifier
device-id - the value of the Device.SERVICE_UID Device service property
function-id - function identifier in the scope of the device
If the function is not bound to a device, the function unique identifier can be device independent.
The service property value contains the function version. That version
can point to specific implementation version and vary in the different
vendor implementations. It's an optional property. The value type is
java.lang.String.
The function operation name, for which metadata is requested.
Provides metadata about the function operation.
This method must continue to return the operation metadata after the function service has been unregistered.
The operation metadata for the given operation name. null
if the operation metadata is not available.
IllegalArgumentException– If the function operation with the
specified name is not available.
The function property name, for which metadata is requested.
Provides metadata about the function property.
This method must continue to return the property metadata after the function service has been unregistered.
The property metadata for the given property name. null
if the property metadata is not available.
IllegalArgumentException– If the function property with the
specified name is not available.
The property key.
Returns the current value of the specified property. The method will
return the same value as ServiceReference.getProperty(String) for
the service reference of this function.
This method must continue to return property values after the device function service has been unregistered.
The property value or null if the property key cannot be
mapped to a value.
Returns an array with all function service property keys. The method will
return the same value as ServiceReference.getPropertyKeys() for
the service reference of this function. The result cannot be null
.
An array with all function service property keys, cannot be
null.
Abstract Function data wrapper. A subclass must be used for an access
to the property values by all functions. It takes care about the timestamp
and additional metadata. The subclasses are responsible to provide concrete
value and unit if required.
Metadata key, which value represents the data description. The property
value type is java.lang.String.
Represents the metadata field name. The field value is available with
getMetadata(). The field type is Map. The constant can
be used as a key to FunctionData(Map).
Represents the timestamp field name. The field value is available with
getTimestamp(). The field type is long. The constant can
be used as a key to FunctionData(Map).
Contains the new FunctionData instance field
values.
Constructs new FunctionData instance with the specified field
values. The map keys must match to the field names. The map values will
be assigned to the appropriate class fields. For example, the maps can
be: {"timestamp"=Long(1384440775495)}. That map will initialize the
FIELD_TIMESTAMP field with 1384440775495. If timestamp is
missing, Long.MIN_VALUE is used.
-
FIELD_TIMESTAMP - optional field. The value type must be
Long. -
FIELD_METADATA - optional field. The value type must be
Map.
ClassCastException– If the field value types are not expected.
NullPointerException– If the fields map is null.
The data timestamp optional field.
The data metadata optional field.
Constructs new FunctionData instance with the specified
arguments.
FunctionData to be compared.
Compares this FunctionData instance with the given argument. If
the argument is not FunctionData, it throws
ClassCastException. Otherwise, this method returns:
-
-1if this instance timestamp is less than the argument timestamp. If they are equivalent, it can be the result of the metadata map deep comparison. -
0if all fields are equivalent. -
1if this instance timestamp is greater than the argument timestamp. If they are equivalent, it can be the result of the metadata map deep comparison.
Metadata map deep comparison compares the elements of all nested
java.util.Map and array instances. null is less than any
other non-null instance.
-1, 0 or 1 depending on the comparison
rules.
ClassCastException– If the method argument is not of type
FunctionData or metadata maps contain values of different
types for the same key.
NullPointerException– If the method argument is null.
java.lang.Comparable.compareTo(java.lang.Object)
The other instance to compare. It must be of
FunctionData type.
Two FunctionData instances are equal if their metadata and
timestamp are equivalent.
true if this instance and argument have equivalent
metadata and timestamp, false otherwise.
java.lang.Object.equals(java.lang.Object)
Returns FunctionData metadata. It's dynamic metadata related only
to this specific value. Possible keys:
-
custom key
FunctionData metadata or null is there is no
metadata.
Returns FunctionData timestamp. The timestamp is the difference
between the value collecting time and midnight, January 1, 1970 UTC. It's
measured in milliseconds. The device driver is responsible to generate
that value when the value is received from the device.
java.lang.Long.MIN_VALUE value means no timestamp.
FunctionData timestamp.
Asynchronous event, which marks a function property value modification. The event can be triggered when there is a new property value, but it's possible to have events in series with no value change. The event properties must contain:
-
FUNCTION_UID - the event source function unique identifier.
-
PROPERTY_NAME - the property name.
-
PROPERTY_VALUE - the property value. The property value type must be a subclass of FunctionData.
Represents the event class. That constant can be useful for the event handlers depending on the event filters.
Represents the event package. That constant can be useful for the event handlers depending on the event filters.
Represents an event property key for function UID. The property value
type is java.lang.String. The value represents the property value
change source function identifier.
Represents an event property key for the function property name. The
property value type is java.lang.String. The value represents the
property name.
Represents an event property key for the function property value. The
property value type is a subclass of FunctionData. The value
represents the property value.
Represents the event topic for the function property changed.
The event topic.
The event properties.
Constructs a new event with the specified topic and properties.
The event topic.
The event properties.
Constructs a new event with the specified topic and properties.
The event topic.
The event source function UID.
The event source property name.
The event source property value.
Constructs a new event with the specified topic, function UID, property name and property value.
Returns the property name. The value is same as the value of PROPERTY_NAME.
The property name.
Returns the property value. The value is same as the value of PROPERTY_VALUE.
The property value.
Returns the property value change source function identifier. The value is same as the value of FUNCTION_UID property.
The property value change source function.
Contains metadata about function operation.
Metadata key, which value represents the operation description. The
property value type is java.lang.String.
Returns metadata about the function operation. The keys of the
java.util.Map result must be of java.lang.String type.
Possible keys:
-
custom key
The operation metadata or null if no such metadata is
available.
Returns metadata about the operation parameters or null if no
such metadata is available.
Operation parameters metadata.
Contains metadata about a function property, a function operation parameter or a function operation return value. The access to the function properties is a bitmap value of ACCESS metadata key. Function properties can be accessed in three ways. Any combinations between them are possible:
-
ACCESS_READABLE - available for all properties, which can be read. Function must provide a getter method for an access to the property value.
-
ACCESS_WRITABLE - available for all properties, which can be modified. Function must provide a setter method for a modification of the property value.
-
ACCESS_EVENTABLE - available for all properties, which can report the property value. FunctionEvents are sent on property change.
Metadata key, which value represents the access to the function property.
The property value is a bitmap of Integer type. The bitmap can be
any combination of:
For example, value Integer(3) means that the property is readable
and writable, but not eventable.
The property access is available only for function properties and it's missing for the operation parameters.
Marks the eventable function properties. The flag can be used as a part of bitmap value of ACCESS.
Marks the readable function properties. The flag can be used as a part of bitmap value of ACCESS. The readable access mandates function to provide a property getter method.
Marks the writable function properties. The flag can be used as a part of bitmap value of ACCESS. The writable access mandates function to provide a property setter methods.
Metadata key, which value represents the property description. The
property value type is java.lang.String.
Metadata key, which value represents the property supported units. The
property value type is java.lang.String[]. The array first
element at index 0 represents the default unit. Each unit must
follow those rules:
-
The International System of Units must be used where it's applicable. For example, kg for kilogram and km for kilometer.
-
If the unit name matches to an Unicode symbol name, the Unicode symbol must be used. For example, the degree unit matches to the Unicode degree sign (
°). -
If the unit name doesn't match to an Unicode symbol, the unit symbol must be built by Unicode Basic Latin block of characters, superscript and subscript characters. For example, watt per square meter steradian is built by
W/(m² sr).
If those rules cannot be applied to the unit symbol, custom rules are allowed. A set of predefined unit symbols are available in SIUnits interface.
The unit to align the supported values, can be null.
Returns the property possible values according to the specified unit. If
the unit is null, the values set is aligned to the default unit.
If there is no such set of supported values, null is returned.
The values must be sorted in increasing order.
The supported values according to the specified unit or
null if no such values are supported. The values must be
sorted in increasing order.
IllegalArgumentException– If the unit is not supported.
The unit to align the maximum value, can be null .
Returns the property maximum value according to the specified unit. If
the unit is null, the maximum value is aligned to the default
unit. If there is no maximum value, null is returned.
The maximum value according to the specified unit or null
if no maximum value is supported.
IllegalArgumentException– If the unit is not supported.
The unit to align the metadata if it's applicable. It can be null, which means that the default unit will be used.
Returns metadata about the function property or operation parameter. The
keys of the java.util.Map result must be of
java.lang.String type. Possible keys:
-
DESCRIPTION - doesn't depend on the given unit.
-
ACCESS - available only for function property and missing for function operation parameters. It doesn't depend on the given unit.
-
UNITS - doesn't depend on the given unit.
-
custom key - can depend on the unit. Organizations that want to use custom keys that do not clash with OSGi Working Group defined should prefix their keys in own namespace.
The property metadata or null if no such metadata is
available.
The unit to align the minimum value, can be null .
Returns the property minimum value according to the specified unit. If
the unit is null, the minimum value is aligned to the default
unit. If there is no minimum value, null is returned.
The minimum value according to the specified unit or null
if no minimum value is supported.
IllegalArgumentException– If the unit is not supported.
The unit to align the step, can be null.
Returns the difference between two values in series. For example, if the range is [0, 100], the step can be 10.
The step according to the specified unit or null if no
step is supported.
IllegalArgumentException– If the unit is not supported.
Contains most of the International System of Units unit symbols. The constant name represents the unit name. The constant value represents the unit symbol as it's defined in PropertyMetadata.UNITS.
Unit of electric current defined by the International System of Units (SI). It's one of be base units called ampere.
Unit of magnetic field strength. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called ampere per meter.
Unit of current density. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called ampere per square meter.
Unit of length. It's one of other non-SI units. The unit is called angstrom.
Unit of pressure. It's one of other non-SI units. The unit is called bar.
Unit of area. It's one of other non-SI units. The unit is called barn.
Unit of activity referred to a radionuclide. It's one of the coherent derived units in the SI with special names and symbols. The unit is called becquerel.
Unit of logarithmic ratio quantities. It's one of other non-SI units. The unit is called bel.
Unit of luminous intensity defined by the International System of Units (SI). It's one of be base units called candela.
Unit of luminance. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called candela per square meter.
Unit of electronic charge, amount of electricity. It's one of the coherent derived units in the SI with special names and symbols. The unit is called coulomb.
Unit of electric charge density. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called coulomb per cubic meter.
Unit of exposure (x- and gamma-rays). It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called coulomb per kilogram.
Unit of surface charge density, electric flux density, electric displacement. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called coulomb per square meter.
Unit of volume. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called cubic meter.
Unit of specific volume. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called cubic meter per kilogram.
Unit of time. It's one of non-SI units accepted for use with the International System of Units. The unit is called day.
Unit of logarithmic ratio quantities. It's one of other non-SI units. The unit is called decibel.
Unit of plane angle. It's one of non-SI units accepted for use with the International System of Units. The unit is called degree.
Unit of Celsius temperature. It's one of the coherent derived units in the SI with special names and symbols. The unit is called degree Celsius.
Unit of force. It's one of non-SI units associated with the CGS and the CGS-Gaussian system of units. The unit is called dyne.
Unit of energy. It's one of non-SI units associated with the CGS and the CGS-Gaussian system of units. The unit is called erg.
Unit of capacitance. It's one of the coherent derived units in the SI with special names and symbols. The unit is called farad.
Unit of permittivity. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called farad per meter.
Unit of acceleration. It's one of non-SI units associated with the CGS and the CGS-Gaussian system of units. The unit is called gal.
Unit of magnetic flux density. It's one of non-SI units associated with the CGS and the CGS-Gaussian system of units. The unit is called gauss.
Unit of absorbed dose, specific energy (imparted), kerma. It's one of the coherent derived units in the SI with special names and symbols. The unit is called gray.
Unit of absorbed dose rate. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called gray per second.
Unit of area. It's one of non-SI units accepted for use with the International System of Units. The unit is called hectare.
Unit of inductance. It's one of the coherent derived units in the SI with special names and symbols. The unit is called henry.
Unit of permeability. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called henry per meter.
Unit of frequency. It's one of the coherent derived units in the SI with special names and symbols. The unit is called hertz.
Unit of time. It's one of non-SI units accepted for use with the International System of Units. The unit is called hour.
Unit of energy, work, amount of electricity. It's one of the coherent derived units in the SI with special names and symbols. The unit is called joule.
Unit of energy density. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called joule per cubic meter.
Unit of heat capacity, entropy. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called joule per kelvin.
Unit of specific energy. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called joule per kilogram.
Unit of specific heat capacity, specific entropy. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called joule per kilogram kelvin.
Unit of molar energy. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called joule per mole.
Unit of molar entropy, molar heat capacity. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called joule per mole kelvin.
Unit of catalytic activity. It's one of the coherent derived units in the SI with special names and symbols. The unit is called katal.
Unit of catalytic activity concentration. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called katal per cubic meter.
Unit of thermodynamic temperature defined by the International System of Units (SI). It's one of be base units called kelvin.
Unit of mass defined by the International System of Units (SI). It's one of be base units called kilogram.
Unit of density, mass density, mass concentration. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called kilogram per cubic meter.
Unit of surface density. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called kilogram per square meter.
Unit of speed. It's one of other non-SI units. The unit is called knot.
Unit of volume. It's one of non-SI units accepted for use with the International System of Units. The unit is called liter. International System of Units accepts two symbols: lower-case l and capital L. That constant value is using the lower-case l.
Unit of luminous flux. It's one of the coherent derived units in the SI with special names and symbols. The unit is called lumen.
Unit of illuminance. It's one of the coherent derived units in the SI with special names and symbols. The unit is called lux.
Unit of magnetic flux. It's one of non-SI units associated with the CGS and the CGS-Gaussian system of units. The unit is called maxwell.
Unit of length defined by the International System of Units (SI). It's one of be base units called meter.
Unit of speed, velocity. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called meter per second.
Unit of acceleration. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called meter per second squared.
Unit of pressure. It's one of other non-SI units. The unit is called millimeter of mercury.
Unit of amount of substance defined by the International System of Units (SI). It's one of be base units called mole.
Unit of amount concentration, concentration. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called mole per cubic meter.
Unit of distance. It's one of other non-SI units. The unit is called nautical mile.
Unit of logarithmic ratio quantities. It's one of other non-SI units. The unit is called neper.
Unit of force. It's one of the coherent derived units in the SI with special names and symbols. The unit is called newton.
Unit of moment of force. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called newton meter.
Unit of surface tension. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called newton per meter.
Unit of magnetic field. It's one of non-SI units associated with the CGS and the CGS-Gaussian system of units. The unit is called oersted.
Unit of electric resistance. It's one of the coherent derived units in the SI with special names and symbols. The unit is called ohm.
Unit of pressure, stress. It's one of the coherent derived units in the SI with special names and symbols. The unit is called pascal.
Unit of dynamic viscosity. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called pascal second.
Unit of illuminance. It's one of non-SI units associated with the CGS and the CGS-Gaussian system of units. The unit is called phot.
Unit of plane angle. It's one of non-SI units accepted for use with the International System of Units. The unit is called minute.
Unit of plane angle. It's one of non-SI units accepted for use with the International System of Units. The unit is called second.
Unit of dynamic viscosity. It's one of non-SI units associated with the CGS and the CGS-Gaussian system of units. The unit is called poise.
Adopted prefix symbol to form the symbols of the decimal submultiples of SI units. It's called atto and represents the 18th negative power of ten.
Adopted prefix symbol to form the symbols of the decimal submultiples of SI units. It's called centi and represents the 2nd negative power of ten.
Adopted prefix symbol to form the symbols of the decimal multiples of SI units. It's called deca and represents the 1st power of ten.
Adopted prefix symbol to form the symbols of the decimal submultiples of SI units. It's called deci and represents the 1st negative power of ten.
Adopted prefix symbol to form the symbols of the decimal multiples of SI units. It's called exa and represents the 18th power of ten.
Adopted prefix symbol to form the symbols of the decimal submultiples of SI units. It's called femto and represents the 15th negative power of ten.
Adopted prefix symbol to form the symbols of the decimal multiples of SI units. It's called giga and represents the 9th power of ten.
Adopted prefix symbol to form the symbols of the decimal multiples of SI units. It's called hecto and represents the 2nd power of ten.
Adopted prefix symbol to form the symbols of the decimal multiples of SI units. It's called kilo and represents the 3rd power of ten.
Adopted prefix symbol to form the symbols of the decimal multiples of SI units. It's called mega and represents the 6th power of ten.
Adopted prefix symbol to form the symbols of the decimal submultiples of SI units. It's called micro and represents the 6th negative power of ten.
Adopted prefix symbol to form the symbols of the decimal submultiples of SI units. It's called milli and represents the 3rd negative power of ten.
Adopted prefix symbol to form the symbols of the decimal submultiples of SI units. It's called nano and represents the 9th negative power of ten.
Adopted prefix symbol to form the symbols of the decimal submultiples of SI units. It's called pico and represents the 12th negative power of ten.
Adopted prefix symbol to form the symbols of the decimal submultiples of SI units. It's called yocto and represents the 24th negative power of ten.
Adopted prefix symbol to form the symbols of the decimal multiples of SI units. It's called yotta and represents the 24th power of ten.
Adopted prefix symbol to form the symbols of the decimal submultiples of SI units. It's called zepto and represents the 21th negative power of ten.
Adopted prefix symbol to form the symbols of the decimal multiples of SI units. It's called zetta and represents the 21th power of ten.
Unit of plane angle. It's one of the coherent derived units in the SI with special names and symbols. The unit is called radian.
Unit of angular velocity. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called radian per second.
Unit of angular acceleration. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called radian per second squared.
Unit of wavenumber. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called reciprocal meter.
Unit of time defined by the International System of Units (SI). It's one of be base units called second.
Unit of electric conductance. It's one of the coherent derived units in the SI with special names and symbols. The unit is called siemens.
Unit of dose equivalent, ambient dose equivalent, directional dose equivalent, personal dose equivalent. It's one of the coherent derived units in the SI with special names and symbols. The unit is called sievert.
Unit of area. It's one of coherent derived units in the SI expressed in terms of base units. The unit is called square meter.
Unit of solid angle. It's one of the coherent derived units in the SI with special names and symbols. The unit is called steradian.
Unit of luminance. It's one of non-SI units associated with the CGS and the CGS-Gaussian system of units. The unit is called stilb.
Unit of kinematic viscosity. It's one of non-SI units associated with the CGS and the CGS-Gaussian system of units. The unit is called stokes.
Unit of magnetic flux density. It's one of the coherent derived units in the SI with special names and symbols. The unit is called tesla.
Unit of time. It's one of non-SI units accepted for use with the International System of Units. The unit is called minute.
Unit of mass. It's one of non-SI units accepted for use with the International System of Units. The unit is called tonne.
Unit of electric potential difference, electromotive force. It's one of the coherent derived units in the SI with special names and symbols. The unit is called volt.
Unit of electric field strength. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called volt per meter.
Unit of power, radiant flux. It's one of the coherent derived units in the SI with special names and symbols. The unit is called watt.
Unit of thermal conductivity. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called watt per meter kelvin.
Unit of heat flux density, irradiance. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called watt per square meter.
Unit of radiance. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called watt per square meter steradian.
Unit of radiant intensity. It's one of coherent derived units whose names and symbols include SI coherent derived units with special names and symbols. The unit is called watt per steradian.