The standard methods for changing properties and invoking operations on Device Class Objects are executed synchronously which means that the program halts while the Protocol Adapter waits for response from the device(s).

The AsynchUtility (com.prosyst.mbs.services.hdm.util.async.AsyncUtility) provides methods for changing property values and for invoking operations on Device Class Objects that are executed asynchronously (in a separate thread) and hence they do not stop the execution of your program. The AsynchUtility methods allow you to send requests to sleeping devices, which with the synchronous methods is not possible for they throw exceptions in such cases. These requests are put in a queue and are executed once the device wakes up.

The AsynchUtility (com.prosyst.mbs.services.hdm.util.async.AsyncUtility) provides methods for changing property values and for invoking operations on Device Class Objects that are executed asynchronously (in a separate thread) and hence they do not stop the execution of your program. The AsynchUtility methods allow you to send requests to sleeping devices, which with the synchronous methods is not possible for they throw exceptions in such cases. These requests are put in a queue and are executed once the device wakes up.

To make an asynchronous method call to a device or zone you have the following alternatives:

Executing an Asynchronous DCO Operation/Property Change

To create an asynchronous request for executing an operation or for changing a property of a Device Class Object you can use the Java or JSON-RPC API of the HDM module.

If a device class object operation or property change throws a HomeDeviceException with code HomeDeviceException.COMMUNICATION_ERROR and the home device has device class WakeUp, device class object property WakeUp.PROPERTY_AWAKE and the status of the device of the device class object is HomeDevice.STATUS_ONLINE, this means that the home device is asleep and the request is put back in the waiting queue, as well as all subsequent requests. As soon as the home device awakes, the HDM Util tries several times to execute the request. If all attempts fail, the exception is sent to an AsyncCallback object. After the execution of all waiting requests, the home device is forced to go back to sleep mode.

Via Java API

To create an asynchronous request for executing an operation or for changing a property of a Device Class Object you need an AsyncCallback object. The asynchronous callback contains the code which is executed after a Device Class Object operation is invoked/a property is changed. Its three methods correspond to the three possible outcomes of a Device Class Object request.

• If the request doesn't reach the device, the remove method is called and a constant is passed that indicates why the request failed (check the API).
• If the request reaches the device, but the device returns an exception, the exceptionOccurred method is called (This is valid only for Device Class Object requests. Zone requests do not return exceptions).
• If the request reaches the device and is executed successfully, the result method is called.

The following Java code snippet provides an example implementation of the AsyncCallback interface, that prints information about the execution status of each operation:

  public class MyCallback implements AsyncCallback {

    public void exceptionOccurred(AsyncRequest arg0, HomeDeviceException arg1) {

      if (arg0 instanceof DCOOperationAsyncRequest) {

        DCOOperationAsyncRequest myrequest = (DCOOperationAsyncRequest) arg0;

        System.out.println("Operation " + myrequest.getDCOOperation()

            + " failed because of an exception: " + arg1.getMessage());

      }

    }

    public void removed(AsyncRequest arg0, int arg1) {

      if (arg0 instanceof DCOOperationAsyncRequest) {

        DCOOperationAsyncRequest myrequest = (DCOOperationAsyncRequest) arg0;

        System.out.println("Operation " + myrequest.getDCOOperation()

            + " was stopped");

      }

    }

    public void result(AsyncRequest arg0, Object arg1) {

      if (arg0 instanceof DCOOperationAsyncRequest) {

        DCOOperationAsyncRequest myrequest = (DCOOperationAsyncRequest) arg0;

        System.out.println("Operation " + myrequest.getDCOOperation()

            + " executed sucessfully on device "

            + myrequest.getHomeDevice().getUID());

      }

    }

  }

To execute a property change/operation using one of the methods of the AsyncUtility create an instance of your implementation of the AsyncCallback interface and pass it as an argument to the respective method of the AsyncUtility.

The following Java code snippet demonstrates how to asynchronously execute the toggle operation on the device with UID "23". An instance of the asynchronous callback implemented in the previous example is used.

String deviceUID = "23"; String deviceClass = BinarySwitch.class.getName(); String operation = "toggle"; Object[] arguments = null; int timeToLive = 5000; //instantiate the callback MyCallback callback = new MyCallback(); //retrieve the Device HomeDevice device = deviceadmin.getHomeDevice(deviceUID); //call the static method to invoke an operation on a Device Class Object AsyncUtility.invokeDCOOperation(callback, device, deviceClass, operation, arguments, timeToLive);

Each Java API request method for operation/property change returns an AsyncRequest object that contains information about your request and allows you to cancel it if it is no longer applicable.

