aquarium 0.4.1 → 0.4.2

data/examples/aspect_design_example_spec.rb

@@ -31,10 +31,28 @@ end
 
 include Aquarium::Aspects
 
-describe "An example of an aspect using a class-defined pointcut." do
+# Two ways of referencing the pointcut are shown. The first assumes you know the particular
+# pointcuts you care about. The second is more general; it uses the recently-introduced
+# :named_pointcut feature to search for all pointcuts matching a name in a set of types.
+describe "An example of an aspect referencing a particular class-defined pointcut." do
   it "should observe state changes in the class." do
     @new_state = nil
-    observer = Aspect.new :after, :pointcut => Aquarium::ClassWithStateAndBehavior::STATE_CHANGE do |jp, obj, *args|
+    observer = Aspect.new :after, 
+      :pointcut => Aquarium::ClassWithStateAndBehavior::STATE_CHANGE do |jp, obj, *args|
+      @new_state = obj.state
+      @new_state.should be_eql(*args)
+    end
+    object = Aquarium::ClassWithStateAndBehavior.new(:a1, :a2, :a3)
+    object.state = [:b1, :b2]
+    @new_state.should == [:b1, :b2]
+    observer.unadvise
+  end
+end
+describe "An example of an aspect searching for class-defined pointcuts." do
+  it "should observe state changes in the class." do
+    @new_state = nil
+    observer = Aspect.new :after, 
+      :named_pointcuts => {:matching => /CHANGE/, :within_types => Aquarium::ClassWithStateAndBehavior} do |jp, obj, *args|
       @new_state = obj.state
       @new_state.should be_eql(*args)
     end

data/examples/introductions_example.rb

@@ -0,0 +1,35 @@
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'aquarium'
+
+module Aquarium
+  module TypeFinderIntroductionExampleTargetModule1
+  end
+  module TypeFinderIntroductionExampleTargetModule2
+  end
+  class TypeFinderIntroductionExampleTargetClass1
+  end
+  class TypeFinderIntroductionExampleTargetClass2
+  end
+  module TypeFinderIntroductionExampleModule
+    def introduced_method; end
+  end
+end
+
+include Aquarium::Finders
+
+# First, find the types
+
+found = TypeFinder.new.find :types => /Aquarium::TypeFinderIntroductionExampleTarget/
+
+# Now, iterate through them and "extend" them with the module defining the new behavior.
+
+found.each {|t| t.extend Aquarium::TypeFinderIntroductionExampleModule }
+
+# See if the "introduced" modules's method is there.
+
+[Aquarium::TypeFinderIntroductionExampleTargetModule1, 
+ Aquarium::TypeFinderIntroductionExampleTargetModule2,
+ Aquarium::TypeFinderIntroductionExampleTargetClass1,
+ Aquarium::TypeFinderIntroductionExampleTargetClass2].each do |t|
+   p "type #{t}, method there? #{t.methods.include?("introduced_method")}"
+end

data/examples/introductions_example_spec.rb

@@ -0,0 +1,37 @@
+require File.dirname(__FILE__) + '/../spec/aquarium/spec_helper'
+require 'aquarium'
+
+# Example demonstrating how to use the TypeFinder class to convenient "introduce" new
+# methods and attributes in a set of types, like you might do with AspectJ in Java.
+# Of course, in Ruby, you can simply use Object#extend(module). However, if you want to
+# do this in a cross-cutting way, TypeFinder. is convenient.
+
+module Aquarium
+  module TypeFinderIntroductionExampleTargetModule1
+  end
+  module TypeFinderIntroductionExampleTargetModule2
+  end
+  class TypeFinderIntroductionExampleTargetClass1
+  end
+  class TypeFinderIntroductionExampleTargetClass2
+  end
+  module TypeFinderIntroductionExampleModule
+    def introduced_method; end
+  end
+end
+
+# include Aquarium::Finders
+
+describe "Using TypeFinder to introduce modules in a set of other types" do
+  it "should extend each found type with the specified module if you use the finder result #each method" do
+    found = Aquarium::Finders::TypeFinder.new.find :types => /Aquarium::TypeFinderIntroductionExampleTarget/
+    found.each {|t| t.extend Aquarium::TypeFinderIntroductionExampleModule }
+    [Aquarium::TypeFinderIntroductionExampleTargetModule1, 
+     Aquarium::TypeFinderIntroductionExampleTargetModule2,
+     Aquarium::TypeFinderIntroductionExampleTargetClass1,
+     Aquarium::TypeFinderIntroductionExampleTargetClass2].each do |t|
+       t.methods.should include('introduced_method')
+    end
+  end
+end
+  

