aquarium 0.1.8 → 0.2.0

data/lib/aquarium/aspects/advice.rb

@@ -26,6 +26,7 @@ module Aquarium
     class AdviceChainNode 
       include Enumerable
       def initialize options = {}, &proc_block
+        raise Aquarium::Utils::InvalidOptions.new("You must specify an advice block or Proc") if proc_block.nil?
         @proc = Proc.new &proc_block
         # assign :next_node and :static_join_point so the attributes are always created
         options[:next_node] ||= nil  
@@ -38,19 +39,28 @@ module Aquarium
         end
       end
   
-      def call jp, *args
+      def call jp, obj, *args
+        do_call @proc, "", jp, obj, *args
+      end
+
+      def invoke_original_join_point current_jp, obj, *args
+        do_call last, "While executing the original join_point: ", current_jp, obj, *args
+      end
+      
+      def do_call proc_to, error_message_prefix, jp, obj, *args
         begin
-          @proc.call jp, *args
+          proc_to.call jp, obj, *args
         rescue => e
           class_or_instance_method_separater = jp.instance_method? ? "#" : "."
-          context_message = "Exception raised while executing \"#{jp.context.advice_kind}\" advice for \"#{jp.type_or_object.inspect}#{class_or_instance_method_separater}#{jp.method_name}\": "
+          context_message = error_message_prefix + "Exception raised while executing \"#{jp.context.advice_kind}\" advice for \"#{jp.type_or_object.inspect}#{class_or_instance_method_separater}#{jp.method_name}\": "
           backtrace = e.backtrace
           e2 = e.exception(context_message + e.message + " (join_point = #{jp.inspect})")
           e2.set_backtrace backtrace
           raise e2
         end
       end
-
+      protected :do_call
+      
       # Supports Enumerable
       def each 
         node = self 
@@ -59,7 +69,14 @@ module Aquarium
           node = node.next_node 
         end 
       end
-  
+      
+      def last
+        last_node = nil
+        each { |node| last_node = node unless node.nil? } #; p "<br/>last_node: #{last_node.inspect .gsub(/\</,"&lt;").gsub(/\>/,"&gt;")}"}
+        # p "<br/><br/>returning last_node: #{last_node.inspect .gsub(/\</,"&lt;").gsub(/\>/,"&gt;")}"
+        last_node
+      end
+      
       def size
         inject(0) {|memo, node| memo += 1}
       end
@@ -73,6 +90,12 @@ module Aquarium
       end
   
       NIL_OBJECT = Aquarium::Utils::NilObject.new
+      
+      protected
+      
+      def invoking_object join_point
+        join_point.instance_method? ? join_point.context.advised_object : join_point.target_type
+      end
     end
 
     # When invoking the original method, we use object.send(original_method_name, *args)
@@ -82,13 +105,12 @@ module Aquarium
       # Note that we extract the block passed to the original method call, if any, 
       # from the context and pass it to method invocation.
       def initialize options = {}