Via JSON-RPC API

If you are using the JSON Remote API each request is identified by a callerID and a requestID. By subscribing to the events for these IDs you will be notified about the responses to your requests. To do so:

1. Install the Remote Events component.
2. Subscribe to a remote event with the following topic and filter:
   • Topic: The response event topic which corresponds to the type of your request (Device Class Object or Zone operation, or property change).
   • Filter: Remote asynchronous requests are identified by caller and request IDs, so you can filter the request by one of them or by both using an LDAP filter:

The following LDAP filter demonstrates how to receive the responses to the requests with caller ID equal to "myApplication":

(event.caller.id=myApplication)

The following LDAP filter shows how to receive the responses to a specific request with caller ID "myApplication" and request ID "1".

(&&(event.caller.id=myApplication)(event.request.id=1))

To create an asynchronous request for executing an operation or for changing a property of a Device Class Object:

• Call one of the HDMUtil/async<method_name> methods from the JSON-RPC API that corresponds to the type of your request.
• Pass the callerID and requestID as method parameters.
• Provide the other parameters depending on the method you are calling.

The following JavaScript code snippet demonstrates how to invoke an asynchronous toggle operation on a device with UID "23".

deviceUID = "23" deviceClass = "com.prosyst.mbs.services.hdm.deviceclasses.BinarySwitch" operation = "toggle" arguments = {} timeToLive = 5000 //establish an ID for the application which is calling the method(callerID) and for this specific request (requestID) callerID="myApplication" requestID="1" //call the static function to invoke an operation on a Device Class Object params = [callerID, requestID, deviceUID, deviceClass, operation, arguments, timeToLive] var xhr = new XMLHttpRequest(); xhr.open("POST", "/remote/json-rpc", false); // xhr.send('{"jsonrpc": "2.0", "method": "HDMUtil/asyncInvokeDCOOperation", "params": ["'+callerID+'", "'+requestID+'", "'+deviceClass+'", "'+operation+'", "'+arguments+'", "'+timeToLive+'"], "id": 2}') xhr.send('{"jsonrpc": "2.0", "method": "HDMUtil/asyncInvokeDCOOperation", "params":'+JSON.stringify(params)+', "id": 2}')

Executing a Zone Operation/Property Request

Requests for executing an operation or for changing a property of a Zone are created in the same way as Device Class Object requests.

When you create a Zone request, the AsynchUtility obtains all devices from the Zone and creates a separate asynchronous request for each one of them.

Canceling Asynchronous Requests

Asynchronous requests can be canceled before or during their execution.

A request is canceled automatically when it expires or when the request limit for a certain device is reached.

Via Java API

To cancel an asynchronous request invoke the cancel method of the AsyncRequest instance. The following Java code snippet demonstrates how to invoke an asynchronous operation on a Device Class Object and cancel it right away.

// invoke an operation on a Device Class Object and save a reference to the request DCOOperationAsyncRequest request = AsyncUtility.invokeDCOOperation( callback, device, deviceClass, operation, arguments, timeToLive); //cancel the request request.cancel();

When a request is canceled HDM executes the removed(AsyncRequest request, int removeCode) method of the AsyncCallback object with arguments: the canceled request object and the int constant AsyncCallback.CODE_REQUEST_CANCELLED.

Via JSON-RPC API

If you are using the JSON Remote API you can cancel a request by calling the HDMUtil/removeAsyncRequest function and passing the ID of the request. The following JavaScript code example shows how to invoke an asynchronous operation and cancel it immediately after that.

// invoke an operation on a Device Class Object var xhr = new XMLHttpRequest(); xhr.open("POST", "/remote/json-rpc", false); xhr.send('{"jsonrpc": "2.0", "method": "HDMUtil/asyncInvokeDCOOperation", "params":'+JSON.stringify(params)+', "id": 1}') // cancel the request by passing as parameters its caller and request IDs xhr.open("POST", "/remote/json-rpc", false); xhr.send('{"jsonrpc": "2.0", "method": "HDMUtil/removeAsyncRequest", "params":["myApplication", "1"], "id": 2}')

Configuration

• The HDM AsyncUtility registers a ManagedService with name HDM Util Async Configuration and PID mbs.da.hdm.api.async.
• The mbs.da.hdm.api.async.blacklist.devices is Factory Configuration registered by HDM AsyncUtility. The AsyncUtility will check all available configuration instances (of this factory configuration), and if any of the filters matches a device, the AsyncUtility will not send goToSleep.

The available configuration properties can be viewed here.

For further information on how to setup Configurations, please follow the instructions in this guide.