aquarium 0.3.0 → 0.3.1

data/CHANGES

@@ -1,3 +1,46 @@
+== Version 0.3.1
+
+V0.3.1 adds numerous performance improvements, especially in the RSpec suite, and some minor API additions.
+
+Bug fixes:
+N.A.
+
+Enhancements:
+14447	Unify internal handling of reporting errors to the user
+17514	Provide an Aquarium library-wide logger with configuration parameters and instance overrides
+17515	Add an optional warning if an aspect doesn't match any join points
+17516	Remove unnecessary examples that use :types_and_descendents to shorten time to run the RSpec suite
+17565	JoinPoint.new should convert a type name, symbol, or regex to the type and only allow one type
+
+These first two enhancements are related. There is a now an Aquarium::Utils::DefaultLogger
+module with static accessors for getting and setting the "system-wide" logger. 
+
+When instance-level overrides are necessary, the Aquarium::Utils::OptionsUtils provides 
+"universal" options (but currently used only by Aspect and Pointcut) for specifying a logger 
+(with the new :logger parameter), or alternatively, specifying just the output stream 
+(:logger_stream) and/or the severity (:severity, one of the standard library's 
+Logger::Severity-defined constants). If either of the latter two options is specified, a 
+separate logger instance is created, rather than changing parameters for the global logger.
+
+OptionsUtils also supports a :noop parameter, which classes interpret to mean do none (or
+perhaps only some) of the processing. Useful for debugging.
+
+#17515 adds a helpful warning to the system (or aspect-instance's) logger if an aspect 
+matches no join points. This warning will be suppressed if (i) the severity level for the 
+logger is above WARN or (ii) the aspect was created with the option 
+	:ignore_no_matching_join_points => true.
+
+#17516 fixes halved the long execution times for the whole RSpec suite by refactoring some examples
+that used type finders with the :types_and_descendents option unnecessarily. It is a very intensive
+computation! Note that I stubbed out these calls using an aspect with around advise, a useful
+"development-time" aspect. See Aquarium::TypeUtilsStub (in spec_example_types.rb) and how it's used
+in pointcut_spec.rb. Using this technique and other optimizations, the time to run the suite was 
+reduced from ~5 minutes to about 1 minute.
+ 
+#17565 fixes a "hole" in JoinPoint, where it doesn't confirm that a specified type string, symbol
+or regex matches a class that exists and only one class. Now it does and it stores the type, rather
+than the original "specification" for it.
+
 == Version 0.3.0
 
 V0.3.0 adds numerous improvements to the DSL, making aspect specification more intuitive and 

data/UPGRADE

@@ -1,9 +1,15 @@
-== Upgrading to Aquarium-0.3.0
+== Updating to Aquarium-0.3.1
+
+There should be no upgrade issues with this release. However, the enhancement #17565 now ensures that a
+JoinPoint is only specified with one type and a type that actually exists, when a string, symbol, or
+regex is used to specify the type. 
+
+== Updating to Aquarium-0.3.0
 
 There are no known upgrade issues with this release. Although many new synonyms were added for API method
 parameters, all changes are backwards compatible.
 
-== Upgrading to Aquarium-0.2.0
+== Updating to Aquarium-0.2.0
 
 This release changes the expected advice parameter list from |join_point, *method_args| to
 |join_point, object, *method_args|, where "object" is the current object receiving the message
@@ -14,22 +20,22 @@ Aquarium will raise an exception if the advice block or proc has this obsolete s
 
 Note that "JoinPoint#Context.advised_object" is still supported, even if it is now less useful.
 
-== Upgrading to Aquarium-0.1.8
+== Updating to Aquarium-0.1.8
 
 V0.1.7 did not successfully "register" at rubyforge. This releases fixes that problem and also adds
 several feature enhancements and refactorings. There are no known upgrade issues.
 
-== Upgrading to Aquarium-0.1.7
+== Updating to Aquarium-0.1.7
 
 This is primarily a bug-fix release, so there should be no upgrading or incompatibility issues.
 
-== Upgrading to Aquarium-0.1.6
+== Updating to Aquarium-0.1.6
 
 As described in the CHANGES, the JoinPoint#type, JoinPoint#type=, JoinPoint#object, and JoinPoint#object=
 are now deprecated. Client code that uses these methods will still work, but warning messages will be 
 written to STDOUT. See CHANGES for more details. 
 
-== Upgrading to Aquarium-0.1.5
+== Updating to Aquarium-0.1.5
 
 This is mostly a bug-fix release, but it did have to introduce one API change, as described in the 
 CHANGES. In particular, the aspect "DSL" methods are no longer automatically to Object, as some of 
@@ -69,6 +75,6 @@ object.extend(Aquarium::Aspects::DSL::AspectDSL)
 
 See the CHANGES for more details.
 
-== Upgrading existing code to Aquarium-0.1.0
+== Updating existing code to Aquarium-0.1.0
 
 This is the first release of Aquarium.

data/examples/method_tracing_example_spec.rb

@@ -79,8 +79,11 @@ end
 
 describe "An example with advice on the public instance methods (excluding ancestor methods) of Bar" do
   it "should not trace any calls to the public methods defined by the included BarModule" do
+    # Suppress warnings about no join points matched with :ignore_no_matching_join_points => true 
     aspect = Aquarium::Aspects::Aspect.new :around, 
-      :invocations_of => :all_methods, :for_type => Aquarium::Bar, :restricting_methods_to => :exclude_ancestor_methods do |execution_point, obj, *args|
+      :invocations_of => :all_methods, :for_type => Aquarium::Bar, 
+      :restricting_methods_to => :exclude_ancestor_methods,
+      :ignore_no_matching_join_points => true do |execution_point, obj, *args|
       begin
         obj.log "Entering: #{execution_point.target_type.name}##{execution_point.method_name}: args = #{args.inspect}"
         execution_point.proceed

data/lib/aquarium/aspects/aspect.rb

@@ -35,7 +35,8 @@ module Aquarium
       CANONICAL_OPTIONS = Pointcut::CANONICAL_OPTIONS.merge({
         "advice"            => %w[action do_action use_advice advise_with invoke call],
         "pointcuts"         => %w[pointcut within_pointcuts within_pointcut on_pointcuts on_pointcut],
-        "exclude_pointcuts" => %w[exclude_pointcut exclude_on_pointcut exclude_on_pointcuts exclude_within_pointcut exclude_within_pointcuts]
+        "exclude_pointcuts" => %w[exclude_pointcut exclude_on_pointcut exclude_on_pointcuts exclude_within_pointcut exclude_within_pointcuts],
+        "ignore_no_matching_join_points" => %[ignore_no_jps]
       })
          
       ALL_ALLOWED_OPTIONS = CANONICAL_OPTIONS.keys.inject([]) {|ary,i| ary << i << CANONICAL_OPTIONS[i]}.flatten +
@@ -103,15 +104,18 @@ module Aquarium
       #   One or an array of Pointcut or JoinPoint objects. Mutually-exclusive with the :types, :objects,
       #   :methods, :attributes, :method_options, and :attribute_options parameters.
       #
-      # <tt>:noop</tt>::
-      #   Does not actually advise any join points. Useful for testing.
+      # <tt>:ignore_no_matching_join_points => true | false</tt>
+      # <tt>ignore_no_jps => 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!
       #
-      # It also accepts all the same options that Pointcut accepts, including the synonyms for :types,
-      # :methods, etc.
+      # 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.
       def initialize *options, &block
         @first_option_that_was_method = []
         opts = rationalize options
-        init_specification opts, canonical_options, &block
+        init_specification opts, CANONICAL_OPTIONS, &block
         init_pointcuts
         validate_specification
         return if noop
@@ -126,9 +130,6 @@ module Aquarium
         get_jps :join_points_not_matched
       end
       
-      def canonical_options
-        CANONICAL_OPTIONS
-      end
       def all_allowed_option_symbols
         ALL_ALLOWED_OPTION_SYMBOLS + @first_option_that_was_method
       end
@@ -213,8 +214,25 @@ module Aquarium
           pointcuts << Pointcut.new(pc_options)
         end
         @pointcuts = Set.new(remove_excluded_join_points_and_empty_pointcuts(pointcuts))
+        warn_if_no_join_points_matched
       end
 
+      def warn_if_no_join_points_matched
+        return unless should_warn_if_no_matching_join_points
+        @pointcuts.each do |pc|
+          if pc.join_points_matched.size > 0
+            return
+          end
+        end
+        logger.warn "Warning: No join points were matched. The options specified were #{@original_options.inspect}"
+      end
+      
+      def should_warn_if_no_matching_join_points
+        @specification[:ignore_no_matching_join_points].nil? or 
+        @specification[:ignore_no_matching_join_points].empty? or 
+        @specification[:ignore_no_matching_join_points].to_a.first == false
+      end
+      
       def remove_excluded_join_points_and_empty_pointcuts pointcuts
         pointcuts.reject do |pc|
           pc.join_points_matched.delete_if do |jp|
@@ -328,7 +346,6 @@ module Aquarium
         Aspect.is_type_join_point?(join_point) ? "" : "remove_method :#{join_point.method_name}"
       end
 
-      # TODO Move to JoinPoint
       def self.is_type_join_point? join_point
         Aquarium::Utils::TypeUtils.is_type? join_point.type_or_object
       end
@@ -473,7 +490,7 @@ module Aquarium
         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 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.") 
+          bad_options("At least one of :pointcut(s), :type(s), :type(s)_and_ancestors, :type(s)_and_descendents, :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).") 

data/lib/aquarium/aspects/exclusion_handler.rb

@@ -18,7 +18,7 @@ module Aquarium
         end
       end
 
-      # Using @specification[:exclude_join_points].include?(jp) doesn't always work correctly (it probably uses equal())!
+      # Using @specification[:exclude_join_points].include?(jp) doesn't always work correctly (it probably uses equal?())!
       def is_excluded_join_point? jp
         return false if @specification[:exclude_join_points].nil?
         @specification[:exclude_join_points].find {|jp2| jp2 == jp || jp2.eql?(jp)}

data/lib/aquarium/aspects/join_point.rb

@@ -17,6 +17,20 @@ module Aquarium
         alias :target_object  :advised_object
         alias :target_object= :advised_object=
         
+        # Create a join point object. It must have one and only type _or_ object and one method or the special keywords <tt>:all</tt>.
+        # Usage:
+        #  join_point = JoinPoint.new.find :type => ..., :method_name => ... [, (:class_method | :instance_method) => (true | false) ]
+        # where
+        # <tt>:type => type_or_type_name_or_regexp</tt>::
+        #   A single type, type name or regular expression matching only one type. One and only one
+        #   type _or_ object is required. An error is raised otherwise.
+        #
+        # <tt>:method_name => method_name_or_sym</tt>::
+        # <tt>:method => method_name_or_sym</tt>::
+        #   A single method name or symbol. Only one is allowed, although the special flag <tt>:all</tt> is allowed.
+        #
+        # <tt>(:class_method | :instance_method) => (true | false)</tt>::
+        #   Is the method a class or instance method? Defaults to <tt>:instance_method => true</tt>.
         def initialize options
           update options
           assert_valid options
@@ -91,7 +105,7 @@ module Aquarium
       end
       
       def initialize options = {}
-        @target_type     = options[:type]
+        @target_type     = resolve_type options
         @target_object   = options[:object]
         @method_name     = options[:method_name] || options[:method]
         class_method     = options[:class_method].nil? ? false : options[:class_method]
@@ -143,24 +157,26 @@ module Aquarium
         new_jp
       end
 
+      # Needed for comparing this field in #compare_field
+      def instance_method
+        @instance_method
+      end
+      
       # We require the same object id, not just equal objects.
       def <=> other
         return 0  if object_id == other.object_id 
         return 1  if other.nil?
