HERE iOS SDK Developer's Guide

NMACLE2Task

Class Summary

class NMACLE2Task

Derived from: <__covariant ResultType>, <__covariant ResultType>

Encapsulates asynchronous CLE2 task (that usually involves network communication and/or database operations) and provides some common operations like observing, waiting for the result, cancelling or getting the result.

Include: NMAKit.framework/headers/NMACLE2DataManager.h

Inheritance Diagrams

Figure 1. Public inheritance diagram for NMACLE2Task

[For complete information, see the section Class Details]

Private Enumeration Summary

Table 1. Private Enumerations
Private Enumerations

NMACLE2OperationType

Indicates type of data operation that can be performed on CLE2 data.

NMACLE2StorageType

Used to make distinction between local storage and CLE service (server).

Public Property Summary

Table 2. Public Properties
Public Properties

[readable, assign] NSError *_Nullable  error

Holds status of last execution of this task

[readable, assign] BOOL  isFinished

Indicates whether this task has finished or not

[readable, assign] BOOL  isStarted

Indicates whether this task has been started or not

[readable, assign] ResultType _Nullable  result

Holds result of last execution of this task

Protected Variable Summary

Table 3. Protected Variables
Protected Variables

  __pad0__

Instance Method Summary

Table 4. Instance Methods
Instance Method Summary

-(void) cancel

Cancels a previously triggered request execution

-(void) startWithBlock:(void)(ResultType _Nullable result, NSError *_Nullable error)) listenerBlock

Starts this task in background thread with a supplied subscriber that will be called on the main thread once this task finishes

-(void) subscribeWithBlock:(void)(ResultType _Nullable result, NSError *_Nullable error)) subscriberBlock

Adds a subscriber to this task

-(void) unsubscribeBlock:(void)(ResultType _Nullable, NSError *_Nullable error)) subscriberBlock

Removes a supplied block from the list of this task's subscribers

-(void) waitForResult

Blocks until this task finishes

-(BOOL) waitForResult:(NSTimeInterval) timeout

Blocks until this task finishes or a specied timeout passes

Class Details

Encapsulates asynchronous CLE2 task (that usually involves network communication and/or database operations) and provides some common operations like observing, waiting for the result, cancelling or getting the result.

A typical use of a NMACLE2Task involves creating a task, subscribing to it for result and starting its execution. For convenience, it is possible to start and subscribe to the task with one call.

In the simplest scenario where only one subscriber is enough and there is no need to hold onto the task for later, it looks something like this: [[taskFactory doSomethingTask:param] startWithBlock:^(ResultType *result, NSError * error) { // process result of the task }];

NMACLE2Task does however provide some more advanced features. For example, if you are performing some background operation that at some point involves interacting with CLE2 in some way, an NMACLE2Task can be used in a synchronous manner by means of calling waitForResult method and then getting the result and error from the properties of the task.

Having multiple subscribers to the task is also possible.

And finally, since NMACLE2Task object represents a unit of work, it can be held onto for later use, passed around, run repeatedly multiple times (for example, retrying a failed operation) and of course, canceled.

Private Enumeration Details

NMACLE2OperationType

Indicates type of data operation that can be performed on CLE2 data.

Enumeration Members:

  • NMACLE2OperationTypeCreate

    Indicates an operation that creates new data.

  • NMACLE2OperationTypeUpdate

    Indicates an operation that updates existing data.

  • NMACLE2OperationTypeDelete

    Indicates an operation that deletes existing data.

NMACLE2StorageType

Used to make distinction between local storage and CLE service (server).

Enumeration Members:

  • NMACLE2StorageTypeLocal

    Indicates local storage.

  • NMACLE2StorageTypeRemote

    Indicates storage on remote CLE service.

Public Property Details

[readable, assign] NSError *_Nullable error

Holds status of last execution of this task.

[readable, assign] BOOL isFinished

Indicates whether this task has finished or not.

[readable, assign] BOOL isStarted

Indicates whether this task has been started or not. Note that a task that is finished has also been started.

[readable, assign] ResultType _Nullable result

Holds result of last execution of this task.

Protected Variable Details

 __pad0__

Instance Method Details

-(void) cancel

Cancels a previously triggered request execution. Cancelled requests will have their subscribers called with the respective NMACLE2Error.

Note:

Cancelling might not always be possible if the operation was already in an advanced stage, hence check the error code to determine actual fate of the task

-(void) startWithBlock:(void)(ResultType _Nullable result, NSError *_Nullable error)) listenerBlock

Starts this task in background thread with a supplied subscriber that will be called on the main thread once this task finishes. Starting a task that is already running has no effect. Starting a task that has already finished will start it once more.

-(void) subscribeWithBlock:(void)(ResultType _Nullable result, NSError *_Nullable error)) subscriberBlock

Adds a subscriber to this task. All subscribers are called on the main thread. A subscriber block will be called with the result of the operation and an error object that can be inspected to determine if the operation succeeded. Subscribing to a task that has already finished will cause the block to be called with the curently held (ie. last finished) result and error.

Parameters:

  • subscriberBlock

    A block that will be called when this task finishes

-(void) unsubscribeBlock:(void)(ResultType _Nullable, NSError *_Nullable error)) subscriberBlock

Removes a supplied block from the list of this task's subscribers.

Parameters:

  • subscriberBlock

    A block to remove from the list of subscribers

-(void) waitForResult

Blocks until this task finishes.

Note:

Trying to call this method on main thread will result in NSException being thrown

-(BOOL) waitForResult:(NSTimeInterval) timeout

Blocks until this task finishes or a specied timeout passes.

Note:

Only use this in a backgrounded thread.

Parameters:

  • timeout

    Specifies how long to wait for the task to finish

Returns:

YES if the task finishes within the specified time limit or if it was not running in the first place, NO if specified time limit went by without the task finishing