data/examples/method_missing_example.rb

@@ -31,7 +31,8 @@ echo1.say "hello", "world!"
 echo1.log "something", "interesting..."
 echo1.shout "theater", "in", "a", "crowded", "firehouse!"
 
-Aquarium::Aspects::Aspect.new :around, :calls_to => :method_missing, :for_type => Aquarium::Echo, do |join_point, obj, sym, *args|
+Aquarium::Aspects::Aspect.new :around, 
+  :calls_to => :method_missing, :for_type => Aquarium::Echo, do |join_point, obj, sym, *args|
   if sym == :log 
     p "--- Sending to log: #{args.join(" ")}" 
   else

data/lib/aquarium/aspects/advice.rb

@@ -8,6 +8,8 @@ module Aquarium
   module Aspects
     module Advice
       
+      UNKNOWN_ADVICE_KIND = "unknown"
+
       KINDS_IN_PRIORITY_ORDER = [:around, :before, :after, :after_returning, :after_raising] 
       
       def self.kinds; KINDS_IN_PRIORITY_ORDER; end
@@ -17,6 +19,19 @@ module Aquarium
           KINDS_IN_PRIORITY_ORDER.index(x.to_sym) <=> KINDS_IN_PRIORITY_ORDER.index(y.to_sym)
         end.map {|x| x.to_sym}
       end
+      
+      def self.compare_advice_kinds kind1, kind2
+        if kind1.nil?
+          return kind2.nil? ? 0 : -1
+        end
+        return 1 if kind2.nil?
+        if kind1.eql?(UNKNOWN_ADVICE_KIND)
+          return kind2.eql?(UNKNOWN_ADVICE_KIND) ? 0 : -1
+        else
+          return kind2.eql?(UNKNOWN_ADVICE_KIND) ? 1 : KINDS_IN_PRIORITY_ORDER.index(kind1) <=> KINDS_IN_PRIORITY_ORDER.index(kind2)
+        end
+      end
+      
     end  
 
     # Supports Enumerable, but not the sorting methods, as this class is a linked list structure.
@@ -25,9 +40,7 @@ module Aquarium
     # in the case of around advice!
     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
+      def initialize options = {}
         # assign :next_node and :static_join_point so the attributes are always created
         options[:next_node] ||= nil  
         options[:static_join_point] ||= nil
