GZ/nwyj/.svn/pristine/8f/8fa9184b2591eef2d968fdd538ca4354803866b4.svn-base

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);
					}
				}
			});

}