GODPAPER | All Packages | All Classes | Index | Frames No Frames |
Task

Package | org.spicefactory.lib.task
Class | public class Task
Inheritance | Task flash.events.EventDispatcher
Subclasses | CleanUpChessPieceTask, CleanUpPiecesBitboardTask, DelegateTask, ResultTask, SynchronousDelegateTask, TaskGroup

Abstract base class of the Task Framework representing an asynchronous operation. This may be an animation, a loading operation, a remote call, WebService invocation or playback of Video/Audio or anything else with asynchronous nature. The concrete functionality (loading, animating, etc.) would be implemented in a subclass of Task. That alone does not generate added value. But thanks to the generic set of events fired by Task implementations (`START`, `SUSPEND`, `RESUME`, `CANCEL`, `COMPLETE` and `ERROR`), multiple Tasks can be chained in a `SequentialTaskGroup` or executed concurrently in a `ConcurrentTaskGroup`. Both classes fire their `COMPLETE` event when all their child Tasks have completed and both extend the abstract `TaskGroup` class. Since `TaskGroup` is a subclass of Task itself, it can be nested too. This type of nesting can be cumbersome to implement without Tasks if you work with a lot of different types of asynchronous operations which all have their individual event sets for notifying observers that they have completed or that an error occured.

A minimal subclass of Task would at least overwrite the `doStart` method, do its work and then call `complete` when the operation is done. The Task class comes with several properties to control the behaviour. A Task can be `restartable` or `cancelable`, if the `suspendable` property is true, a Task can be suspended and resumed. If the `skippable` property is set, a Task can be forced to move to its final state (which may make sense in asynchronous operations like animations, but obviously not in Tasks like loading operations). All these properties are true by default and are protected so they must be set by subclasses.

You can also set a timeout for the operation or assign it a name for log output.

Public Properties

| Property | Defined By
--- | --- | ---
|  | cancelable : Boolean [read-only] Indicates whether this Task can be cancelled. | Task
|  | data : * An arbitrary value associated with this Task. | Task
|  | parent : TaskGroup [read-only] The parent of this Task. | Task
|  | restartable : Boolean [read-only] Indicates whether this Task can be restarted. | Task
|  | root : Task [read-only] The root TaskGroup in case this Task is nested in one or more TaskGroups. | Task
|  | skippable : Boolean [read-only] Indicates whether this Task can be forced to skip to its final state. | Task
|  | state : TaskState [read-only] The current state of this Task. | Task
|  | suspendable : Boolean [read-only] Indicates whether this Task can be suspended. | Task
|  | timeout : uint [read-only] The timeout for this Task in milliseconds. | Task

Public Methods

| Method | Defined By
--- | --- | ---
|  | cancel():Boolean Cancels this Task. | Task
|  | resume():Boolean Resumes this Task if it is suspended. | Task
|  | skip():Boolean Forces this Task to move to its final state. | Task
|  | start():Boolean Starts this Task. | Task
|  | suspend():Boolean Suspends this Task. | Task

Protected Methods

| Method | Defined By
--- | --- | ---
|  | complete():Boolean Signals that this Task has completed. | Task
|  | doCancel():void Called before the CANCEL event gets fired. | Task
|  | doError(message:String):void Called before the ERROR event gets fired. | Task
|  | doResume():void Called before the RESUME event gets fired. | Task
|  | doSkip():void Called after skip has been called but before the COMPLETE event gets fired. | Task
|  | doStart():void Called before the START event gets fired. | Task
|  | doSuspend():void Called before the SUSPEND event gets fired. | Task
|  | doTimeout():void Called before the ERROR event gets fired after a timeout occurred. | Task
|  | error(message:String):Boolean Signals an error condition and cancels the Task. | Task
|  | setCancelable(value:Boolean):void Specifies whether this Task can be cancelled. | Task
|  | setName(name:String):void Sets the name of this Task. | Task
|  | setRestartable(value:Boolean):void Specifies whether this Task can be restarted. | Task
|  | setSkippable(value:Boolean):void Specifies whether this Task can be forced to skip to its final state. | Task
|  | setSuspendable(value:Boolean):void Specifies whether this Task can be suspended. | Task
|  | setTimeout(value:uint):void Sets the timeout for this Task in milliseconds. | Task

Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | cancel | Dispatched when a Task is cancelled. | Task
|  | complete | Dispatched when a Task has completed its execution. | Task
|  | error | Dispatched when a Task has aborted due to an error condition. | Task
|  | resume | Dispatched when a suspended Task is resumed. | Task
|  | start | Dispatched when a Task is started. | Task
|  | suspend | Dispatched when a Task is suspended. | Task

Property Detail

cancelable | property

`cancelable:Boolean` [read-only]

Indicates whether this Task can be cancelled.

Implementation
`public function get cancelable():Boolean`

data | property |

`data:*`

An arbitrary value associated with this Task. This may be useful if a Task is nested in a `TaskGroup` for example and produces or loads data that is needed by subsequent Tasks. If the value for this Task is null and the Task has a parent, the parents data value will be used.

Implementation
`public function get data():*`
`public function set data(value:any):void`

parent | property |

`parent:TaskGroup` [read-only]

The parent of this Task. The value is null if this Task is not nested in a `TaskGroup`.

Implementation
`public function get parent():TaskGroup`

restartable | property |

`restartable:Boolean` [read-only]

Indicates whether this Task can be restarted. If true the `start` method can be invoked again after either the `COMPLETE`, `CANCEL` or `ERROR` events were fired. If it is false calling `start` after these event were fired will cause an Error to be thrown.

Implementation
`public function get restartable():Boolean`

root | property |

`root:Task` [read-only]

The root TaskGroup in case this Task is nested in one or more TaskGroups. If this Task is not nested then this property points to the Task itself.

Implementation
`public function get root():Task`

skippable | property |

`skippable:Boolean` [read-only]

Indicates whether this Task can be forced to skip to its final state. This may be useful in asynchronous operations like animations, but not in Tasks like loading operations. For the difference between `cancelable` and `skippable` see skip().

Implementation
`public function get skippable():Boolean`

state | property |

`state:TaskState` [read-only]

The current state of this Task.

Implementation
`public function get state():TaskState`

suspendable | property |

`suspendable:Boolean` [read-only]

Indicates whether this Task can be suspended.

Implementation
`public function get suspendable():Boolean`

timeout | property |

`timeout:uint` [read-only]

The timeout for this Task in milliseconds. A value of 0 disables the timeout.

Implementation
`public function get timeout():uint`
Method Detail

cancel | () | method

`public function cancel():Boolean`

Cancels this Task. For this method to succeed the cancelable property of this Task must be set to true and the current state of the Task must be `ACTIVE` or `SUSPENDED`. If this method executes successfully the `CANCEL` event will be fired.

Returns

| `Boolean` — true if the Task successfully switched its internal state, false if otherwise

complete | () | method |

`protected function complete():Boolean`

Signals that this Task has completed. Subclasses should call this method when the asynchronous operation has completed. If this method executes successfully the `COMPLETE` event will be fired.

Returns

| `Boolean` — true if the Task successfully switched its internal state, false if otherwise

doCancel | () | method |

`protected function doCancel():void`

Called before the `CANCEL` event gets fired. Subclasses for cancelable Tasks should overwrite this method and cancel the actual operation this Task performs.

doError | () | method |

`protected function doError(message:String):void`

Called before the `ERROR` event gets fired. Subclasses may optionally overwrite this method to do some cleanup.

Parameters

| `message:String`

doResume | () | method |

`protected function doResume():void`

Called before the `RESUME` event gets fired. Subclasses for suspendable Tasks should overwrite this method and resume the suspended operation this Task performs.

doSkip | () | method |

`protected function doSkip():void`

Called after `skip` has been called but before the `COMPLETE` event gets fired. Subclasses for skippable Tasks should overwrite this method and put this Task into its final state.

doStart | () | method |

`protected function doStart():void`

Called before the `START` event gets fired. Subclasses should overwrite this method to start with the actual operation this Task should perform.

doSuspend | () | method |

`protected function doSuspend():void`

Called before the `SUSPEND` event gets fired. Subclasses for suspendable Tasks should overwrite this method and suspend the actual operation this Task performs.

doTimeout | () | method |

`protected function doTimeout():void`

Called before the `ERROR` event gets fired after a timeout occurred. Subclasses should overwrite this method and cancel the operation this Task performs. In many cases this method can be handled the same way like the `doCancel` hook.

error | () | method |

`protected function error(message:String):Boolean`

Signals an error condition and cancels the Task. Subclasses should call this method when the asynchronous operation cannot be successfully completed. If this method executes successfully the `ERROR` event will be fired.

Parameters

| `message:String` — the error description

Returns

| `Boolean` — true if the Task successfully switched its internal state, false if otherwise

resume | () | method |

`public function resume():Boolean`

Resumes this Task if it is suspended. For this method to succeed the suspendable property of this Task must be set to true and the current state of the Task must be `SUSPENDED`. If this Task is member of a `TaskGroup` it cannot be resumed if the parent `TaskGroup` is still suspended. If this method executes successfully the `RESUME` event will be fired.

Returns

| `Boolean` — true if the Task successfully switched its internal state, false if otherwise

setCancelable | () | method |

`protected function setCancelable(value:Boolean):void`

Specifies whether this Task can be cancelled.

Parameters

| `value:Boolean` — whether this Task can be cancelled

setName | () | method |

`protected function setName(name:String):void`

Sets the name of this Task. This name will not be used internally by the Task Framework except for log output.

Parameters

| `name:String` — the new name of this Task

setRestartable | () | method |

`protected function setRestartable(value:Boolean):void`

Specifies whether this Task can be restarted. If true the `start` method can be invoked again after either the `COMPLETE`, `CANCEL` or `ERROR` events were fired. If it is false calling `start` after these event were fired will cause an Error to be thrown.

Parameters

| `value:Boolean` — whether this Task can be restarted

setSkippable | () | method |

`protected function setSkippable(value:Boolean):void`

Specifies whether this Task can be forced to skip to its final state. This may be useful in asynchronous operations like animations, but not in Tasks like loading operations.

Parameters

| `value:Boolean` — whether this Task can be forced to skip/move to its final state

setSuspendable | () | method |

`protected function setSuspendable(value:Boolean):void`

Specifies whether this Task can be suspended.

Parameters

| `value:Boolean` — whether this Task can be suspended

setTimeout | () | method |

`protected function setTimeout(value:uint):void`

Sets the timeout for this Task in milliseconds. A value of 0 disables the timeout.

Parameters

| `value:uint` — the timeout for this Task in milliseconds

skip | () | method |

`public function skip():Boolean`

Forces this Task to move to its final state. If this method executes successfully the `COMPLETE` event will be fired. The method is somewhat similar to the `cancel` method but with a few subtle differences:

- The semantics of `cancel` would imply that the asynchronous operation just aborts and optionally rewinds to its initial state. In constrast the semantics of `skip` would rather imply to move the operation to its final state and skip the remaining progress. This is applicable for operations like animations, but obviously not feasible in Tasks like loading operations.
- To underline the different semantics the `cancel` method would cause a `CANCEL` event to be fired, while the `skip` method would just cause a `COMPLETE` event to be fired as if the Task completed normally.

Returns

| `Boolean` — true if the Task successfully switched its internal state, false if otherwise

start | () | method |

`public function start():Boolean`

Starts this Task. If this Task is member of a TaskGroup this method should not be called by application code.

Returns

| `Boolean` — true if the Task was started successfully, false if it was in an illegal state

suspend | () | method |

`public function suspend():Boolean`

Suspends this Task. For this method to succeed the suspendable property of this Task must be set to true and the current state of the Task must be `ACTIVE`. If this method executes successfully the `SUSPEND` event will be fired.

Returns

| `Boolean` — true if the Task successfully switched its internal state, false if otherwise

Event Detail

cancel | Event

Event Object Type: `org.spicefactory.lib.task.events.TaskEvent`
TaskEvent.type property = `org.spicefactory.lib.task.events.TaskEvent.CANCEL`

Dispatched when a Task is cancelled.

Constant for the type of event fired when a Task is cancelled.

complete | Event |

Event Object Type: `org.spicefactory.lib.task.events.TaskEvent`
TaskEvent.type property = `org.spicefactory.lib.task.events.TaskEvent.COMPLETE`

Dispatched when a Task has completed its execution.

Constant for the type of event fired when a Task is completed.

error | Event |

Event Object Type: `flash.events.ErrorEvent`
ErrorEvent.type property = `flash.events.ErrorEvent.ERROR`

Dispatched when a Task has aborted due to an error condition.

resume | Event |

Event Object Type: `org.spicefactory.lib.task.events.TaskEvent`
TaskEvent.type property = `org.spicefactory.lib.task.events.TaskEvent.RESUME`

Dispatched when a suspended Task is resumed.

Constant for the type of event fired when a Task is resumed.

start | Event |

Event Object Type: `org.spicefactory.lib.task.events.TaskEvent`
TaskEvent.type property = `org.spicefactory.lib.task.events.TaskEvent.START`

Dispatched when a Task is started.

Constant for the type of event fired when a Task is started.

suspend | Event |

Event Object Type: `org.spicefactory.lib.task.events.TaskEvent`
TaskEvent.type property = `org.spicefactory.lib.task.events.TaskEvent.SUSPEND`

Dispatched when a Task is suspended.

Constant for the type of event fired when a Task is suspended.

Thu Jan 16 2014, 01:11 PM +08:00