The HDM provides a mechanism for inserting custom logic for its basic operations - adding/removing devices or zones, changing the value of a home device or a device class object property, or executing a device class object operation.
Using Hooks
To use a hook implement its interface and register it as an OSGi service. Optionally, you can specify as registration properties of the service the parameters of the devices or zones that this hook should be used for.
For each Hook interface is provided a list of registration properties that you can use.
The value of a property can be either of type String - for one value or String[] - for multiple values.
After the Hook is registered the Home Device Manager automatically discovers it and attaches it to its system.
When multiple hook services are registered for a certain device or zone, the service with the highest ranking number will be called first.
Available Hooks
Currently there are four hooks available:
DeviceClassObjectModifyHook
The DeviceClassObjectModifyHook is used when the value of a Device Class Object property is about to be changed. Before setting the new value the Home Device Manager calls the modifyProperty method to check if this value needs to be modified or can be used as it is. Optionally, to specify the target devices, you can register this Hook with the following properties:
HomeDevice.ADAPTERF
HomeDevice.UID
HomeDevice.NAME
HomeDevice.VENDOR
HomeDevice.VERSION
HomeDevice.TYPE
HomeDevice.DEVICE_CLASSES
HomeDeviceAddHook
The HomeDeviceAddHook is used to prevent adding unexpected Home Devices to the HDM, as well as to specify the visibility of Home Devices which cannot be removed from the HDM (for example, due to Protocol Adapter limitations).
The HomeDeviceAddHook provides three methods - setHandler, deviceAvailable and deviceUnavailable. HDM uses such hooks when:
an adapter notifies the HDM that a new device is added, meaning that the HomeDeviceAdminSpi.homeDeviceAdded is invoked;
a device is removed, because the HomeDeviceAddHook needs to notify the HDM that a device is not available anymore.
If multiple services need to be registered to a specific device, the hooks are called in the compareTo reverse ordering of their Service References. The service with the highest ranking number is called first when:
all the hooks for a single device notify the HDM that the device is accepted - it is considered as expected and is set to visible;
at least one hook notifies the HDM that a device needs to be rejected - the device removal is invoked.
In some cases custom logic will be needed in order to prevent any useless adding of devices or visibility state management issues. In order to add a home device, it must be specified with the hook model which accepts/rejects devices that are waiting to be added. Otherwise a device, different from the expected one might be detected first. All devices that are collected in the inbox are checked. The hook is notified for every available device and is responsible to accept or reject every device by invoking a method of the HomeDeviceAddHookHandler as a callback. The devices that are accepted by the hook should be added and set to visible. A rejected device should be removed. When a device is unavailable the HDM notifies the HomeDeviceAddHook that the provided device is removed.ptionally, to specify the target devices, you can register this Hook with the following properties:
HomeDevice.ADAPTER
HomeDevice.UID
HomeDevice.NAME
HomeDevice.VENDOR
HomeDevice.VERSION
HomeDevice.TYPE
HomeDevice.STATUS
HomeDevice.DEVICE_CLASSES
HomeDevice.PARENT_UID
HomeDevice.CONTROLLER_ID
HomeDevice.MODEL
HomeDevice.ERROR_CODE
HomeDevice.FIRMWARE_VENDOR
HomeDevice.FIRMWARE_VERSION
HomeDevice.SERIAL_NUMBER
HomeDevice.SECURE and others
HomeDeviceValidateHook
The Home Device Manager calls all registered HomeDeviceValidateHook services when the values of Home Device properties need to be validated before they are set. HDM uses such hooks when an application tries to:
Add a Home Device with specified set of properties. The hook should provide a meaningful implementation of the validateAddingProperties method. HDM expects this method to throw an exception even if the validation fails only for one property and the device should not be added to HDM. In case the validation is successful the Home Device Manager adds the Home Device and fires an event with topic TOPIC_HOME_DEVICE_ADDED.
Set a value to a specific Home Device property. The hook should provide an implementation of the validateProperty method which verifies if a correct value is set to the specific Home Device property. HDM expects this method to throw an exception if the new value is not a valid one for the specific Home Device instance. In this case HDM does not set the new value to the Home Device property.
Set a value to a specific Device Class Object property. The hook should provide an implementation of the validateDCOProperty method which verifies if the DCO property value is valid for the specific Home Device and Device Class Object instances. HDM expects this method to throw an exception in case the DCO property value is not a valid one for the specific Home Device and Device Class Object instances. In this case HDM does not set the new value to the Home Device property.
Invoke a Device Class Object operation with a set of arguments. The hook should provide an implementation of the validateDCOOperation method which validates the arguments for executing a Device Class Object operation before it is invoked. HDM expects an exception to be thrown by this method if the values of the operation arguments are not valid for performing the specific Device Class Object operation in HDM. In this case HDM does not execute the Device Class Object operation.
Optionally, to specify the target devices, you can register this Hook with the following properties:
HomeDevice.ADAPTER
HomeDevice.UID
HomeDevice.NAME
HomeDevice.VENDOR
HomeDevice.VERSION
HomeDevice.TYPE
HomeDevice.STATUS
HomeDevice.DEVICE_CLASSES
HomeDevice.PARENT_UID
HomeDevice.CONTROLLER_ID
HomeDevice.MODEL
HomeDevice.ERROR_CODE
HomeDevice.FIRMWARE_VENDOR
HomeDevice.FIRMWARE_VERSION
HomeDevice.SERIAL_NUMBER
HomeDevice.SECURE and others
HomeZoneValidateHook
The Home Device Manager calls all registered HomeZoneValidateHook services when the values of the Home Zone properties and Device Class Object properties that should be set to devices part of a Home Zone, need to be validated before they are set. HDM uses such hooks when an application tries to:
Add a Home Zone with a specified set of properties. The hook should provide an implementation of the validateAddingProperties method. HDM expects this method to throw an exception even if the validation fails only for one property. In this case HDM does not add the zone to its management scope. If the validation is successful the Home Device Manager adds the Home Zone and fires an event with topic TOPIC_HOME_ZONE_ADDED.
Set a value to a specific Home Zone property. The hook should provide an implementation of the validateProperty method. HDM expects this method to throw an exception if the new value is not a valid one for the specific Home Zone instance. In this case HDM does not set the new value to the Home Zone property.
Set a value to a Device Class Object property for a device part of a Home Zone instance. The hook should provide an implementation of the validateDCOProperty method. HDM expects this method to throw an exception in case the DCO property value does not validate. In this case HDM does not set the new value to the DCO property.
Invoke a Device Class Object operation with a set of arguments over the devices in a Home Zone instance. The hook should provide an implementation of the validateDCOOperation method. HDM expects this method to throw an exception even if only one of the operation arguments is not valid for the specific Device Class Object operation for all devices in the specified Home Zone. HDM will not execute the operation if it is not successfully validated by all registered HomeZoneValidateHook services.
Optionally, to specify the target zones, you can register this Hook with the following properties:
