com.adobe.gravity.utility.async

# IToken - AS3 ADEP Client Component

Package | com.adobe.gravity.utility.async
Interface | public interface IToken
Implementors | AggregatingToken, AsyncTokenWrapper, ImmediateFaultToken, ImmediateSuccessToken, Token

Language Version: | ActionScript 3.0

Product Version: | Adobe Digital Enterprise Platform Experience Services - Client Component Framework 10

Runtime Versions: | AIR 1.1, Flash Player 9

IToken objects are returned from functions that initiate asynchronous operations. You are guaranteed that either the fault handlers or the success handlers will be invoked, depending on whether the operation succeeded or failed.

Success handlers take an arbitrary number of parameters. The number and type of the parameters depend on the API that returns the token; the API documentation will generally indicate what to expect. Fault handlers must take a single parameter of type Error.

The asynchronous token concept: the classes in this package implement the asynchronous token concept. Instead of calling asynchronous methods on an object and adding event listeners to that object to learn the result, a token is returned from the asynchronous method and success and fault handlers are added to the token.

For example, in the traditional Flash model one might have:

    	 public function addPhotoToLibrary(photoUrl:String, library:PhotoLibrary):void
    	 {
    	    library.importPhoto(photoUrl);
    	    library.addEventHandler(PhotoLibraryEvent.IMPORT_COMPLETE, importCompleteHandler);
    	    library.addEventHandler(PhotoLibraryEvent.IMPORT_FAULT, importFaultHandler);
    	 }

    	 public function importCompleteHandler(event:PhotoLibraryEvent):void
    	 {
    	    library.removeEventHandler(PhotoLibraryEvent.IMPORT_COMPLETE, importCompleteHandler);
    	    library.removeEventHandler(PhotoLibraryEvent.IMPORT_FAULT, importFaultHandler);
    	    var photo:IPhoto = event.photo;
    	    // now that the photo has been imported, do something else
    	 }

    	 public function importFaultHandler(fault:FaultEvent):void
    	 {
    	 library.removeEventHandler(PhotoLibraryEvent.IMPORT_COMPLETE, importCompleteHandler);
    	 library.removeEventHandler(PhotoLibraryEvent.IMPORT_FAULT, importFaultHandler);
    	 // deal with the error here
    	 }

With a token, the pattern is slightly different:

    	 public function addPhotoToLibrary(photoUrl:String, library:PhotoLibrary):void
    	 {
    	    var token:IToken = library.importPhoto(photoUrl);
    	    token.addSuccessHandler(importCompleteHandler);
    	    token.addFaultHandler(importFaultHandler);
    	 }

    	 public function importCompleteHandler(photo:IPhoto):void
    	 {
    	    // now that the photo has been imported, do something else
    	 }

    	 public function importFaultHandler(error:Error):void
    	 {
    	 // deal with the error here
    	 }

The benefit of this model is that since the token is associated with a specific invocation of the operation, handlers added to that token will only get invoked for that specific operation invocation.

Public Methods

| Method | Defined By
--- | --- | ---
|  | addFaultHandler(handler:Function, weakReference:Boolean = false):void Add a handler to be called if the operation fails. | IToken
|  | addSuccessHandler(handler:Function, weakReference:Boolean = false):void Add a handler to be called if the operation succeeds. | IToken
|  | removeFaultHandler(handler:Function):void Remove a fault handler. | IToken
|  | removeSuccessHandler(handler:Function):void Remove a success handler. | IToken

Method Detail

### addFaultHandler

()
method

`public function addFaultHandler(handler:Function, weakReference:Boolean = false):void`

Language Version: | ActionScript 3.0

Product Version: | Adobe Digital Enterprise Platform Experience Services - Client Component Framework 10

Runtime Versions: | AIR 1.1, Flash Player 9

Add a handler to be called if the operation fails.

Parameters

| `handler:Function` — A function to be called if the operation fails.
| `weakReference:Boolean` (default = `false`)`` — Use a weak reference to hold onto the handler.

### addSuccessHandler

()
method

`public function addSuccessHandler(handler:Function, weakReference:Boolean = false):void`

Language Version: | ActionScript 3.0

Product Version: | Adobe Digital Enterprise Platform Experience Services - Client Component Framework 10

Runtime Versions: | AIR 1.1, Flash Player 9

Add a handler to be called if the operation succeeds.

Parameters

| `handler:Function` — A function to be called if the operation succeeds.
| `weakReference:Boolean` (default = `false`)`` — Use a weak reference to hold onto the handler.

### removeFaultHandler

()
method

`public function removeFaultHandler(handler:Function):void`

Language Version: | ActionScript 3.0

Product Version: | Adobe Digital Enterprise Platform Experience Services - Client Component Framework 10

Runtime Versions: | AIR 1.1, Flash Player 9

Remove a fault handler.

Parameters

| `handler:Function` — The handler to be removed.

### removeSuccessHandler

()
method

`public function removeSuccessHandler(handler:Function):void`

Language Version: | ActionScript 3.0

Product Version: | Adobe Digital Enterprise Platform Experience Services - Client Component Framework 10

Runtime Versions: | AIR 1.1, Flash Player 9

Remove a success handler.

Parameters

| `handler:Function` — The handler to remove.

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00