-        super(options) { |jp, *args| 
+        super(options) { |jp, obj, *args| 
           block_for_method = jp.context.block_for_method
-          invoking_object = jp.instance_method? ? jp.context.advised_object : jp.target_type
-          method = invoking_object.method(@alias_method_name)
+          method = invoking_object(jp).method(@alias_method_name)
           block_for_method.nil? ? 
-            invoking_object.send(@alias_method_name, *args) : 
-            invoking_object.send(@alias_method_name, *args, &block_for_method)
+            invoking_object(jp).send(@alias_method_name, *args) : 
+            invoking_object(jp).send(@alias_method_name, *args, &block_for_method)
           # Buggy!!
           # method = invoking_object.method(@alias_method_name)
           # block_for_method.nil? ? 
@@ -100,20 +122,20 @@ module Aquarium
 
     class BeforeAdviceChainNode < AdviceChainNode
       def initialize options = {}
-        super(options) { |jp, *args| 
+        super(options) { |jp, obj, *args| 
           before_jp = jp.make_current_context_join_point :advice_kind => :before
-          advice.call(before_jp, *args)
-          next_node.call(jp, *args)
+          advice.call(before_jp, obj, *args)
+          next_node.call(jp, obj, *args)
         }
       end
     end
 
     class AfterReturningAdviceChainNode < AdviceChainNode
       def initialize options = {}
-        super(options) { |jp, *args| 
-          returned_value = next_node.call(jp, *args)
+        super(options) { |jp, obj, *args| 
+          returned_value = next_node.call(jp, obj, *args)
           next_jp = jp.make_current_context_join_point :advice_kind => :after_returning, :returned_value => returned_value
-          advice.call(next_jp, *args)
+          advice.call(next_jp, obj, *args)
           next_jp.context.returned_value   # allow advice to modify the returned value
         }
       end
@@ -124,13 +146,13 @@ module Aquarium
     class AfterRaisingAdviceChainNode < AdviceChainNode
       include Aquarium::Utils::ArrayUtils
       def initialize options = {}
-        super(options) { |jp, *args| 
+        super(options) { |jp, obj, *args| 
           begin
-            next_node.call(jp, *args)
+            next_node.call(jp, obj, *args)
           rescue Object => raised_exception
             if after_raising_exceptions_list_includes raised_exception
               next_jp = jp.make_current_context_join_point :advice_kind => :after_raising, :raised_exception => raised_exception
-              advice.call(next_jp, *args)
+              advice.call(next_jp, obj, *args)
               raised_exception = next_jp.context.raised_exception   # allow advice to modify raised exception
             end
             raise raised_exception
@@ -151,17 +173,17 @@ module Aquarium
 
     class AfterAdviceChainNode < AdviceChainNode
       def initialize options = {}
-        super(options) { |jp, *args| 
+        super(options) { |jp, obj, *args| 
           # advice.call is invoked in each bloc, rather than once in an "ensure" clause, so the invocation in the rescue class
           # can allow the advice to change the exception that will be raised.
           begin
-            returned_value = next_node.call(jp, *args)
+            returned_value = next_node.call(jp, obj, *args)
             next_jp = jp.make_current_context_join_point :advice_kind => :after, :returned_value => returned_value
-            advice.call(next_jp, *args)
+            advice.call(next_jp, obj, *args)
             next_jp.context.returned_value   # allow advice to modify the returned value
           rescue Object => raised_exception
             next_jp = jp.make_current_context_join_point :advice_kind => :after, :raised_exception => raised_exception
-            advice.call(next_jp, *args)
+            advice.call(next_jp, obj, *args)
             raise next_jp.context.raised_exception
           end
         }
@@ -170,9 +192,9 @@ module Aquarium
 
     class AroundAdviceChainNode < AdviceChainNode
       def initialize options = {}
-        super(options) { |jp, *args| 
+        super(options) { |jp, obj, *args| 
           around_jp = jp.make_current_context_join_point :advice_kind => :around, :proceed_proc => next_node
-          advice.call(around_jp, *args)
+          advice.call(around_jp, obj, *args)
         }
       end
     end

data/lib/aquarium/aspects/aspect.rb

@@ -1,4 +1,5 @@
 require 'aquarium/extensions'
+require 'aquarium/finders/type_finder'
 require 'aquarium/utils'
 require 'aquarium/aspects/advice'
 require 'aquarium/aspects/exclusion_handler'
@@ -30,12 +31,15 @@ module Aquarium
       attr_accessor :verbose, :log
       attr_reader   :specification, :pointcuts, :advice
   
+      OTHER_ALLOWED_OPTIONS_SINGULAR = %w[type_and_descendents type_and_ancestors exclude_type_and_descendents exclude_type_and_ancestors].map {|o| o.intern}
+      OTHER_ALLOWED_OPTIONS_PLURAL   = %w[types_and_descendents types_and_ancestors exclude_types_and_descendents exclude_types_and_ancestors].map {|o| o.intern}
+
       ALLOWED_OPTIONS_SINGULAR = %w[advice type object method attribute method_option attribute_option pointcut default_object
        exclude_type exclude_object exclude_pointcut exclude_join_point exclude_method exclude_attribute noop].map {|o| o.intern}
   
-      ALLOWED_OPTIONS_PLURAL = ALLOWED_OPTIONS_SINGULAR.map {|o| "#{o}s".intern}
+      ALLOWED_OPTIONS_PLURAL = OTHER_ALLOWED_OPTIONS_PLURAL + ALLOWED_OPTIONS_SINGULAR.map {|o| "#{o.to_s}s".intern}
 
-      ALLOWED_OPTIONS = ALLOWED_OPTIONS_SINGULAR + ALLOWED_OPTIONS_PLURAL
+      ALLOWED_OPTIONS = ALLOWED_OPTIONS_PLURAL + ALLOWED_OPTIONS_SINGULAR + OTHER_ALLOWED_OPTIONS_SINGULAR
 
       ADVICE_OPTIONS_SYNONYMS_MAP = {
         :call               => :advice,
@@ -44,33 +48,38 @@ module Aquarium
       }
       
       ALLOWED_OPTIONS_SYNONYMS_MAP = { 
-        :type               => :types,
-        :within_type        => :types, 
-        :within_types       => :types,
-        :object             => :objects,
-        :within_object      => :objects, 
-        :within_objects     => :objects,
-        :method             => :methods,
-        :within_method      => :methods, 
-        :within_methods     => :methods,
-        :attribute          => :attributes,
-        :pointcut           => :pointcuts,
-        :within_pointcut    => :pointcuts,
-        :within_pointcuts   => :pointcuts,
-        :exclude_type       => :exclude_types,
-        :exclude_object     => :exclude_objects,
-        :exclude_pointcut   => :exclude_pointcuts,
-        :exclude_join_point => :exclude_join_points,
-        :exclude_method     => :exclude_methods,
-        :exclude_attribute  => :exclude_attributes,
+        :type                  => :types,
+        :type_and_descendents  => :types_and_descendents,
+        :type_and_ancestors    => :types_and_ancestors,
+        :within_type           => :types, 
+        :within_types          => :types,
+        :object                => :objects,
+        :within_object         => :objects, 
+        :within_objects        => :objects,
+        :method                => :methods,
+        :within_method         => :methods, 
+        :within_methods        => :methods,
+        :attribute             => :attributes,
+        :pointcut              => :pointcuts,
+        :within_pointcut       => :pointcuts,
+        :within_pointcuts      => :pointcuts,
+        :exclude_type          => :exclude_types,
+        :exclude_type_and_descendents => :exclude_types_and_descendents,
+        :exclude_type_and_ancestors   => :exclude_types_and_ancestors,
+        :exclude_object        => :exclude_objects,
+        :exclude_pointcut      => :exclude_pointcuts,
+        :exclude_join_point    => :exclude_join_points,
+        :exclude_method        => :exclude_methods,
+        :exclude_attribute     => :exclude_attributes,
       }
 
       # Aspect.new (:around | :before | :after | :after_returning | :after_raising ) \
       #   (:pointcuts => [...]), | \
-      #    ((:types => [...] | :objects => [...]), 
+      #    ((:types => [...] | :types_and_ancestors => [...] | :types_and_descendents => [...] \
+      #     :objects => [...]), 
       #     :methods => [], :method_options => [...], \
       #     :attributes => [...], :attribute_options[...]), \
-      #    (:advice = advice | do |join_point, *args| ...; end)
+      #    (:advice = advice | do |join_point, obj, *args| ...; end)
       # 
       # where the parameters often have many synonyms (mostly to support a "humane
       # interface") and they are interpreted as followed:
@@ -109,6 +118,13 @@ module Aquarium
       #   All the :types, :objects, :methods, :attributes, :method_options, and :attribute_options
       #   are used to construct Pointcuts internally.
       #
+      # <tt>:types_and_descendents => type || [type_list]</tt>::
+      # <tt>:type_and_descendents  => type || [type_list]</tt>::
+      # <tt>:types_and_ancestors   => type || [type_list]</tt>::
+      # <tt>:type_and_ancestors    => type || [type_list]</tt>::
+      #   One or an array of types and either their descendents or ancestors. 
+      #   If you want both the descendents _and_ ancestors, use both options.
+      #
       # <tt>:objects => object || [object_list]</tt>::
       # <tt>:object  => object || [object_list]</tt>::
       # <tt>:within_object  => object || [object_list]</tt>::
@@ -164,6 +180,16 @@ module Aquarium
       # <tt>:exclude_attribute   => attribute || [attribute_list]</tt>::
       #   Exclude the specified "things" from the matched join points.
       #
+      # <tt>:exclude_types_and_descendents => type || [type_list]</tt>::
+      # <tt>:exclude_type_and_descendents  => type || [type_list]</tt>::
+      # <tt>:exclude_types_and_ancestors   => type || [type_list]</tt>::
+      # <tt>:exclude_type_and_ancestors    => type || [type_list]</tt>::
+      #   Exclude the specified types and their descendents, ancestors.
+      #   If you want to exclude both the descendents _and_ ancestors, use both options.
+      #
+      # The actual advice to execute is the block or you can pass a Proc using :advice => proc.
+      # Note that the advice takes a join_point argument, which will include a non-nil 
+      # JoinPoint#Context object, the object being executed, and the argument list to the method.
       def initialize *options, &block
         process_input options, &block
         init_pointcuts
@@ -218,15 +244,22 @@ module Aquarium
         opts = rationalize_parameters options.flatten.dup
         # For non-hash inputs, use an empty string for the value
         @specification = Aquarium::Utils::MethodUtils.method_args_to_hash(*opts) {|option| ""} 
-        use_default_object_if_defined unless (types_given? || objects_given? || pointcuts_given?)
+        use_default_object_if_defined unless some_type_or_pc_option_given? 
         use_first_nonadvice_symbol_as_method(opts) unless methods_given?
+        calculate_excluded_types
         @advice = determine_advice block
-        if @advice.nil? && @specification[:noop].nil?
-          bad_options "No advice block nor :advice argument was given."
-        end
         validate_specification
       end
 
+      def calculate_excluded_types
+        type_finder_options = {}
+        %w[types types_and_ancestors types_and_descendents].each do |opt|
+          type_finder_options[opt.intern] = @specification["exclude_#{opt}".intern] if @specification["exclude_#{opt}".intern]
+        end
+        excluded_types = Aquarium::Finders::TypeFinder.new.find type_finder_options
+        @specification[:exclude_types_calculated] = excluded_types.matched.keys
+      end
+      
       def determine_advice block
         # There can be only one advice; take the last one...
         block || (@specification[:advice].kind_of?(Array) ? @specification[:advice].last : @specification[:advice])
@@ -322,8 +355,8 @@ module Aquarium
       # Useful for debugging...
       def self.advice_chain_inspect advice_chain
         return "[nil]" if advice_chain.nil?
-        "<br/>"+advice_chain.inspect do |advice_chain|
-          "#{advice_chain.class.name}:#{advice_chain.object_id}: join_point = #{advice_chain.static_join_point}: aspect = #{advice_chain.aspect.object_id}, next_node = #{advice_chain_inspect advice_chain.next_node}"
+        "<br/>"+advice_chain.inspect do |ac|
+          "#{ac.class.name}:#{ac.object_id}: join_point = #{ac.static_join_point}: aspect = #{ac.aspect.object_id}, next_node = #{advice_chain_inspect ac.next_node}"
         end.gsub(/\</,"&lt;").gsub(/\>/,"&gt;")+"<br/>"
       end
 
@@ -402,7 +435,7 @@ module Aquarium
             :advised_object => #{target_self}, 
             :parameters => args, 
             :block_for_method => block_for_method)
-          advice_chain.call advice_join_point, *args
+          advice_chain.call advice_join_point, #{target_self}, *args
         end
         #{join_point.visibility.to_s} :#{join_point.method_name}
         private :#{alias_method_name}
@@ -495,14 +528,16 @@ module Aquarium
         "_aspect_"
       end
   
+      def some_type_or_pc_option_given?
+        pointcuts_given? or some_type_option_given? or objects_given? #or default_objects_given?
+      end
+      
+      def some_type_option_given?
+        types_given? or types_and_ancestors_given? or types_and_descendents_given? 
+      end
+      
       def self.determine_type_or_object join_point
         join_point.type_or_object
-        # type_or_object = join_point.type_or_object
-        # method_type = join_point.instance_or_class_method
-        # if is_type_join_point? join_point
-        #   type_or_object = Aquarium::Utils::MethodUtils.definer type_or_object, join_point.method_name, "#{method_type}_method_only".intern
-        # end
-        # type_or_object
       end
       
       def self.make_type_or_object_key join_point
@@ -553,15 +588,21 @@ module Aquarium
         bad_options(":after can't be used with :after_returning.")   if after_given_with? :after_returning
         bad_options(":after can't be used with :after_raising.")     if after_given_with? :after_raising
         bad_options(":after_returning can't be used with :after_raising.") if after_returning_given_with? :after_raising
-        unless pointcuts_given? or types_given? or objects_given? or default_objects_given?
-          bad_options("At least one of :pointcut(s), :type(s), :object(s) is required.") 
+        unless some_type_or_pc_option_given?
+          bad_options("At least one of :pointcut(s), :type(s), :type(s)_with_ancestors, :type(s)_with_descendents, :object(s) is required.") 
         end
-        if pointcuts_given? and (types_given? or objects_given?)
+        if pointcuts_given? and (some_type_option_given? or objects_given?)
           bad_options("Can't specify both :pointcut(s) and one or more of :type(s), and/or :object(s).") 
         end
         @specification.each_key do |parameter|
           check_parameter parameter
         end
+        if @advice.nil? && @specification[:noop].nil?
+          bad_options "No advice block nor :advice argument was given."
+        end
+        if @advice.arity == -2
+          bad_options "It appears that your advice parameter list is the obsolete format |jp, *args|. The correct format is |jp, object, *args|"
+        end
       end
 
       def check_parameter parameter
@@ -571,6 +612,7 @@ module Aquarium
       def is_valid_parameter key
         ALLOWED_OPTIONS.include?(key) || ALLOWED_OPTIONS_SYNONYMS_MAP.keys.include?(key) || 
           ADVICE_OPTIONS_SYNONYMS_MAP.keys.include?(key) || KINDS_IN_PRIORITY_ORDER.include?(key) ||
+          key == :exclude_types_calculated ||
           parameter_is_a_method_name?(key)    # i.e., use_first_nonadvice_symbol_as_method
       end
       

data/lib/aquarium/aspects/dsl/aspect_dsl.rb

@@ -25,7 +25,7 @@ module Aquarium
         %w[after after_returning after_raising].each do |after_kind|
           module_eval(<<-AFTER, __FILE__, __LINE__)
             def before_and_#{after_kind} *options, &block
-              advise(:before, :#{after_kind}, *options, &block)
+              advise :before, :#{after_kind}, *options, &block
             end
           AFTER
         end

data/lib/aquarium/aspects/exclusion_handler.rb

@@ -28,8 +28,8 @@ module Aquarium
         unless @specification[:exclude_objects].nil?
           return true if @specification[:exclude_objects].include?(type_or_object)
         end
-        unless @specification[:exclude_types].nil?
-          return true if @specification[:exclude_types].find do |t|
+        unless @specification[:exclude_types_calculated].nil?
+          return true if @specification[:exclude_types_calculated].find do |t|
             case t
             when String: type_or_object.name.eql?(t)
             when Symbol: type_or_object.name.eql?(t.to_s)

data/lib/aquarium/aspects/join_point.rb

@@ -8,6 +8,9 @@ module Aquarium
   module Aspects
     class JoinPoint
 
+      class ProceedMethodNotAvailable < Exception; end
+      class ContextNotDefined < Exception; end
+      
       class Context
         attr_accessor :advice_kind, :advised_object, :parameters, :block_for_method, :returned_value, :raised_exception, :proceed_proc
 
@@ -26,12 +29,20 @@ module Aquarium
         end
     
         def proceed enclosing_join_point, *args, &block
-          raise "It looks like you tried to call \"JoinPoint#proceed\" (or \"JoinPoint::Context#proceed\") from within advice that isn't \"around\" advice. Only around advice can call proceed. (Specific error: JoinPoint#proceed cannot be called because no \"@proceed_proc\" attribute was set on the corresponding JoinPoint::Context object.)" unless @proceed_proc
+          raise ProceedMethodNotAvailable.new("It looks like you tried to call \"JoinPoint#proceed\" (or \"JoinPoint::Context#proceed\") from within advice that isn't \"around\" advice. Only around advice can call proceed. (Specific error: JoinPoint#proceed cannot be called because no \"@proceed_proc\" attribute was set on the corresponding JoinPoint::Context object.)") if @proceed_proc.nil?
+          do_invoke :call, enclosing_join_point, *args, &block
+        end
+        
+        def invoke_original_join_point enclosing_join_point, *args, &block
+          do_invoke :invoke_original_join_point, enclosing_join_point, *args, &block
+        end
+        
+        def do_invoke method, enclosing_join_point, *args, &block
           args = parameters if (args.nil? or args.size == 0)
           enclosing_join_point.context.block_for_method = block if block 
-          proceed_proc.call enclosing_join_point, *args
+          proceed_proc.send method, enclosing_join_point, advised_object, *args
         end
-        protected :proceed
+        protected :do_invoke
         
         alias :to_s :inspect
     
@@ -68,32 +79,9 @@ module Aquarium
         end    
       end
 
-      %w[type object].each do |attr|
-        class_eval(<<-EOF, __FILE__, __LINE__)
-          # Deprecated, as JoinPoint#type overrides Module#type in a non-substitutable way!
-          # JoinPoint#target_#{attr} will be removed in the next release.
-          # Use JoinPoint#target_#{attr} instead
-          def #{attr}
-            p "WARNING: JoinPoint##{attr} is deprecated. It will be removed in the next release."
-            target_#{attr}
-          end
-          # Deprecated
-          def #{attr}= new_#{attr}
-            p "WARNING: JoinPoint##{attr}= is deprecated. It will be removed in the next release."
-            target_#{attr}= new_#{attr}
-          end
-        EOF
-      end
-      
       attr_accessor :target_type, :target_object, :method_name, :visibility, :context
       attr_reader   :instance_or_class_method
       
-      # For "symmetry" with JoinPoint#target_type
-      alias_method  :object, :target_object
-
-      # For "symmetry" with JoinPoint#target_type=
-      alias_method  :object=, :target_object=
-      
       def instance_method?
         @instance_method
       end
@@ -124,14 +112,26 @@ module Aquarium
         results = Aquarium::Finders::MethodFinder.new.find type_or_object_sym => type_or_object, 
                             :method => method_name, 
                             :options => [visibility, instance_or_class_method]
-        raise Exception("MethodFinder returned more than one item! #{results.inspect}") if (results.matched.size + results.not_matched.size) != 1
+        raise Aquarium::Utils::LogicError("MethodFinder returned more than one item! #{results.inspect}") if (results.matched.size + results.not_matched.size) != 1
         return results.matched.size == 1 ? true : false
       end
       
+      # Invoke the "enclosed" join point, which could be aspect advice wrapping the original runtime join point.
+      # This method can only be called if the join point has a context object defined that represents an actual
+      # runtime "state".
       def proceed *args, &block
-        context.method(:proceed).call self, *args, &block
+        raise ContextNotDefined.new(":proceed can't be called unless the join point has a context object.") if context.nil?
+        context.proceed self, *args, &block
       end
 
+      # Invoke the actual runtime join point, skipping any intermediate advice.
+      # This method can only be called if the join point has a context object defined that represents an actual
+      # runtime "state".
+      def invoke_original_join_point *args, &block
+        raise ContextNotDefined.new(":invoke_original_join_point can't be called unless the join point has a context object.") if context.nil?
+        context.invoke_original_join_point self, *args, &block
+      end
+      
       def make_current_context_join_point context_options
         new_jp = dup
         if new_jp.context.nil?