@@ -37,38 +50,32 @@ module Aquarium
             attr_accessor(:#{key})
           EOF
         end
+      end
         
-        def call_advice jp, obj, *args
-          case advice.arity
-          when 0 then advice.call
-          when 1 then advice.call jp
-          when 2 then advice.call jp, obj
-          else        advice.call jp, obj, *args
-          end
+      # Bug #19262 workaround: need to only pass jp argument if arity is 1.
+      def call_advice jp
+        if advice.arity == 1
+          advice.call jp
+        else
+          advice.call jp, jp.context.advised_object, *jp.context.parameters
         end
       end
   
-      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
+      def call jp
+        begin
+          advice_wrapper jp
+        rescue Exception => e
+          handle_call_rescue e, "", jp
+        end
       end
       
-      def do_call proc_to, error_message_prefix, jp, obj, *args
+      def invoke_original_join_point current_jp
         begin
-          proc_to.call jp, obj, *args
-        rescue => e
-          class_or_instance_method_separater = jp.instance_method? ? "#" : "."
-          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
+          last.advice_wrapper current_jp
+        rescue Exception => e
+          handle_call_rescue e, "While executing the original join_point: ", current_jp
         end
       end
-      protected :do_call
       
       # Supports Enumerable
       def each 
@@ -101,8 +108,30 @@ module Aquarium
       
       protected
       
-      def invoking_object join_point
-        join_point.instance_method? ? join_point.context.advised_object : join_point.target_type
+      #--
+      # For performance reasons, we don't clone the context. 
+      # TODO: There are potential concurrency issues!
+      #++
+      def update_current_context jp
+        return if advice.arity == 0
+        @last_advice_kind = jp.context.advice_kind
+        @last_advice_node = jp.context.current_advice_node
+        jp.context.current_advice_node = self
+      end
+
+      def reset_current_context jp 
+        return if advice.arity == 0
+        jp.context.advice_kind = @last_advice_kind
+        jp.context.current_advice_node = @last_advice_node
+      end
+      
+      def handle_call_rescue ex, error_message_prefix, jp
+        class_or_instance_method_separater = jp.instance_method? ? "#" : "."
+        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 = ex.backtrace
+        e2 = ex.exception(context_message + ex.message + " (join_point = #{jp.inspect})")
+        e2.set_backtrace backtrace
+        raise e2
       end
     end
 
@@ -113,33 +142,39 @@ 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, obj, *args| 
-          block_for_method = jp.context.block_for_method
-          block_for_method.nil? ? 
-            invoking_object(jp).send(@alias_method_name, *args) : 
-            invoking_object(jp).send(@alias_method_name, *args, &block_for_method)
-        }
+        super options
+      end
+      def advice_wrapper jp
+        jp.context.advised_object.send @alias_method_name, *jp.context.parameters, &jp.context.block_for_method
       end
     end
 
     class BeforeAdviceChainNode < AdviceChainNode
       def initialize options = {}
-        super(options) { |jp, obj, *args| 
-          before_jp = jp.make_current_context_join_point :advice_kind => :before, :current_advice_node => self
-          call_advice(before_jp, obj, *args)
-          next_node.call(jp, obj, *args)
-        }
+        super options 
+      end
+      def advice_wrapper jp
+        update_current_context jp
+        jp.context.advice_kind = :before
+        call_advice jp
+        reset_current_context jp
+        next_node.call jp
       end
     end
 
     class AfterReturningAdviceChainNode < AdviceChainNode
       def initialize options = {}
-        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, :current_advice_node => self
-          call_advice(next_jp, obj, *args)
-          next_jp.context.returned_value   # allow advice to modify the returned value
-        }
+        super options
+      end
+      def advice_wrapper jp
+        returned_value = next_node.call jp
+        update_current_context jp
+        jp.context.advice_kind = :after_returning
+        jp.context.returned_value = returned_value
+        call_advice jp
+        result = jp.context.returned_value   # allow advice to modify the returned value
+        reset_current_context jp
+        result
       end
     end
 
@@ -148,18 +183,22 @@ module Aquarium
     class AfterRaisingAdviceChainNode < AdviceChainNode
       include Aquarium::Utils::ArrayUtils
       def initialize options = {}
-        super(options) { |jp, obj, *args| 
-          begin
-            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, :current_advice_node => self
-              call_advice(next_jp, obj, *args)
-              raised_exception = next_jp.context.raised_exception   # allow advice to modify raised exception
-            end
-            raise raised_exception
+        super options
+      end
+      def advice_wrapper jp
+        begin
+          next_node.call jp
+        rescue Object => raised_exception
+          if after_raising_exceptions_list_includes raised_exception
+            update_current_context jp
+            jp.context.advice_kind = :after_raising
+            jp.context.raised_exception = raised_exception
+            call_advice jp
+            raised_exception = jp.context.raised_exception   # allow advice to modify the raised exception
+            reset_current_context jp
           end
-        }
+          raise raised_exception
+        end
       end
 
       private
@@ -175,29 +214,43 @@ module Aquarium
 
     class AfterAdviceChainNode < AdviceChainNode
       def initialize options = {}
