Overview

Tasks are the foundation of the geospatial functionality in your iOS applications. Using tasks in your application, users can interact with maps, find and display reports of real world objects, collect geographic information and analyze what they see on a map.

The API includes the following task:

• Query Task - get features from map services that satisfy attribute or spatial queries.
• Identify Task - get features from map services at a location.
• Find Task - get features from map services that contain a particular value in their attributes.
• GeometryService Task - perform geometric operations such as buffering, projecting, and simplifying.
• Geoprocessor - do complex GIS analysis by executing geoprocessing models that have been published as geoprocessing services
• Locator - match locations to addresses and vice-versa
• Route Task - compute point-to-point or multi-point routes and driving directions

Working with Tasks

All tasks inherit from AGSTask. Working with tasks is simple once the pattern is understood. All tasks follow the same basic principals and pattern. Tasks are wrappers around operations supported by ArcGIS Server REST web services . Tasks take care of asynchronously sending the request, showing the network activity indicator, applying appropriate credentials to the network resource and parsing the results.

To execute a task, you typically work through the following pattern:

• Instantiate
• Set delegate
• Retain
• Kick-off operation
• Wait for delegate to be fired

Instantiate

Since the tasks inherit from AGSTask, they all have the following initializers: initWithURL and initWithURL:credential. Since tasks rely on operations of ArcGIS Server REST web services, you must instantiate them with a URL. Some services will be secured and will require credentials.

Set delegate

Since tasks work asynchronously, the calling object will want to be notified when the task succeeds or fails. This is where the delegate comes in to play. The delegate is an object that you assign to the task, that the task can call well-known methods on (defined by some protocol). Typically each operation that the task can execute will have a success method and a failure method. For example the AGSQueryTaskDelegate has the following methods:

- (void)queryTask:(AGSQueryTask *)queryTask operation:(NSOperation*)op didExecuteWithFeatureSetResult:(AGSFeatureSet *)featureSet; 

- (void)queryTask:(AGSQueryTask *)queryTask operation:(NSOperation*)op didFailWithError:(NSError *)error;

Notice, there are 2 methods (1 success and 1 fail) for the query operation. When you set yourself as a delegate, you can choose to implement these methods, if they are important for you.

Retain

Retaining the task is important. Since the task executes asynchronously, and kicking off the operations is a non-blocking call, you must retain your task. Creating a retain property for your task is one simple and effective way to do this. The reason is that if the task is deallocated before the operation completes, it will not be able to call back the delegate.

Kick-off operation

To kick-off an operation on the task, you simply call the method of the operation you want to execute. For example, the AGSQuery task has the following method:

-(NSOperation *)executeWithQuery:(AGSQuery *)query;

Tasks will return the operation that they kick off, so that you can cancel it at anytime. You can also associate these operations with some state, so that you can track which operations you kicked off. You can kick off as many operations as you'd like, even on a single task. For example, you can have one query task that executes 5 queries simultaneously.

Wait for delegate to be fired

After kicking off an operation, you can wait for the delegate to be notified of its success or failure. The task will take care of showing the network activity indicator for you while the operation is executing. If an operation fails, it could be because the proper credentials were not supplied, the inputs were not valid, or because of some other reason.. You can check the NSError object that is returned to find out the exact cause of the error.