Esri Business Analyst Online API for Flex - Executing a Single Task

A Business Analyst Online task class is responsible for executing a concrete Business Analyst Online API task. For example, the GetReportTemplatesTask class instance executes the Get Report Templates task; the SimpleRingsTask class instance executes the Simple Rings task; and so on. Different task classes differ in the types of input parameters and in the types of results received.

Creating an instance of task

The public interface of a Business Analyst Online task is very similar to the interface of tasks from ArcGIS API for Flex, except for the additional tokenProvider property. You can create a Business Analyst Online task in the same way that you would create an ArcGIS task. To make a task class instance ready for execution, specify a base URL to the Business Analyst Online web service and an authentication token and/or token provider. You can specify the URL in the parameters of the constructor or assign it later.

The code snippet below shows an example of creating a Business Analyst Online task with the assumption that a token provider was created earlier. See Getting authenticated for details.

var task:GetReportTemplatesTask = new GetReportTemplatesTask();
task.url = "http://baoapi.esri.com";
task.tokenProvider = tokenProvider;

Using the BAOnlineClient class

Every Business Analyst Online task class contains one task-specific property, lastResult, which receives a result of the last successful execution of this task. It also encapsulates an instance of the BAOnlineClient class. See the Business Analyst Online task diagram for details. All other properties of a Business Analyst Online task class instance are proxies to corresponding properties of the encapsulated BAOnlineClient class instance. Setting a property value on a task instance, e.g. the tokenProvider property value is actually being set on the underlying BAOnlineClient class instance.

If an application works with many Business Analyst Online tasks, specifying an URL and token/tokenProvider properties for every task is inconvenient. Instead, you can create one instance of the BAOnlineClent class, specify all required properties, and then create concrete tasks passing this instance in the constructor’s parameter.

The code snippet below shows an example of creating a Business Analyst Online task using an instance of the BAOnlineClient class. As you can see, a task created this way is ready for execution after construction assuming that a token provider was created earlier. See Getting authenticated for details.

var client:BAOnlineClient = new BAOnlineClent();
client.url = "http://baoapi.esri.com";
client.tokenProvider = tokenProvider;

var task:GetReportTemplatesTask = new GetReportTemplatesTask(client);

Executing a simple task

HTTP requests in Flex are executed asynchronously. To get a result back from executing a Business Analyst Online task, you need to specify result and fault handlers for the task. The code snippet below shows how the callback functions can be specified.

import com.esri.bacore.BATaskCompletedEvent;
import mx.rpc.events.FaultEvent;

public class SampleCallback
{
    public static function result(event:BATaskCompletedEvent):void
    {
        // Specify actions to be applied on result ...
    }

    public static function fault(event:FaultEvent):void
    {
        // Specify actions to be applied on fault ...
    }
}

There are two ways for associating callback functions with a task to be executed—as event listeners or as responders.

The code snippet below shows how to associate callback functions with a Business Analyst Online task as event listeners and execute the task. Assume that an instance of the BAOnlineClient class is already created (see above).

var task:GetReportTemplatesTask = new GetReportTemplatesTask(client);
task.addEventListener(BATaskCompletedEvent.COMPLETE, SampleCallback.result);
task.addEventListener(FaultEvent.FAULT, SampleCallback.fault);
task.execute();

Callback functions registered on a task as event listeners will receive control on a response after every execution of this task. Alternatively, you can specify callback functions for a concrete execution of a task using the optional responder parameter.

var task:GetReportTemplatesTask = new GetReportTemplatesTask(client);
task.execute(new Responder(SampleCallback.result, SampleCallback.fault));

You can use both methods simultaneously. Moreover, you can add a responder (or a number of responders) right after the execute method instead of specifying it in parameters of this method.

var task:GetReportTemplatesTask = new GetReportTemplatesTask(client);
var asyncToken:AsyncToken = task.execute();
asyncToken.addResponder(new Responder(SampleCallback.result, SampleCallback.fault));

When the result or fault is received, the responders, if specified, are notified at first. After that, the event listeners are notified.

Executing a complex task

The GetReportTemplatesTask is an example of a simple task since the execute method of the GetReportTemplatesTask class has no task-specific parameters. On the other hand, the SimpleRingsTask is an example of a complex task. Its execute method requires as its first parameter an instance of the SimpleRingsParameters class. The second responder parameter is optional.