-        super(options) { |jp, obj, *args| 
-          # call_advice 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, obj, *args)
-            next_jp = jp.make_current_context_join_point :advice_kind => :after, :returned_value => returned_value, :current_advice_node => self
-            call_advice(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, :current_advice_node => self
-            call_advice(next_jp, obj, *args)
-            raise next_jp.context.raised_exception
-          end
-        }
+        super options
+      end
+      def advice_wrapper jp
+        # call_advice is invoked in each bloc, rather than once in an "ensure" clause, so the invocation in 
+        # the rescue clause can allow the advice to change the exception that will be raised.
+        begin
+          returned_value = next_node.call jp
+          update_current_context jp
+          jp.context.advice_kind = :after
+          jp.context.returned_value = returned_value
+          call_advice jp
+          result = jp.context.returned_value   # allow advice to modify the returned value
+          reset_current_context jp
+          result
+        rescue Object => raised_exception
+          update_current_context jp
+          jp.context.advice_kind = :after
+          jp.context.raised_exception = raised_exception
+          call_advice jp
+          raised_exception = jp.context.raised_exception   # allow advice to modify the raised exception
+          reset_current_context jp
+          raise raised_exception
+        end
       end
     end
 
     class AroundAdviceChainNode < AdviceChainNode
       def initialize options = {}
-        super(options) { |jp, obj, *args| 
-          around_jp = jp.make_current_context_join_point :advice_kind => :around, :proceed_proc => next_node, :current_advice_node => self
-          call_advice(around_jp, obj, *args)
-        }
+        super options
+      end
+      def advice_wrapper jp
+        update_current_context jp
+        jp.context.advice_kind = :around
+        jp.context.proceed_proc = next_node
+        result = call_advice jp
+        reset_current_context jp
+        result
       end
     end
 

data/lib/aquarium/aspects/aspect.rb

@@ -1,5 +1,5 @@
 require 'aquarium/extensions'
-require 'aquarium/finders/type_finder'
+require 'aquarium/finders'
 require 'aquarium/utils'
 require 'aquarium/aspects/advice'
 require 'aquarium/aspects/exclusion_handler'
@@ -12,14 +12,14 @@ module Aquarium
   module Aspects
     
     # == Aspect
-    # Aspects "advise" one or more method invocations for one or more types or objects
+    # Aspect "advises" one or more method invocations for one or more types or objects
     # (including class methods on types). The corresponding advice is a Proc that is
     # invoked either before the join point, after it returns, after it raises an exception, 
     # after either event, or around the join point, meaning the advice runs and it decides 
     # when and if to invoke the advised method. (Hence, around advice can run code before 
     # and after the join point call and it can "veto" the actual join point call).
     #  
-    # See also Aquarium::Aspects::DSL::AspectDsl for more information.
+    # See also Aquarium::DSL for more information.
     class Aspect
       include Advice
       include ExclusionHandler
@@ -35,27 +35,31 @@ module Aquarium
       ASPECT_CANONICAL_OPTIONS = {
         "advice"            => %w[action do_action use_advice advise_with invoke call],
         "pointcuts"         => %w[pointcut],
+        "named_pointcuts"   => %w[named_pointcut],
         "exceptions"        => %w[exception],
         "ignore_no_matching_join_points" => %[ignore_no_jps]
       }
-      add_prepositional_option_variants_for "pointcuts", ASPECT_CANONICAL_OPTIONS
-      add_exclude_options_for               "pointcuts", ASPECT_CANONICAL_OPTIONS
+      ["pointcuts", "named_pointcuts"].each do |pc_option|
+        add_prepositional_option_variants_for pc_option, ASPECT_CANONICAL_OPTIONS
+        add_exclude_options_for               pc_option, ASPECT_CANONICAL_OPTIONS
+      end
       CANONICAL_OPTIONS = Pointcut::CANONICAL_OPTIONS.merge ASPECT_CANONICAL_OPTIONS
          
       canonical_options_given_methods CANONICAL_OPTIONS
 
 
-      # Aspect.new (:around | :before | :after | :after_returning | :after_raising ) \
-      #   (:pointcuts => [...]), | \
-      #    ((:types => [...] | :types_and_ancestors => [...] | :types_and_descendents => [...] \
-      #     :objects => [...]), 
-      #     :methods => [], :method_options => [...], \
-      #     :attributes => [...], :attribute_options[...]), \
+      # Aspect.new (:around | :before | :after | :after_returning | :after_raising )
+      #   (:pointcuts => [...]), :named_pointcuts => [...] |
+      #    ((:types => [...] | :types_and_ancestors => [...] | :types_and_descendents => [...]
+      #     | :types_and_nested_types | :objects => [...]), 
+      #     :methods => [], :method_options => [...],
+      #     :attributes => [...], :attribute_options[...]),
       #    (: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:
       #
+      # ==== Type of Advice
       # <tt>:around</tt>::
       #   Invoke the specified advice "around" the join points. It is up to the advice
       #   itself to call <tt>join_point.proceed</tt> (where <tt>join_point</tt> is the
@@ -73,36 +77,64 @@ module Aquarium
       #   Invoke the specified advice after the join point returns successfully.
       #
       # <tt>:after_raising [=> exception || [exception_list]]</tt>::
-      # <tt>:after_raising, :exceptions => (exception || [exception_list])</tt>::
-      # <tt>:after_raising, :exception  => (exception || [exception_list])</tt>::
       #   Invoke the specified advice after the join point raises one of the specified exceptions.
-      #   If no exceptions are specified, the advice is invoked after any exception is raised. 
+      #   If no exceptions are specified, the advice is invoked after any exception is raised. An
+      #   alternative syntax is <tt>:after_raising, :exception[s] => (exception || [exception_list])</tt>.
+      #
+      # ==== Advice
+      # The advice to invoke before, after, or around the join points. Only one advice may be specified. 
+      # If a block is specified, the following options are ignored.
+      # * <tt>:advice => proc</tt>
+      # * <tt>:action => proc</tt>
+      # * <tt>:do_action => proc</tt>
+      # * <tt>:use_advice => proc</tt>
+      # * <tt>:advise_with => proc</tt>
+      # * <tt>:invoke => proc</tt>
+      # * <tt>:call => proc</tt>
+      #
+      # ==== Pointcuts
+      # A Pointcut, JoinPoint, or array of the same (Mixed is allowed.). Specifying pointcuts
+      # is mutually-exclusive with specifying them "indirectly" through :types, :objects,
+      # :methods, :attributes, :method_options, and :attribute_options parameters.
+      # * <tt>:pointcuts => pointcut || [pointcut_list]</tt>
+      # * <tt>:pointcut  => pointcut || [pointcut_list]</tt>
+      # * <tt>:on_pointcut  => pointcut || [pointcut_list]</tt>
+      # * <tt>:on_pointcuts => pointcut || [pointcut_list]</tt>
+      # * <tt>:in_pointcut  => pointcut || [pointcut_list]</tt>
+      # * <tt>:in_pointcuts => pointcut || [pointcut_list]</tt>
+      # * <tt>:within_pointcut  => pointcut || [pointcut_list]</tt>
+      # * <tt>:within_pointcuts => pointcut || [pointcut_list]</tt>
       #
-      # <tt>:advice => proc</tt>::
-      # <tt>:action => proc</tt>::
-      # <tt>:do_action => proc</tt>::
-      # <tt>:use_advice => proc</tt>::
-      # <tt>:advise_with => proc</tt>::
-      # <tt>:invoke => proc</tt>::
-      # <tt>:call => proc</tt>::
-      #   The specified advice to be invoked. Only one advice may be specified. If a block is
-      #   specified, it is used instead.
+      # ==== Named Pointcuts
+      # Specify search criteria to locate Pointcuts defined as class constants and/or class variables.
+      # The options for the <tt>named_pointcuts</tt> parameter must form a hash and satisfy the
+      # requirements documented for Aquarium::Finders::PointcutFinder#find.
+      # Specifying named pointcuts is also mutually-exclusive with specifying Pointcuts "indirectly"
+      # through :types, :objects, :methods, :attributes, :method_options, and :attribute_options parameters.
+      # * <tt>:named_pointcuts => {PointcutFinder options}</tt>
+      # * <tt>:named_pointcut  => {PointcutFinder options}</tt>
+      # * <tt>:on_named_pointcuts => {PointcutFinder options}</tt>
+      # * <tt>:on_named_pointcut  => {PointcutFinder options}</tt>
+      # * <tt>:in_named_pointcuts => {PointcutFinder options}</tt>
+      # * <tt>:in_named_pointcut  => {PointcutFinder options}</tt>
+      # * <tt>:within_named_pointcuts => {PointcutFinder options}</tt>
+      # * <tt>:within_named_pointcut  => {PointcutFinder options}</tt>
       #
-      # <tt>:pointcuts => pointcut || [pointcut_list]</tt>::
-      # <tt>:pointcut  => pointcut || [pointcut_list]</tt>::
-      # <tt>:within_pointcut  => pointcut || [pointcut_list]</tt>::
-      # <tt>:within_pointcuts => pointcut || [pointcut_list]</tt>::
-      #   One or an array of Pointcut or JoinPoint objects. Mutually-exclusive with the :types, :objects,
-      #   :methods, :attributes, :method_options, and :attribute_options parameters.
+      # ==== Exclude Pointcuts
+      # Exclude the specified pointcuts. The <tt>exclude_</tt> prefix can be used with any of the 
+      # <tt>:pointcuts</tt> and <tt>:named_pointcuts</tt> synonyms. 
+      # * <tt>:exclude_pointcuts => pointcut || [pointcut_list]</tt>
+      # * <tt>:exclude_named_pointcuts => {PointcutFinder options}</tt>
       #
-      # <tt>:ignore_no_matching_join_points => true | false</tt>
-      # <tt>ignore_no_jps => true | false</tt>::
+      # ==== Miscellaneous Options
+      # <tt>:ignore_no_matching_join_points => true | false</tt>::
       #   Do not issue a warning if no join points are actually matched by the aspect. By default, the value
       #   is false, meaning that a WARN-level message will be written to the log. It is usually very helpful
-      #   to be warned when no matches occurred, for diagnostic purposes!
+      #   to be warned when no matches occurred, for debugging purposes! A synonym for this option is
+      #   <tt>ignore_no_jps => true | false</tt>.
       #
-      # Aspect.new also accepts all the same options that Pointcut accepts, including the synonyms for :types,
-      # :methods, etc. It also accepts the "universal" options documented in OptionsUtils.
+      # For other options <i>e.g.,</i> <tt>:types</tt>, <tt>:methods</tt>, Aspect#new accepts all the options 
+      # that Pointcut#new accepts. It also accepts the "universal" options documented in Aquarium::Utils::OptionsUtils.
       def initialize *options, &block
         @first_option_that_was_method = []
         opts = rationalize options
@@ -149,7 +181,7 @@ module Aquarium
 
       alias :== :eql?
   
-      protected
+      private
 
       def rationalize options 
         return {} if options.nil? or options.empty?
@@ -194,7 +226,7 @@ module Aquarium
       
       def calculate_excluded_types
         type_finder_options = {}
-        %w[types types_and_ancestors types_and_descendents].each do |opt|
+        %w[types types_and_ancestors types_and_descendents types_and_nested_types].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
@@ -220,18 +252,10 @@ module Aquarium
       end
       
       def init_pointcuts
-        pointcuts = []
-        if pointcuts_given?
-          pointcuts_given.each do |pointcut|
-            if pointcut.kind_of? Pointcut
-              pointcuts << pointcut 
-            elsif pointcut.kind_of? JoinPoint
-              pointcuts << Pointcut.new(:join_point => pointcut) 
-            else  # a hash of Pointcut.new options?
-              pointcuts << Pointcut.new(pointcut) 
-            end
-          end
-        else
+        set_calculated_excluded_pointcuts determine_excluded_pointcuts
+        pointcuts  = determine_specified_pointcuts
+        pointcuts += determine_named_pointcuts
+        if pointcuts.empty?   # If no PCs specified, then the user must have specified :types, ...
           pc_options = {}
           Pointcut::CANONICAL_OPTIONS.keys.each do |pc_option|
             pco_sym = pc_option.intern
@@ -239,10 +263,38 @@ module Aquarium
           end
           pointcuts << Pointcut.new(pc_options)
         end
-        @pointcuts = Set.new(remove_excluded_join_points_and_empty_pointcuts(pointcuts))
+        @pointcuts = Set.new(remove_excluded_join_points_and_pointcuts(pointcuts))
         warn_if_no_join_points_matched
       end
 
+      def determine_specified_pointcuts
+        pointcuts_given.inject([]) do |pointcuts, pointcut|
+          if pointcut.kind_of? Pointcut
+            pointcuts << pointcut 
+          elsif pointcut.kind_of? JoinPoint
+            pointcuts << Pointcut.new(:join_point => pointcut) 
+          else  # a hash of Pointcut.new options?
+            pointcuts << Pointcut.new(pointcut) 
+          end
+          pointcuts
+        end
+      end
+      
+      def determine_named_pointcuts
+        named_pointcuts_given.inject([]) do |pointcuts, pointcut_spec|
+          found_pointcuts_results = Aquarium::Finders::PointcutFinder.new.find(pointcut_spec) 
+          pointcuts += found_pointcuts_results.found_pointcuts
+          pointcuts
+        end
+      end
+      
+      def determine_excluded_pointcuts
+        exclude_named_pointcuts_given.inject([]) do |excluded_pointcuts, pointcut_spec|
+          found_pointcuts_results = Aquarium::Finders::PointcutFinder.new.find(pointcut_spec) 
+          excluded_pointcuts += found_pointcuts_results.found_pointcuts
+        end
+      end
+      
       def warn_if_no_join_points_matched
         return unless should_warn_if_no_matching_join_points
         @pointcuts.each do |pc|
@@ -261,7 +313,7 @@ module Aquarium
         @specification[:ignore_no_matching_join_points].to_a.first == false
       end
       
-      def remove_excluded_join_points_and_empty_pointcuts pointcuts
+      def remove_excluded_join_points_and_pointcuts pointcuts
         pointcuts.reject do |pc|
           pc.join_points_matched.delete_if do |jp|
             join_point_excluded? jp
@@ -293,13 +345,15 @@ module Aquarium
       end
       
       def add_advice_to_chain join_point, advice_kind, advice
+        # Note that we use the same static join point object throughout the chain. It is
+        # equal to the passed-in join_point, except for additional context information.
         start_of_advice_chain = Aspect.get_advice_chain join_point
         options = @specification.merge({
           :aspect => self,
           :advice_kind => advice_kind, 
           :advice => advice, 
           :next_node => start_of_advice_chain,
-          :static_join_point => join_point})
+          :static_join_point => start_of_advice_chain.static_join_point})
         # New node is new start of chain.
         Aspect.set_advice_chain(join_point, AdviceChainNodeFactory.make_node(options))
       end
