Subversion Repositories Applications.papyrus

if(!dojo._hasResource["dojo._base.Deferred"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.

dojo._hasResource["dojo._base.Deferred"] = true;

dojo.provide("dojo._base.Deferred");

dojo.require("dojo._base.lang");

dojo.Deferred = function(/*Function?*/ canceller){

	// summary:

	//		Encapsulates a sequence of callbacks in response to a value that

	//		may not yet be available.  This is modeled after the Deferred class

	//		from Twisted <http://twistedmatrix.com>.

	// description:

	//		JavaScript has no threads, and even if it did, threads are hard.

	//		Deferreds are a way of abstracting non-blocking events, such as the

	//		final response to an XMLHttpRequest. Deferreds create a promise to

	//		return a response a some point in the future and an easy way to

	//		register your interest in receiving that response.

	//

	//		The most important methods for Deffered users are:

	//

	//			* addCallback(handler)

	//			* addErrback(handler)

	//			* callback(result)

	//			* errback(result)

	//

	//		In general, when a function returns a Deferred, users then "fill

	//		in" the second half of the contract by registering callbacks and

	//		error handlers. You may register as many callback and errback

	//		handlers as you like and they will be executed in the order

	//		registered when a result is provided. Usually this result is

	//		provided as the result of an asynchronous operation. The code

	//		"managing" the Deferred (the code that made the promise to provide

	//		an answer later) will use the callback() and errback() methods to

	//		communicate with registered listeners about the result of the

	//		operation. At this time, all registered result handlers are called

	//		*with the most recent result value*.

	//

	//		Deferred callback handlers are treated as a chain, and each item in

	//		the chain is required to return a value that will be fed into

	//		successive handlers. The most minimal callback may be registered

	//		like this:

	//

	//		|	var d = new dojo.Deferred();

	//		|	d.addCallback(function(result){ return result; });

	//

	//		Perhaps the most common mistake when first using Deferreds is to

	//		forget to return a value (in most cases, the value you were

	//		passed).

	//

	//		The sequence of callbacks is internally represented as a list of

	//		2-tuples containing the callback/errback pair.  For example, the

	//		following call sequence:

	//

	//		|	var d = new dojo.Deferred();

	//		|	d.addCallback(myCallback);

	//		|	d.addErrback(myErrback);

	//		|	d.addBoth(myBoth);

	//		|	d.addCallbacks(myCallback, myErrback);

	//

	//		is translated into a Deferred with the following internal

	//		representation:

	//

	//		|	[

	//		|		[myCallback, null],

	//		|		[null, myErrback],

	//		|		[myBoth, myBoth],

	//		|		[myCallback, myErrback]

	//		|	]

	//

	//		The Deferred also keeps track of its current status (fired).  Its

	//		status may be one of three things:

	//

	//			* -1: no value yet (initial condition)

	//			* 0: success

	//			* 1: error

	//

	//		A Deferred will be in the error state if one of the following three

	//		conditions are met:

	//

	//			1. The result given to callback or errback is "instanceof" Error

	//			2. The previous callback or errback raised an exception while

	//			   executing

	//			3. The previous callback or errback returned a value

	//			   "instanceof" Error

	//

	//		Otherwise, the Deferred will be in the success state. The state of

	//		the Deferred determines the next element in the callback sequence

	//		to run.

	//

	//		When a callback or errback occurs with the example deferred chain,

	//		something equivalent to the following will happen (imagine

	//		that exceptions are caught and returned):

	//

	//		|	// d.callback(result) or d.errback(result)

	//		|	if(!(result instanceof Error)){

	//		|		result = myCallback(result);

	//		|	}

	//		|	if(result instanceof Error){

	//		|		result = myErrback(result);

	//		|	}

	//		|	result = myBoth(result);

	//		|	if(result instanceof Error){

	//		|		result = myErrback(result);

	//		|	}else{

	//		|		result = myCallback(result);

	//		|	}

	//

	//		The result is then stored away in case another step is added to the

	//		callback sequence.	Since the Deferred already has a value

	//		available, any new callbacks added will be called immediately.

	//

	//		There are two other "advanced" details about this implementation

	//		that are useful:

	//

	//		Callbacks are allowed to return Deferred instances themselves, so

	//		you can build complicated sequences of events with ease.

	//

	//		The creator of the Deferred may specify a canceller.  The canceller

	//		is a function that will be called if Deferred.cancel is called

	//		before the Deferred fires. You can use this to implement clean

	//		aborting of an XMLHttpRequest, etc. Note that cancel will fire the

	//		deferred with a CancelledError (unless your canceller returns

	//		another kind of error), so the errbacks should be prepared to

	//		handle that error for cancellable Deferreds.

	// example:

	//	|	var deferred = new dojo.Deferred();

	//	|	setTimeout(function(){ deferred.callback({success: true}); }, 1000);

	//	|	return deferred;

	// example:

	//		Deferred objects are often used when making code asynchronous. It

	//		may be easiest to write functions in a synchronous manner and then

	//		split code using a deferred to trigger a response to a long-lived

	//		operation. For example, instead of register a callback function to

	//		denote when a rendering operation completes, the function can

	//		simply return a deferred:

	//

	//		|	// callback style:

	//		|	function renderLotsOfData(data, callback){

	//		|		var success = false

	//		|		try{

	//		|			for(var x in data){

	//		|				renderDataitem(data[x]);

	//		|			}

	//		|			success = true;

	//		|		}catch(e){ }

	//		|		if(callback){

	//		|			callback(success);

	//		|		}

	//		|	}

	//

	//		|	// using callback style

	//		|	renderLotsOfData(someDataObj, function(success){

	//		|		// handles success or failure

	//		|		if(!success){

	//		|			promptUserToRecover();

	//		|		}

	//		|	});

	//		|	// NOTE: no way to add another callback here!!

	// example:

	//		Using a Deferred doesn't simplify the sending code any, but it

	//		provides a standard interface for callers and senders alike,

	//		providing both with a simple way to service multiple callbacks for

	//		an operation and freeing both sides from worrying about details

	//		such as "did this get called already?". With Deferreds, new

	//		callbacks can be added at any time.

	//

	//		|	// Deferred style:

	//		|	function renderLotsOfData(data){

	//		|		var d = new dojo.Deferred();

	//		|		try{

	//		|			for(var x in data){

	//		|				renderDataitem(data[x]);

	//		|			}

	//		|			d.callback(true);

	//		|		}catch(e){

	//		|			d.errback(new Error("rendering failed"));

	//		|		}

	//		|		return d;

	//		|	}

	//

	//		|	// using Deferred style

	//		|	renderLotsOfData(someDataObj).addErrback(function(){

	//		|		promptUserToRecover();

	//		|	});

	//		|	// NOTE: addErrback and addCallback both return the Deferred

	//		|	// again, so we could chain adding callbacks or save the

	//		|	// deferred for later should we need to be notified again.

	// example:

	//		In this example, renderLotsOfData is syncrhonous and so both

	//		versions are pretty artificial. Putting the data display on a

	//		timeout helps show why Deferreds rock:

	//

	//		|	// Deferred style and async func

	//		|	function renderLotsOfData(data){

	//		|		var d = new dojo.Deferred();

	//		|		setTimeout(function(){

	//		|			try{

	//		|				for(var x in data){

	//		|					renderDataitem(data[x]);

	//		|				}

	//		|				d.callback(true);

	//		|			}catch(e){

	//		|				d.errback(new Error("rendering failed"));

	//		|			}

	//		|		}, 100);

	//		|		return d;

	//		|	}

	//

	//		|	// using Deferred style

	//		|	renderLotsOfData(someDataObj).addErrback(function(){

	//		|		promptUserToRecover();

	//		|	});

	//

	//		Note that the caller doesn't have to change his code at all to

	//		handle the asynchronous case.

	this.chain = [];

	this.id = this._nextId();

	this.fired = -1;

	this.paused = 0;

	this.results = [null, null];

	this.canceller = canceller;

	this.silentlyCancelled = false;

};

dojo.extend(dojo.Deferred, {

	/*

	makeCalled: function(){

		// summary:

		//		returns a new, empty deferred, which is already in the called

		//		state. Calling callback() or errback() on this deferred will

		//		yeild an error and adding new handlers to it will result in

		//		them being called immediately.

		var deferred = new dojo.Deferred();

		deferred.callback();

		return deferred;

	},

	toString: function(){

		var state;

		if(this.fired == -1){

			state = 'unfired';

		}else{

			state = this.fired ? 'success' : 'error';

		}

		return 'Deferred(' + this.id + ', ' + state + ')';

	},

	*/

	_nextId: (function(){

		var n = 1;

		return function(){ return n++; };

	})(),

	cancel: function(){

		// summary:

		//		Cancels a Deferred that has not yet received a value, or is

		//		waiting on another Deferred as its value.

		// description:

		//		If a canceller is defined, the canceller is called. If the

		//		canceller did not return an error, or there was no canceller,

		//		then the errback chain is started.

		var err;

		if(this.fired == -1){

			if(this.canceller){

				err = this.canceller(this);

			}else{

				this.silentlyCancelled = true;

			}

			if(this.fired == -1){

				if(!(err instanceof Error)){

					var res = err;

					err = new Error("Deferred Cancelled");

					err.dojoType = "cancel";

					err.cancelResult = res;

				}

				this.errback(err);

			}

		}else if(	(this.fired == 0) &&

					(this.results[0] instanceof dojo.Deferred)

		){

			this.results[0].cancel();

		}

	},

	_resback: function(res){

		// summary:

		//		The private primitive that means either callback or errback

		this.fired = ((res instanceof Error) ? 1 : 0);

		this.results[this.fired] = res;

		this._fire();

	},

	_check: function(){

		if(this.fired != -1){

			if(!this.silentlyCancelled){

				throw new Error("already called!");

			}

			this.silentlyCancelled = false;

			return;

		}

	},

	callback: function(res){

		// summary:	Begin the callback sequence with a non-error value.

		/*

		callback or errback should only be called once on a given

		Deferred.

		*/

		this._check();

		this._resback(res);

	},

	errback: function(/*Error*/res){

		// summary:

		//		Begin the callback sequence with an error result.

		this._check();

		if(!(res instanceof Error)){

			res = new Error(res);

		}

		this._resback(res);

	},

	addBoth: function(/*Function||Object*/cb, /*Optional, String*/cbfn){

		// summary:

		//		Add the same function as both a callback and an errback as the

		//		next element on the callback sequence.	This is useful for code

		//		that you want to guarantee to run, e.g. a finalizer.

		var enclosed = dojo.hitch(cb, cbfn);

		if(arguments.length > 2){

			enclosed = dojo.partial(enclosed, arguments, 2);

		}

		return this.addCallbacks(enclosed, enclosed);

	},

	addCallback: function(cb, cbfn){

		// summary:

		//		Add a single callback to the end of the callback sequence.

		var enclosed = dojo.hitch(cb, cbfn);

		if(arguments.length > 2){

			enclosed = dojo.partial(enclosed, arguments, 2);

		}

		return this.addCallbacks(enclosed, null);

	},

	addErrback: function(cb, cbfn){

		// summary:

		//		Add a single callback to the end of the callback sequence.

		var enclosed = dojo.hitch(cb, cbfn);

		if(arguments.length > 2){

			enclosed = dojo.partial(enclosed, arguments, 2);

		}

		return this.addCallbacks(null, enclosed);

	},

	addCallbacks: function(cb, eb){

		// summary:

		//		Add separate callback and errback to the end of the callback

		//		sequence.

		this.chain.push([cb, eb])

		if(this.fired >= 0){

			this._fire();

		}

		return this;

	},

	_fire: function(){

		// summary:

		//		Used internally to exhaust the callback sequence when a result

		//		is available.

		var chain = this.chain;

		var fired = this.fired;

		var res = this.results[fired];

		var self = this;

		var cb = null;

		while(

			(chain.length > 0) &&

			(this.paused == 0)

		){

			// Array

			var f = chain.shift()[fired];

			if(!f){ continue; }

			try{

				res = f(res);

				fired = ((res instanceof Error) ? 1 : 0);

				if(res instanceof dojo.Deferred){

					cb = function(res){

						self._resback(res);

						// inlined from _pause()

						self.paused--;

						if(

							(self.paused == 0) &&

							(self.fired >= 0)

						){

							self._fire();

						}

					}

					// inlined from _unpause

					this.paused++;

				}

			}catch(err){

				console.debug(err);

				fired = 1;

				res = err;

			}

		}

		this.fired = fired;

		this.results[fired] = res;

		if((cb)&&(this.paused)){

			// this is for "tail recursion" in case the dependent

			// deferred is already fired

			res.addBoth(cb);

		}

	}

});

}