IToken  - AS3 ADEP Client Component

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.