@@ -330,22 +384,31 @@ module Aquarium
         type_to_advise = Aspect.type_to_advise_for join_point
         # Note: Must set advice chain, a class variable on the type we're advising, FIRST. 
         # Otherwise the class_eval that follows will assume the @@ advice chain belongs to Aspect!
-        Aspect.set_advice_chain join_point, AdviceChainNodeFactory.make_node(
+        static_join_point = make_static_join_point join_point
+        advice_chain = AdviceChainNodeFactory.make_node(
           :aspect => nil,  # Belongs to all aspects that might advise this join point!
           :advice_kind => :none, 
           :alias_method_name => alias_method_name,
-          :static_join_point => join_point)
-        type_being_advised_text = join_point.instance_method? ? "self.class" : "self"
-        unless Aspect.is_type_join_point?(join_point) 
+          :static_join_point => static_join_point)
+        advice_chain_attr_sym = Aspect.make_advice_chain_attr_sym join_point
+        Aspect.set_advice_chain static_join_point, advice_chain
+        type_being_advised_text = static_join_point.instance_method? ? "self.class" : "self"
+        unless Aspect.is_type_join_point?(static_join_point) 
           type_being_advised_text = "(class << self; self; end)"
         end
-        type_to_advise2 = join_point.instance_method? ? type_to_advise : (class << type_to_advise; self; end)
-        type_to_advise2.class_eval(<<-EOF, __FILE__, __LINE__)
-          #{def_eigenclass_method_text join_point}
-          #{alias_original_method_text alias_method_name, join_point, type_being_advised_text}
+        metatype_to_advise = static_join_point.instance_method? ? type_to_advise : (class << type_to_advise; self; end)
+        metatype_to_advise.class_eval(<<-EOF, __FILE__, __LINE__)
+          #{def_eigenclass_method_text static_join_point}
+          #{alias_original_method_text alias_method_name, static_join_point, type_being_advised_text}
         EOF
       end
       
