Interface Device


  • public interface Device
    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.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String DEVICE_CATEGORY
      Constant for the value of the Constants.DEVICE_CATEGORY service property.
      static java.lang.String SERVICE_DESCRIPTION
      The service property value contains the device description.
      static java.lang.String SERVICE_DRIVER
      The service property value contains the device driver name.
      static java.lang.String SERVICE_FIRMWARE_VENDOR
      The service property value contains the device firmware vendor.
      static java.lang.String SERVICE_FIRMWARE_VERSION
      The service property value contains the device firmware version.
      static java.lang.String SERVICE_HARDWARE_VENDOR
      The service property value contains the device hardware vendor.
      static java.lang.String SERVICE_HARDWARE_VERSION
      The service property value contains the device hardware version.
      static java.lang.String SERVICE_MODEL
      The service property value contains the device model.
      static java.lang.String SERVICE_NAME
      The service property value contains the device name.
      static java.lang.String SERVICE_REFERENCE_UIDS
      The service property value contains the reference device unique identifiers.
      static java.lang.String SERVICE_SERIAL_NUMBER
      The service property value contains the device serial number.
      static java.lang.String SERVICE_STATUS
      The service property value contains the device status.
      static java.lang.String SERVICE_STATUS_DETAIL
      The service property value contains the device status detail.
      static java.lang.String SERVICE_TYPES
      The service property value contains the device types like DVD, TV, etc.
      static java.lang.String SERVICE_UID
      The service property value contains the device unique identifier.
      static java.lang.Integer STATUS_DETAIL_BROKEN
      Device status detail indicates that the device is broken.
      static java.lang.Integer STATUS_DETAIL_COMMUNICATION_ERROR
      Device status detail indicates that the device communication is problematic.
      static java.lang.Integer STATUS_DETAIL_CONFIGURATION_ERROR
      Device status detail indicates that the device cannot be configured.
      static java.lang.Integer STATUS_DETAIL_CONFIGURATION_UNAPPLIED
      Device status detail indicates that the device configuration is not applied.
      static java.lang.Integer STATUS_DETAIL_CONNECTING
      Device status detail indicates that the device is currently connecting to the network.
      static java.lang.Integer STATUS_DETAIL_DATA_INSUFFICIENT
      Device status detail indicates that the device doesn't provide enough information and cannot be determined.
      static java.lang.Integer STATUS_DETAIL_DUTY_CYCLE
      Device status detail indicates that the device is in duty cycle.
      static java.lang.Integer STATUS_DETAIL_FIRMWARE_UPDATING
      Device status detail indicates that the device firmware is updating.
      static java.lang.Integer STATUS_DETAIL_INACCESSIBLE
      Device status detail indicates that the device is not accessible and further communication is not possible.
      static java.lang.Integer STATUS_DETAIL_INITIALIZING
      Device status detail indicates that the device is currently in process of initialization.
      static java.lang.Integer STATUS_DETAIL_REMOVING
      Device status detail indicates that the device is leaving the network.
      static java.lang.Integer STATUS_NOT_CONFIGURED
      Device status indicates that the device is currently not configured.
      static java.lang.Integer STATUS_NOT_INITIALIZED
      Device status indicates that the device is currently not initialized.
      static java.lang.Integer STATUS_OFFLINE
      Device status indicates that the device is currently not available for operations.
      static java.lang.Integer STATUS_ONLINE
      Device status indicates that the device is currently available for operations.
      static java.lang.Integer STATUS_PROCESSING
      Device status indicates that the device is currently busy with an operation.
      static java.lang.Integer STATUS_REMOVED
      Device status indicates that the device has been removed from the network.
    • Field Detail

      • SERVICE_UID

        static final java.lang.String SERVICE_UID
        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

        See Also:
        Constant Field Values
      • SERVICE_REFERENCE_UIDS

        static final java.lang.String SERVICE_REFERENCE_UIDS
        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.
        See Also:
        Constant Field Values
      • SERVICE_DRIVER

        static final java.lang.String SERVICE_DRIVER
        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.
        See Also:
        Constant Field Values
      • SERVICE_NAME

        static final java.lang.String SERVICE_NAME
        The service property value contains the device name. It's an optional property. The value type is java.lang.String.
        See Also:
        Constant Field Values
      • SERVICE_HARDWARE_VENDOR

        static final java.lang.String SERVICE_HARDWARE_VENDOR
        The service property value contains the device hardware vendor. It's an optional property. The value type is java.lang.String.
        See Also:
        Constant Field Values
      • SERVICE_HARDWARE_VERSION

        static final java.lang.String SERVICE_HARDWARE_VERSION
        The service property value contains the device hardware version. It's an optional property. The value type is java.lang.String.
        See Also:
        Constant Field Values
      • SERVICE_FIRMWARE_VENDOR

        static final java.lang.String SERVICE_FIRMWARE_VENDOR
        The service property value contains the device firmware vendor. It's an optional property. The value type is java.lang.String.
        See Also:
        Constant Field Values
      • SERVICE_FIRMWARE_VERSION

        static final java.lang.String SERVICE_FIRMWARE_VERSION
        The service property value contains the device firmware version. It's an optional property. The value type is java.lang.String.
        See Also:
        Constant Field Values
      • SERVICE_TYPES

        static final java.lang.String SERVICE_TYPES
        The service property value contains the device types like DVD, TV, etc. It's an optional property. The value type is java.lang.String[].
        See Also:
        Constant Field Values
      • SERVICE_MODEL

        static final java.lang.String SERVICE_MODEL
        The service property value contains the device model. It's an optional property. The value type is java.lang.String.
        See Also:
        Constant Field Values
      • SERVICE_SERIAL_NUMBER

        static final java.lang.String SERVICE_SERIAL_NUMBER
        The service property value contains the device serial number. It's an optional property. The value type is java.lang.String.
        See Also:
        Constant Field Values
      • SERVICE_DESCRIPTION

        static final java.lang.String SERVICE_DESCRIPTION
        The service property value contains the device description. It's an optional property. The value type is java.lang.String.
        See Also:
        Constant Field Values
      • STATUS_REMOVED

        static final java.lang.Integer STATUS_REMOVED
        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.
      • STATUS_OFFLINE

        static final java.lang.Integer STATUS_OFFLINE
        Device status indicates that the device is currently not available for operations. It can be used as a value of SERVICE_STATUS service property.
      • STATUS_ONLINE

        static final java.lang.Integer STATUS_ONLINE
        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.
      • STATUS_PROCESSING

        static final java.lang.Integer STATUS_PROCESSING
        Device status indicates that the device is currently busy with an operation. It can be used as a value of SERVICE_STATUS service property.
      • STATUS_NOT_INITIALIZED

        static final java.lang.Integer STATUS_NOT_INITIALIZED
        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.
      • STATUS_NOT_CONFIGURED

        static final java.lang.Integer STATUS_NOT_CONFIGURED
        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.
      • STATUS_DETAIL_CONNECTING

        static final java.lang.Integer STATUS_DETAIL_CONNECTING
        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.
      • STATUS_DETAIL_INITIALIZING

        static final java.lang.Integer STATUS_DETAIL_INITIALIZING
        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.
      • STATUS_DETAIL_REMOVING

        static final java.lang.Integer STATUS_DETAIL_REMOVING
        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.
      • STATUS_DETAIL_FIRMWARE_UPDATING

        static final java.lang.Integer STATUS_DETAIL_FIRMWARE_UPDATING
        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.
      • STATUS_DETAIL_CONFIGURATION_UNAPPLIED

        static final java.lang.Integer STATUS_DETAIL_CONFIGURATION_UNAPPLIED
        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.
      • STATUS_DETAIL_BROKEN

        static final java.lang.Integer STATUS_DETAIL_BROKEN
        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.
      • STATUS_DETAIL_COMMUNICATION_ERROR

        static final java.lang.Integer STATUS_DETAIL_COMMUNICATION_ERROR
        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.
      • STATUS_DETAIL_DATA_INSUFFICIENT

        static final java.lang.Integer STATUS_DETAIL_DATA_INSUFFICIENT
        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.
      • STATUS_DETAIL_INACCESSIBLE

        static final java.lang.Integer STATUS_DETAIL_INACCESSIBLE
        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.
      • STATUS_DETAIL_CONFIGURATION_ERROR

        static final java.lang.Integer STATUS_DETAIL_CONFIGURATION_ERROR
        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.
      • STATUS_DETAIL_DUTY_CYCLE

        static final java.lang.Integer STATUS_DETAIL_DUTY_CYCLE
        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.
    • Method Detail

      • getServiceProperty

        java.lang.Object getServiceProperty​(java.lang.String propKey)
        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.

        Parameters:
        propKey - The property key.
        Returns:
        The property value or null if the property key cannot be mapped to a value.
      • getServicePropertyKeys

        java.lang.String[] getServicePropertyKeys()
        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.
        Returns:
        An array with all device service property keys, cannot be null.
      • remove

        void remove()
             throws DeviceException
        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.
        Throws:
        DeviceException - If an operation error is available.
        java.lang.UnsupportedOperationException - If the operation is not supported over this device.
        java.lang.SecurityException - If the caller does not have the appropriate DevicePermission(this device, DevicePermission.REMOVE) and the Java Runtime Environment supports permissions.
        java.lang.IllegalStateException - If this device service object has already been unregistered.