-        result = self.class <=> other.class 
-        return result unless result == 0
-        result = (self.target_type.nil? and other.target_type.nil?) ? 0 : self.target_type.to_s <=> other.target_type.to_s 
+        result = self.class <=> other.class
         return result unless result == 0
-        result = (self.target_object.nil? and other.target_object.nil?) ? 0 : self.target_object.object_id <=> other.target_object.object_id 
+        result = compare_field(:target_object, other) {|f1,f2| f1.object_id <=> f2.object_id}
         return result unless result == 0
-        result = (self.method_name.nil? and other.method_name.nil?) ? 0 : self.method_name.to_s <=> other.method_name.to_s 
+        result = compare_field(:instance_method, other) {|f1,f2| boolean_compare(f1,f2)}
         return result unless result == 0
-        result = self.instance_method? == other.instance_method?
-        return 1 unless result == true
-        return  0 if  self.context.nil? and  other.context.nil?
-        return -1 if  self.context.nil? and !other.context.nil?
-        return  1 if !self.context.nil? and other.context.nil?
-        return self.context <=> other.context 
+        [:target_type, :method_name, :context].each do |field|
+          result = compare_field field, other
+          return result unless result == 0
+        end
+        0
       end
 
       def eql? other
@@ -179,9 +195,37 @@ module Aquarium
   
       protected
   
+      def compare_field field_reader, other
+        field1 = self.method(field_reader).call
+        field2 = other.method(field_reader).call
+        if field1.nil? 
+          return field2.nil? ? 0 : -1
+        else
+          return 1 if field2.nil?
+        end
+        block_given? ? (yield field1, field2) : (field1 <=> field2)
+      end
+      
+      def boolean_compare b1, b2
+        return 0 if b1 == b2
+        return b1 == true ? 1 : -1
+      end
+      
+      def resolve_type options
+        type = options[:type]
+        return type if type.nil?  # okay, if they specified an object!
+        return type if type.kind_of? Module
+        found = Aquarium::Finders::TypeFinder.new.find :type => type
+        if found.matched.empty?
+          bad_attributes("No type matched the string or regular expression: #{type}", options)
+        elsif found.matched.size > 1
+          bad_attributes("More than one type matched the string or regular expression: #{type}", options)
+        end
+        found.matched.keys.first
+      end
+
       # Since JoinPoints can be declared for non-existent methods, tolerate "nil" for the visibility.
-      def assert_valid options
-        error_message = ""
+      def assert_valid options, error_message = ""
         error_message << "Must specify a :method_name. "            unless method_name
         error_message << "Must specify either a :type or :object. " unless (target_type or  target_object)
         error_message << "Can't specify both a :type or :object. "  if     (target_type and target_object)

data/lib/aquarium/aspects/pointcut.rb

@@ -158,8 +158,10 @@ module Aquarium
       #   Exclude the specified types and their descendents, ancestors.
       #   If you want to exclude both the descendents _and_ ancestors, use both options.
       #
+      # Pointcut.new also accepts all the "universal" options documented in OptionsUtils.
       def initialize options = {} 
-        init_specification options, canonical_options
+        init_specification options, CANONICAL_OPTIONS
+        return if noop
         init_candidate_types 
         init_candidate_objects
         init_candidate_join_points
@@ -177,8 +179,8 @@ module Aquarium
          candidate_types == other.candidate_types && 
          candidate_types_excluded == other.candidate_types_excluded && 
          candidate_objects == other.candidate_objects && 
-         join_points_matched == other.join_points_matched &&
-         join_points_not_matched == other.join_points_not_matched) 
+         join_points_not_matched == other.join_points_not_matched &&
+         join_points_matched == other.join_points_matched)  # not_matched is probably smaller, so do first.
       end
   
       alias :== :eql?
@@ -220,9 +222,6 @@ module Aquarium
 
       ALL_ALLOWED_OPTION_SYMBOLS = ALL_ALLOWED_OPTIONS.map {|o| o.intern}
          
-      def canonical_options
-        CANONICAL_OPTIONS
-      end
       def all_allowed_option_symbols
         ALL_ALLOWED_OPTION_SYMBOLS
       end