+      def make_static_join_point join_point
+        static_jp = join_point.dup
+        static_jp.context.advice_kind = advice_kinds_given
+        static_jp
+      end
+      
       # When advising an instance, create an override method that gets advised instead of the types method.
       # Otherwise, all objects will be advised!
       # Note: this also solves bug #15202.
@@ -368,6 +431,13 @@ module Aquarium
         join_point.target_type ? join_point.target_type : (class << join_point.target_object; self; end)
       end
 
+      #--
+      # By NOT dup'ing the join_point, we save about 25% on the overhead! However, we
+      # compromise thread safety, primarily because the join_point's context object will be changed.
+      # TODO Refactor context out of static join point part.
+      # Note that we have to assign the parameters and block to the context object in case
+      # the advice calls "proceed" or "invoke_original_join_point" without arguments.
+      #++
       def alias_original_method_text alias_method_name, join_point, type_being_advised_text
         target_self = join_point.instance_method? ? "self" : join_point.target_type.name
         advice_chain_attr_sym = Aspect.make_advice_chain_attr_sym join_point
@@ -375,13 +445,11 @@ module Aquarium
         alias_method :#{alias_method_name}, :#{join_point.method_name}
         def #{join_point.method_name} *args, &block_for_method
           advice_chain = #{type_being_advised_text}.send :class_variable_get, "#{advice_chain_attr_sym}"
