Work with command callbacks

A function on the client may be dependent on having the service complete the execution of a given command handler. For example, if the client sends a command to perform a search in a database, whatever action the client plans to take based on the search results must wait until the service has completed the search and returned the result.

For these situations, client applications can register an optional response callback function in their command call, which will run once the service-side handler is done.

This section describes how to specify a callback, and how to read the service response parameters from within the callback. (For information on how the service populates the response, see Set response parameters from the service.)

Steps

Set up a callback on the client

APIs:

WebClient.queueCommand() | HTML5 | Android
PWWebClient.queueCommand() | iOS

To provide a callback function, you would include it as the last argument of queueCommand.

The callback takes the CommandResponseEventArgs object, which encapsulates the command responses populated by the service.

The syntax will look something like this:

HTML5

pureweb.getClient().queueCommand('NiftyCommand', null, function (sender, args) {
    // Do something useful
};

iOS (Obj-C)

[[PWFramework sharedInstance].client queueCommand:@"NiftyCommand" withParameters:nil onComplete:^(PWCommandResponseEventArgs *args) 
{
    // Do something useful
}];

Android

framework.getWebClient().queueCommand("NiftyCommand", new MyCallbackFunction());

(...)

MyCallbackFunction implements EventHandler<CommandResponseEventArgs>
{
    public void invoke(Object source, CommandResponseEventArgs args)
    {
        // Do something useful
    }
}					


Read from the response object

APIs:

CommandResponseEventArgs.getResponse() | HTML5 | Android
PWCommandResponseEventArgs.response() | iOS

XmlUtility | HTML5 | Android
PWXmlUtility | iOS

If the callback function requires response parameters from the service, you can get the parsed command response by calling the getResponse method on the CommandResponseEventArgs object. The response will be expressed as an XML element.

The APIs provide the XmlUtility class to manipulate XML elements. In particular, you'll find the getText method, to get the value of an element as a string, and the getTextAs method, to get the value converted to a different data type.

When reading from the responses object, all the elements are considered children of the root response element.

In the snippets below, we assume that the service has provided a response with an element called ServiceResponseKey. The code illustrates both the getText and getTextAs methods. In the latter case, the value is converted to an integer.

HTML5

To get the value for the ServiceResponseKey element:

pureweb.xml.XmlUtility.getText({parent: args.getResponse(), childPath: '/ServiceResponseKey'});

To get the value for ServiceResponseKey element, converted to an integer:

pureweb.xml.XmlUtility.getTextAs({parent: args.getResponse(), childPath: '/ServiceResponseKey'}, Number);

iOS (Obj-C)

To get the value for ServiceResponseKey element:

[args.response getText:@"ServiceResponseKey"];

To get the value for the ServiceResponseKey element, converted to an integer:

[[args.response elementForName:@"ServiceResponseKey"] getTextAs:@encode(int)];

Android

To get the value for the ServiceResponseKey element:

XmlUtility.getText(args.getResponse(), "ServiceResponseKey");

To get the value for the ServiceResponseKey element, converted to an integer:

XmlUtility.getTextAs(Integer.class, args.getResponse(), "ServiceResponseKey");