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.

---