-          static_join_point = advice_chain.static_join_point
-          advice_join_point = static_join_point.make_current_context_join_point(
-            :advice_kind => #{advice_kinds_given.inspect}, 
-            :advised_object => #{target_self}, 
-            :parameters => args, 
-            :block_for_method => block_for_method)
-          advice_chain.call advice_join_point, #{target_self}, *args
+          join_point = advice_chain.static_join_point
+          join_point.context.parameters = args
+          join_point.context.block_for_method = block_for_method
+          join_point.context.advised_object = #{target_self}
+          advice_chain.call join_point
         end
         #{join_point.visibility.to_s} :#{join_point.method_name}
         private :#{alias_method_name}
@@ -437,7 +505,6 @@ module Aquarium
         EOF
       end
       
-      # TODO optimize calls to these *_advice_chain methods from other private methods.
       def self.advice_chain_exists? join_point
         advice_chain_attr_sym = self.make_advice_chain_attr_sym join_point
         type_to_advise_for(join_point).class_variable_defined? advice_chain_attr_sym
@@ -481,11 +548,11 @@ module Aquarium
       end
   
       def some_type_object_join_point_or_pc_option_given?
-        pointcuts_given? or join_points_given? or some_type_option_given? or objects_given? 
+        pointcuts_given? or named_pointcuts_given? or join_points_given? or some_type_option_given? or objects_given? 
       end
       
       def some_type_option_given?
