source: Dev/trunk/src/client/dojox/lang/aspect.js @ 532

dojo.provide("dojox.lang.aspect");

(function(){
        var d = dojo, aop = dojox.lang.aspect, ap = Array.prototype,
                contextStack = [], context;
                
        // this class implements a topic-based double-linked list
        var Advice = function(){
                this.next_before = this.prev_before =
                this.next_around = this.prev_around =
                this.next_afterReturning = this.prev_afterReturning =
                this.next_afterThrowing = this.prev_afterThrowing =
                        this;
                this.counter = 0;
        };
        d.extend(Advice, {
                add: function(advice){
                        var dyn = d.isFunction(advice),
                                node = {advice: advice, dynamic: dyn};
                        this._add(node, "before", "", dyn, advice);
                        this._add(node, "around", "", dyn, advice);
                        this._add(node, "after", "Returning", dyn, advice);
                        this._add(node, "after", "Throwing", dyn, advice);
                        ++this.counter;
                        return node;
                },
                _add: function(node, topic, subtopic, dyn, advice){
                        var full = topic + subtopic;
                        if(dyn || advice[topic] || (subtopic && advice[full])){
                                var next = "next_" + full, prev = "prev_" + full;
                                (node[prev] = this[prev])[next] = node;
                                (node[next] = this)[prev] = node;
                        }
                },
                remove: function(node){
                        this._remove(node, "before");
                        this._remove(node, "around");
                        this._remove(node, "afterReturning");
                        this._remove(node, "afterThrowing");
                        --this.counter;
                },
                _remove: function(node, topic){
                        var next = "next_" + topic, prev = "prev_" + topic;
                        if(node[next]){
                                node[next][prev] = node[prev];
                                node[prev][next] = node[next];
                        }
                },
                isEmpty: function(){
                        return !this.counter;
                }
        });

        var getDispatcher = function(){
        
                return function(){
                        
                        var self = arguments.callee,    // the join point
                                advices = self.advices,         // list of advices for this joinpoint
                                ret, i, a, e, t;

                        // push context
                        if(context){ contextStack.push(context); }
                        context = {
                                instance: this,                                 // object instance
                                joinPoint: self,                                // join point
                                depth: contextStack.length,             // current level of depth starting from 0
                                around: advices.prev_around,    // pointer to the current around advice
                                dynAdvices: [],                                 // array of dynamic advices if any
                                dynIndex: 0                                             // index of a dynamic advice
                        };

                        try{
                                // process before events
                                for(i = advices.prev_before; i != advices; i = i.prev_before){
                                        if(i.dynamic){
                                                // instantiate a dynamic advice
                                                context.dynAdvices.push(a = new i.advice(context));
                                                if(t = a.before){ // intentional assignment
                                                        t.apply(a, arguments);
                                                }
                                        }else{
                                                t = i.advice;
                                                t.before.apply(t, arguments);
                                        }
                                }

                                // process around and after events
                                try{
                                        // call the around advice or the original method
                                        ret = (advices.prev_around == advices ? self.target : aop.proceed).apply(this, arguments);
                                }catch(e){
                                        // process after throwing and after events
                                        context.dynIndex = context.dynAdvices.length;
                                        for(i = advices.next_afterThrowing; i != advices; i = i.next_afterThrowing){
                                                a = i.dynamic ? context.dynAdvices[--context.dynIndex] : i.advice;
                                                if(t = a.afterThrowing){ // intentional assignment
                                                        t.call(a, e);
                                                }
                                                if(t = a.after){ // intentional assignment
                                                        t.call(a);
                                                }
                                        }
                                        // continue the exception processing
                                        throw e;
                                }
                                // process after returning and after events
                                context.dynIndex = context.dynAdvices.length;
                                for(i = advices.next_afterReturning; i != advices; i = i.next_afterReturning){
                                        a = i.dynamic ? context.dynAdvices[--context.dynIndex] : i.advice;
                                        if(t = a.afterReturning){ // intentional assignment
                                                t.call(a, ret);
                                        }
                                        if(t = a.after){ // intentional assignment
                                                t.call(a);
                                        }
                                }
                                // process dojo.connect() listeners
                                var ls = self._listeners;
                                for(i in ls){
                                        if(!(i in ap)){
                                                ls[i].apply(this, arguments);
                                        }
                                }
                        }finally{
                                // destroy dynamic advices
                                for(i = 0; i < context.dynAdvices.length; ++i){
                                        a = context.dynAdvices[i];
                                        if(a.destroy){
                                                a.destroy();
                                        }
                                }
                                // pop context
                                context = contextStack.length ? contextStack.pop() : null;
                        }
                        
                        return ret;
                };
        };

        aop.advise = function(/*Object*/ obj,
                                                /*String|RegExp|Array*/ method,
                                                /*Object|Function|Array*/ advice
                                                ){
                // summary:
                //              Attach AOP-style advices to a method.
                //
                // description:
                //              Attaches AOP-style advices to a method. Can attach several
                //              advices at once and operate on several methods of an object.
                //              The latter is achieved when a RegExp is specified as
                //              a method name, or an array of strings and regular expressions
                //              is used. In this case all functional methods that
                //              satisfy the RegExp condition are processed. This function
                //              returns a handle, which can be used to unadvise, or null,
                //              if advising has failed.
                //
                //              This function is a convenience wrapper for
                //              dojox.lang.aspect.adviseRaw().
                //
                // obj:
                //              A source object for the advised function. Cannot be a DOM node.
                //              If this object is a constructor, its prototype is advised.
                //
                // method:
                //              A string name of the function in obj. In case of RegExp all
                //              methods of obj matching the regular expression are advised.
                //
                // advice:
                //              An object, which defines advises, or a function, which
                //              returns such object, or an array of previous items.
                //              The advice object can define following member functions:
                //              before, around, afterReturning, afterThrowing, after.
                //              If the function is supplied, it is called with a context
                //              object once per call to create a temporary advice object, which
                //              is destroyed after the processing. The temporary advice object
                //              can implement a destroy() method, if it wants to be called when
                //              not needed.
                
                if(typeof obj != "object"){
                        obj = obj.prototype;
                }

                var methods = [];
                if(!(method instanceof Array)){
                        method = [method];
                }
                
                // identify advised methods
                for(var j = 0; j < method.length; ++j){
                        var t = method[j];
                        if(t instanceof RegExp){
                                for(var i in obj){
                                        if(d.isFunction(obj[i]) && t.test(i)){
                                                methods.push(i);
                                        }
                                }
                        }else{
                                if(d.isFunction(obj[t])){
                                        methods.push(t);
                                }
                        }
                }

                if(!d.isArray(advice)){ advice = [advice]; }

                return aop.adviseRaw(obj, methods, advice);     // Object
        };
        
        aop.adviseRaw = function(/*Object*/ obj,
                                                /*Array*/ methods,
                                                /*Array*/ advices
                                                ){
                // summary:
                //              Attach AOP-style advices to methods.
                //
                // description:
                //              Attaches AOP-style advices to object's methods. Can attach several
                //              advices at once and operate on several methods of the object.
                //              The latter is achieved when a RegExp is specified as
                //              a method name. In this case all functional methods that
                //              satisfy the RegExp condition are processed. This function
                //              returns a handle, which can be used to unadvise, or null,
                //              if advising has failed.
                //
                // obj:
                //              A source object for the advised function.
                //              Cannot be a DOM node.
                //
                // methods:
                //              An array of method names (strings) to be advised.
                //
                // advices:
                //              An array of advices represented by objects or functions that
                //              return such objects on demand during the event processing.
                //              The advice object can define following member functions:
                //              before, around, afterReturning, afterThrowing, after.
                //              If the function is supplied, it is called with a context
                //              object once per call to create a temporary advice object, which
                //              is destroyed after the processing. The temporary advice object
                //              can implement a destroy() method, if it wants to be called when
                //              not needed.

                if(!methods.length || !advices.length){ return null; }
                
                // attach advices
                var m = {}, al = advices.length;
                for(var i = methods.length - 1; i >= 0; --i){
                        var name = methods[i], o = obj[name], ao = new Array(al), t = o.advices;
                        // create a stub, if needed
                        if(!t){
                                var x = obj[name] = getDispatcher();
                                x.target = o.target || o;
                                x.targetName = name;
                                x._listeners = o._listeners || [];
                                x.advices = new Advice;
                                t = x.advices;
                        }
                        // attach advices
                        for(var j = 0; j < al; ++j){
                                ao[j] = t.add(advices[j]);
                        }
                        m[name] = ao;
                }
                
                return [obj, m];        // Object
        };

        aop.unadvise = function(/*Object*/ handle){
                // summary:
                //              Detach previously attached AOP-style advices.
                //
                // handle:
                //              The object returned by dojox.lang.aspect.advise().
                
                if(!handle){ return; }
                var obj = handle[0], methods = handle[1];
                for(var name in methods){
                        var o = obj[name], t = o.advices, ao = methods[name];
                        for(var i = ao.length - 1; i >= 0; --i){
                                t.remove(ao[i]);
                        }
                        if(t.isEmpty()){
                                // check if we can remove all stubs
                                var empty = true, ls = o._listeners;
                                if(ls.length){
                                        for(i in ls){
                                                if(!(i in ap)){
                                                        empty = false;
                                                        break;
                                                }
                                        }
                                }
                                if(empty){
                                        // revert to the original method
                                        obj[name] = o.target;
                                }else{
                                        // replace with the dojo.connect() stub
                                        var x = obj[name] = d._listener.getDispatcher();
                                        x.target = o.target;
                                        x._listeners = ls;
                                }
                        }
                }
        };
        
        aop.getContext = function(){
                // summary:
                //              Returns the context information for the advice in effect.
                
                return context; // Object
        };
        
        aop.getContextStack = function(){
                // summary:
                //              Returns the context stack, which reflects executing advices
                //              up to this point. The array is ordered from oldest to newest.
                //              In order to get the active context use dojox.lang.aspect.getContext().
                
                return contextStack;    // Array
        };
        
        aop.proceed = function(){
                // summary:
                //              Call the original function (or the next level around advice) in an around advice code.
                //
                // description:
                //              Calls the original function (or the next level around advice).
                //              Accepts and passes on any number of arguments, and returns a value.
                //              This function is valid only in the content of around calls.
                
                var joinPoint = context.joinPoint, advices = joinPoint.advices;
                for(var c = context.around; c != advices; c = context.around){
                        context.around = c.prev_around; // advance the pointer
                        if(c.dynamic){
                                var a = context.dynAdvices[context.dynIndex++], t = a.around;
                                if(t){
                                        return t.apply(a, arguments);
                                }
                        }else{
                                return c.advice.around.apply(c.advice, arguments);
                        }
                }
                return joinPoint.target.apply(context.instance, arguments);
        };
})();

/*
Aspect = {
        before: function(arguments){...},
        around: function(arguments){...returns value...},
        afterReturning: function(ret){...},
        afterThrowing: function(excp){...},
        after: function(){...}
};

Context = {
        instance:  ..., // the instance we operate on
        joinPoint: ..., // Object (see below)
        depth:     ...  // current depth of the context stack
};

JoinPoint = {
        target:     ...,        // the original function being wrapped
        targetName: ...         // name of the method
};
*/