To execute a complex task, you need to instantiate its parameters class and populate it with appropriate values. Some complex tasks can produce a complex output, e.g. the Simple Rings task produces an instance of the TaskResultOutput class which can contain a feature record set, a map image, and a number of report info objects. To select output types to be received, the outputTypes property values are specified in the input parameters of the task.

The code example below shows some implementation details on preparing parameters for the Simple Rings task. The rest of the parameters can be specified where the ellipsis “…” is shown.

var parameters:SimpleRingsParameters = new SimpleRingsParameters();
parameters.outputTypes.getFeatureClass = true;
parameters.outputTypes.getMapImage = true;
parameters.outputTypes.getReport = true;
// ...

var task:SimpleRingsTask = new SimpleRingsTask(client);
task.execute(parameters, new Responder(SampleCallback.result, SampleCallback.fault));

In this example, all allowed output types are requested. Note that report options should be specified in the parameters when the “get report” output is requested. If output types are not specified, the default parameter values are used. See the Reference section for more details.

Executing a task with the BAOnlineGenericTask class

A Business Analyst Online task can be executed in two ways: with a concrete task class and with the BAOnlineGenericTask class. The example above for executing the Simple Rings task can be modified as follows:

var parameters:SimpleRingsParameters = new SimpleRingsParameters();
// ...

var task:BAOnlineGenericTask = new BAOnlineGenericTask(client);
task.execute(parameters, new Responder(SampleCallback.result, SampleCallback.fault));

The parameters instance of the execute method for this task is any data type implementing the IBATaskParameters interface. Classes of parameters for complex tasks implement this interface, but there are no specific classes of parameters for simple tasks. To execute a simple task with the generic task class, use the static createParameters method of a simple task class. The code snippet below shows how to execute the Get Report Templates task using the generic task.

var parameters:IBATaskParameters = GetReportTemplatesTask.createParameters();
var task:BAOnlineGenericTask = new BAOnlineGenericTask(client);
task.execute(parameters, new Responder(SampleCallback.result, SampleCallback.fault));

Using the BACommand class

The BACommand class encapsulates an instance of a task class together with parameters for the task to be executed. It allows you to separate the preparation of the task from its execution. Once you have created an instance of the BACommand class, you can execute it later.

The code snippet below shows how to create commands for executing complex and simple tasks.

var parameters:SimpleRingsParameters = new SimpleRingsParameters();
// ...
var command1:BACommand = new SimpleRingsTask(client).createCommand(parameters);
var command2:BACommand = new GetReportTemplatesTask(client).createCommand();

You can also pass an optional commandName parameter in parameters of the createCommand method in order to identify the created command with a specific name.

When created, the command can be executed in the same way as a task is executed. You can associate callback functions with a command as event listeners.

var parameters:SimpleRingsParameters = new SimpleRingsParameters();
// ...
var command:BACommand = new SimpleRingsTask(client).createCommand(parameters);
command.addEventListener(BATaskCompletedEvent.COMPLETE, SampleCallback.result);
command.addEventListener(FaultEvent.FAULT, SampleCallback.fault);
command.execute();

You can also pass a responder in the parameters of the execute method.

var command:BACommand = new GetReportTemplatesTask(client).createCommand();
command.execute(new Responder(SampleCallback.result, SampleCallback.fault));

You can also add responders after the execute method.

var command:BACommand = new GetReportTemplatesTask(client).createCommand();
var asyncToken:AsyncToken = command.execute();
asyncToken.addResponder(new Responder(SampleCallback.result, SampleCallback.fault));

You can also wrap execution of any asynchronous request with the BACommand class. The code snippet below shows how to wrap the ArcGIS find task with the BACommand.

import com.esri.ags.tasks.FindTask;
import com.esri.ags.tasks.FindParameters;
import com.esri.bacore.client.BACommand;
import mx.rpc.IResponder;

public class ToBACommand
{
    public static function CreateFindCommand(
        task:FindTask,
        parameters:FindParameters,
        commandName:String=null
    ):BACommand
    {
        return new BACommand(commandName, "Find",
            function(responder:IResponder):void
            {
                task.execute(parameters, responder);
            }
        );
    }
}