data/lib/aquarium/extras/design_by_contract.rb

@@ -1,6 +1,6 @@
 # A simple Design by Contract module. Adds advice to test that the contract, which is specified with
 # a block passes. Note that it doesn't attempt to handle the correct behavior under contract 
-# inheritance (TODO).
+# inheritance.
 # Warning: This module automatically includes Aquarium::Aspects::DSL::AspectDSL into the class with 
 # the contract and it adds the :precondition, :postcondition, and the :invariant methods to Object! 
 require 'aquarium'

data/lib/aquarium/finders/method_finder.rb

@@ -90,7 +90,7 @@ module Aquarium
       # +Derived+ class that is defined in the +Base+ class, you won't find it!
       #
       def find options = {}
-        init_specification options, canonical_options
+        init_specification options, CANONICAL_OPTIONS
         return Aquarium::Finders::FinderResult.new if nothing_to_find?
         types_and_objects = input_types + input_objects
         method_names_or_regexps = input_methods
@@ -126,9 +126,6 @@ module Aquarium
 
       ALL_ALLOWED_OPTION_SYMBOLS = ALL_ALLOWED_OPTIONS.map {|o| o.intern}
          
-      def canonical_options
-        CANONICAL_OPTIONS
-      end
       def all_allowed_option_symbols
         ALL_ALLOWED_OPTION_SYMBOLS
       end

data/lib/aquarium/finders/type_finder.rb

@@ -14,6 +14,8 @@ module Aquarium
       include Aquarium::Utils::ArrayUtils
       include Aquarium::Utils::TypeUtils
 
+      TYPES_SYNONYMS = %w[name names type types]
+      
       # Usage:
       #  finder_result = TypeFinder.new.find [options => [...] ]
       # where
@@ -88,11 +90,13 @@ module Aquarium
       # Note: a common idiom in aspects is to include descendents of a type, but not the type
       # itself. You can do as in the following example:
       #   <tt>... :type_and_descendents => "Foo", :exclude_type => "Foo" 
+      # TODO: Use the new OptionsUtils.
       def find options = {}
         result   = Aquarium::Finders::FinderResult.new
         excluded = Aquarium::Finders::FinderResult.new
         unknown_options = []
         input_type_nil = false
+        noop = false
         options.each do |option, value|
           unless TypeFinder.is_recognized_option option
             unknown_options << option
@@ -102,6 +106,8 @@ module Aquarium
             input_type_nil = true
             next
           end
+          noop = value if option == :noop
+          next if noop
           if option.to_s =~ /^exclude_/
             excluded << find_matching(value, option)
           else
@@ -122,11 +128,12 @@ module Aquarium
       end
 
       def self.is_recognized_option option_or_symbol
-        %w[name names type types].each do |t|
+        TYPES_SYNONYMS.each do |t|
           ['', "exclude_"].each do |excl| 
             return true if ["#{excl}#{t}", "#{excl}#{t}_and_descendents", "#{excl}#{t}_and_ancestors"].include?(option_or_symbol.to_s)
           end
         end
+        return true if option_or_symbol.to_s.eql?("noop")
         false
       end
   

data/lib/aquarium/utils.rb

@@ -6,6 +6,7 @@ require 'aquarium/utils/method_utils'
 require 'aquarium/utils/name_utils'
 require 'aquarium/utils/options_utils'
 
+require 'aquarium/utils/default_logger'
 require 'aquarium/utils/html_escaper'
 require 'aquarium/utils/invalid_options'
 require 'aquarium/utils/logic_error'

data/lib/aquarium/utils/default_logger.rb

@@ -0,0 +1,20 @@
+require 'logger'
+
+module Aquarium
+  module Utils
+    # DefaultLogger holds the Aquarium-wide "default" Ruby standard library logger.
+    # Individual objects may chose to create their own loggers.
+    module DefaultLogger
+      
+      @@default_logger = Logger.new STDERR
+      
+      def self.logger
+        @@default_logger
+      end
+      
+      def self.logger= logger
+        @@default_logger = logger
+      end
+    end
+  end
+end