-        types_given? or types_and_ancestors_given? or types_and_descendents_given? 
+        types_given? or types_and_ancestors_given? or types_and_descendents_given? or types_and_nested_types_given? 
       end
       
       def self.determine_type_or_object join_point
@@ -515,10 +582,10 @@ module Aquarium
         bad_options(":after_returning can't be used with :after_raising.") if options_given? :after_returning, :after_raising
         bad_options(":exceptions can't be specified except with :after_raising.") if exceptions_given? and not specified_advice_kinds.include?(:after_raising)
         unless some_type_object_join_point_or_pc_option_given? or default_objects_given?
-          bad_options("At least one of :pointcut(s), :join_point(s), :type(s), :type(s)_and_ancestors, :type(s)_and_descendents, or :object(s) is required.") 
+          bad_options("At least one of :pointcut(s), :named_pointcut(s), :join_point(s), :type(s), :type(s)_and_ancestors, :type(s)_and_descendents, :type(s)_and_nested_types, or :object(s) is required.") 
         end
-        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).") 
+        if (pointcuts_given? or named_pointcuts_given?) and (some_type_option_given? or objects_given?)
+          bad_options("Can't specify both :pointcut(s) or :named_pointcut(s) and one or more of :type(s), and/or :object(s).") 
         end
         unless noop
           if (not @specification[:advice].nil?) && @specification[:advice].size > 1