aquarium 0.4.1 → 0.4.2

data/CHANGES

@@ -1,3 +1,66 @@
+== Version 0.4.2
+
+V0.4.2 adds a few bug fixes and enhancements, greatly improved RDoc output, and internal 
+refactorings to improve performance.
+
+Bug fixes:
+15202	Intermittent confusion between classes and objects when invoking advice
+19262	Just putting join_point argument in advice block causes mysterious method missing error.
+19321	Advice overhead is too high (ongoing improvements)
+
+Enhancements:
+13403	Support recursion into nested types without requiring "tricky" regular expressions
+13406	"Sugar" for adding methods and attributes to types
+18537	Provide a search for all pointcut constants
+19666	Improve the RDoc output
+19119	Provide an "after_raising" type of advice that lets you handle the exception.
+
+#15202: I never figured out the cause of this problem, but it hasn't been seen since late last 
+year, so I suspect it disappeared as a side effect of on-going refactoring and enhancements.
+
+#19262: If you just specified "|jp|" for an advice block, you would sometimes get a method missing
+error. I never figured out exactly why, but it was somehow related to passing the usual three 
+arguments internally, where the last two would be ignored in this case. Now, the code checks the 
+arity and only passes the join point in this case.  
+
+#19321: I removed some of the wasted object creation and initialization in advice invocation, 
+improving the overhead by about 40%. However, it is still at least 10x higher than simple method
+aliasing, so I want to make more improvements. (I did not close this item.)
+
+#13403: I added new options :types_and_nested_types and :types_and_nested that are analogous to
+the similar "ancestors" and "descendents" options. The nested option will return the specified 
+types and any types they "enclose". There are also corresponding "exclude" options.
+
+#13406: I've decided not to do this, as it really isn't the "simplest thing that could possibly
+work." It's easy enough for the user to define a module of new behavior and just use
+"obj.extend(module)". However, when the user needs to do this over a set of types, Aquarium's
+TypeFinder can be helpful, so I added an example to the Examples code and page.
+
+#18537: I've provided an example of the design approach where you define pointcuts in a class,
+as a kind of "aspect interface" and write aspects that specify those pointcuts. The problem has
+been that you had to name every single such pointcut explicitly. There was no "finder" option,
+as for types, methods, etc. Now there is a pointcut finder option with a new option 
+":named_pointcuts" for Aspect.new to specify a search for pointcuts in a set of types matching
+a name specification. Either constants or class variables will be matched (or both).
+
+#19666: The rdoc for the key classes was cleaned up so it "renders" better. Feedback is welcome.
+
+#19119: I finished the previously-incomplete support for allowing advice to change the raised
+exception, in both after and after_raising advice. A common scenario is to wrap the thrown
+exception in another. For example, a low-level, service-specific exception (like a database
+error) in a higher-level, more generic application exception. 
+
+You still can't rescue the exception completely in after_raising and after advice; the value
+for the exception in 
+  joinpoint.context.raised_exception
+when the advice returns will be raised by Aquarium. I think that permitting after_raising or 
+after advice to "eat" the exception could cause subtle issues with scope and variable binding. 
+It would also probably violate the "principle of least surprise"; the advice code that rescues 
+the exception would not be as "obvious" to the reader as the familiar idiom of rescue clauses
+that we are accustomed to using. Therefore, if you want to recover completely from an exception,
+use rescue clauses in around advice.
+
+
 == Version 0.4.1
 
 V0.4.1 adds a few bug fixes, a few more user examples, internal refactoring and some performance

data/ParseTreePlay.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'parse_tree'
+
+class Foo
+  attr_accessor :name
+  def intialize name
+    @name = name
+  end
+end
+
+p ParseTree.new.parse_tree(Foo)
+
+class Bar
+  attr_accessor :name
+  def initialize name
+    @name = name
+  end
+  def attrset x
+    p "calling attrset for #{x}"
+    super
+  end
+end
+
+b=Bar.new "name"
+b.name = "name2"

data/README

@@ -143,7 +143,7 @@ You can pass in pointcuts defined elsewhere:
 	around :pointcuts => my_pointcut do |jp, obj, *args| ...         # Pass in a pointcut
 	around :pointcuts => [my_pointcut, ...] do |jp, obj, *args| ...  # Pass in a pointcut array
 
-As a convenience, since a JoinPoint is like a Pointcut with one element, you can pass a JoinPoint object where Pointcut objects are expected:
+As a convenience, since a JoinPoint is a Pointcut with one element, you can pass a JoinPoint object where Pointcut objects are expected:
 
 my_join_point1 = JoinPoint.new :type => Foo::Bar, :method => do_this
 my_join_point2 = JoinPoint.new :type => Foo::Bar, :method => do_that
@@ -161,6 +161,13 @@ You can specify a single type, a type name, a type regular expression, or an arr
 
 Everywhere "type" is used, you can substitute "class", "classes", "module", or "modules". Note that they are treated as synonyms; there is currently no enforcement that the values passed with ":class", for example, are actually classes, not modules.
 
+There are also several prepositional prefixes allowed for any of the synonyms. E.g.,
+
+	around :for_types = A, ...
+	around :on_types = A, ...
+	around :in_types = A, ...
+	around :within_types = A, ...
+
 Using the plural versions of the synonyms with method specifications sometimes read better:
 
 	around :calls_to => :all_methods, :on_types => [A, B, ...], ...
@@ -252,6 +259,8 @@ You can specify attributes, which are actually convenience methods for the attri
 	around :attributes = /^foo/, ...
 	around :attributes = [/^foo/, /bar$/], ...
 
+Again, it's important to remember that actually advising the attribute accesses is not done; it's the public accessor methods that are advised! This may change in a future release.
+
 You can specify a "Pointcut" that encapsulates one or more pre-defined Pointcuts or JoinPoints.
 
 	around :pointcut = pc, ...                                     # for pre-defined pointcut "pc"
@@ -262,15 +271,57 @@ You can specify a "Pointcut" that encapsulates one or more pre-defined Pointcuts
 
 Using the plural versions of the synonyms, with method specifications so they read better:
 
+	around :for_pointcuts => [pc1, pc2, ...], ...
 	around :on_pointcuts => [pc1, pc2, ...], ...
 	around :in_pointcuts => [pc1, pc2, ...], ...
 	around :within_pointcuts => [pc1, pc2, ...], ...
 
+Since V0.4.2, you can also specify "named" pointcuts, which are searched for just like methods in types (as discussed below).
+For example, if several classes in module "App" define class constant pointcuts named STATE_CHANGE, the following expression
+in an around advice aspect will match all of them:
+
+	around :named_pointcuts => { :constants_matching => :STATE_CHANGE, :in_types => /App::.*/ } ...
+
+For the type specification, which is required, any valid option for the TypeFinder class is allowed. 
+
+You can also match on class variables, using ":class_variables_matching". To match on either kind of definition, use just
+":matching". If no :*matching is specified, then any class constant or variable Pointcut found will be matched. 
+
+Here are the variaus :*matching options and their synonyms:
+
+	around :named_pointcuts => { :constants_matching            => :STATE_CHANGE, ... } ...   # class constants only
+	around :named_pointcuts => { :constants_named               => :STATE_CHANGE, ... } ...
+	around :named_pointcuts => { :constants_with_names_matching => :STATE_CHANGE, ... } ...
+
+	around :named_pointcuts => { :class_variables_matching            => :STATE_CHANGE, ... } ...   # class variables only
+	around :named_pointcuts => { :class_variables_named               => :STATE_CHANGE, ... } ...
+	around :named_pointcuts => { :class_variables_with_names_matching => :STATE_CHANGE, ... } ...
+
+	around :named_pointcuts => { :matching            => :STATE_CHANGE, ... } ...   # class constants and variables
+	around :named_pointcuts => { :named               => :STATE_CHANGE, ... } ...
+	around :named_pointcuts => { :with_names_matching => :STATE_CHANGE, ... } ...
+
+The :*matching options take a name, regular expression or array of the same (you can mix names and regular expressions).
+
+You can also use the following synonyms for :named_pointcuts:
+
+	around :named_pointcut => {...}
+	around :for_named_pointcut => {...}
+	around :on_named_pointcut => {...}
+	around :in_named_pointcut => {...}
+	around :within_named_pointcut => {...}
+	around :for_named_pointcuts => {...}
+	around :on_named_pointcuts => {...}
+	around :in_named_pointcuts => {...}
+	around :within_named_pointcuts => {...}
+	
 You can specifically exclude particular pointcuts, join points, types, objects, methods, or attributes. This is useful when you specify a list or regular expression of "items" to match and you want to exclude some of the items.
 Note that there is an open bug (#15202) that appears to affect advising types, unadvising the types, then advising objects of the same types. (This is not likely to happen a lot in real applications, but it shows up when running Aquarium's specs.)
 
 	around ..., :exclude_pointcut = pc, ...
 	around ..., :exclude_pointcuts = [pc, ...]
+	around ..., :exclude_named_pointcut = {...}
+	around ..., :exclude_named_pointcuts = {...}
 	around ..., :exclude_join_point = jp, ...
 	around ..., :exclude_join_points = [jp, ...]
 	around ..., :exclude_type = t, ...
@@ -286,7 +337,7 @@ Note that there is an open bug (#15202) that appears to affect advising types, u
 	around ..., :exclude_attribute = a, ...
 	around ..., :exclude_attributes = [a, ...]
 
-All the same synonyms for :types, :objects, and :methods apply here as well (after the "exclude_" prefix).
+All the same synonyms for :pointcuts, :named_pointcuts, :types, :objects, and :methods apply here as well (after the "exclude_" prefix).
 
 You can advice methods before execution:
 
@@ -345,7 +396,7 @@ Rather than passing a block as the advice, you can pass a previously-created Pro
 	around :type => [...], :methods => :all, :call => advice         # synonym for advice.
 	around :type => [...], :methods => :all, :invoke => advice       # synonym for advice.
 
-Finally, when running in JRuby, you can advise Java types! See the examples in the separate RSpec suite in the "jruby" directory.
+Finally, when running in JRuby, you can advise Java types! See the examples in the separate RSpec suite in the "jruby" directory and the discussion above concerning known limitations.
 
 === Packages
 
@@ -412,4 +463,5 @@ See http://aquarium.rubyforge.org for further documentation.
 My colleagues in the AOSD community, in particular those who developed AspectJ, have been a big inspiration.
 The RSpec team, in particular David Chelimsky, have really inspired my thinking about what's possible in Ruby, especially in the realm of DSLs. I also cribbed parts of the RSpec Rake process ;)
 My colleagues at Object Mentor are an endless source of insight and inspiration.
+Finally, a number of users have contributed valuable feedback. In particular, thanks to Brendan L., Matthew F., and Mark V. 
  

data/RELEASE-PLAN

@@ -46,11 +46,19 @@ advise Java types!
 
 === Version 0.5
 
-My goals for this release are performance improvements (#19321) and investigating some ideas
+My goals for this release include more performance improvements (#19321) and investigating some ideas
 for a real DSL, meaning declarative statements in blocks, rather than method arguments. It will be 
 redundant somewhat with the existing "method-argument form", as it exists today, but it will set
 the stage for much more complex aspect definitions than would be convenient with the current form.
 
+Another big change is to make pointcut evaluation and advice application happen continuous at runtime,
+rather than only when the aspect is defined. This would eliminate subtle problems related to the order
+of loading and also makes the declarative nature of aspects more fully realized. For example, if I 
+declare an aspect for all types in a module namespace, it should still apply to nested types defined
+or loaded after the aspect is defined. This enhancement will also make it easier to define reusable
+and "abstract" aspects, where they aren't applied immediately, but only when extended by "concrete"
+aspects, for example.
+
 I'll maintain the current form for backwards compatibility and also because it is convenient for
 simpler aspects.
 

data/TODO.rb

@@ -1,26 +1,186 @@
 
 # New DSL ideas.
-Aspect.new do
+Aspect.new {
+  after
+  pointcut {
+    within_context_of named_pointcuts {
+      matching /^STATE/
+      within_types_and_descendents /Foo|Bar/
+    } and not_within_context_of pointcuts {
+      calls_from /callback$/
+      in_types_and_descendents_of /Active/
+    } and pointcut {
+      pointcut {
+        calls_to /index/
+        in_types_and_ancestors_of [String, Fixnum]
+      } or pointcut {
+        calls_to /outdex/
+        in_types_and_ancestors_of /^Foo/
+      }    
+    }
+  }
+  invoke_advice do |join_point, object, *args|
+    p join_point.inspect
+  end
+}
 
-  pointcut do
-    named_pointcuts :matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/
-    or {
+Aspect.new {
+  after
+  pointcut {
+    within_context_of {
+      pointcuts_named /^STATE/
+      within_types_and_descendents /Foo|Bar/
+    } and not within_context_of {
+      calls_to /_handle$/
+      in_types_and_descendents_of /Active/
+    } and pointcut {
+      pointcut {
+        calls_to /index/
+        in_types_and_ancestors_of [String, Fixnum]
+      } or pointcut {
+        calls_to /outdex/
+        in_types_and_ancestors_of /^Foo/
+      }    
+    }
+  }
+  invoke_advice do |join_point, object, *args|
+    p join_point.inspect
+  end
+}
+
+Aspect.new {
+  after {
+    calls_to /index/
+    in_types_and_ancestors_of [String, Fixnum]
+  } or after {
+    calls_to /outdex/
+    in_types_and_ancestors_of /^Foo/
+  } within_context_of {
+    pointcuts_named /^STATE/
+    within_types_and_descendents /Foo|Bar/
+  } and not within_context_of {
+      calls_to /_handle$/
+      in_types_and_descendents_of /Active/
+    } and pointcut {
+      pointcut {
+        calls_to /index/
+        in_types_and_ancestors_of [String, Fixnum]
+      } or pointcut {
+        calls_to /outdex/
+        in_types_and_ancestors_of /^Foo/
+      }    
+    }
+  }
+  invoke_advice do |join_point, object, *args|
+    p join_point.inspect
+  end
+}
+
+Aspect.new {
+  after
+  pointcut {
+    within named_pointcuts {
+      matching /^STATE/
+      within_types_and_descendents /Foo|Bar/
+    } 
+    not_within pointcuts {
+      calls_from /callback$/
+      in_types_and_descendents_of /Active/
+    } 
+    pointcut {
       calls_to /index/
       in_types_and_ancestors_of [String, Fixnum]
-    } and {
+    } 
+    pointcut {
       calls_to /outdex/
       in_types_and_ancestors_of /^Foo/
-    }    
-  end
-  within_pointcuts do
-    calls_to main
-    in_type TopLevel
+    }
+  }
+  invoke_advice do |join_point, object, *args|
+    p join_point.inspect
   end
-  but_not_within pointcuts do
-    calls_from /callback$/
-    in_types_and_descendents_of /Active/
+}
+
+Aspect.new {
+  after
+  pointcut {
+    within named_pointcuts {
+      matching /^STATE/
+      within_types_and_descendents /Foo|Bar/
+    }.and_not_within pointcuts {
+      calls_from /callback$/
+      in_types_and_descendents_of /Active/
+    } {
+      pointcut {
+        calls_to /index/
+        in_types_and_ancestors_of [String, Fixnum]
+      } 
+      pointcut {
+        calls_to /outdex/
+        in_types_and_ancestors_of /^Foo/
+      }
+    }
+  }
+  invoke_advice do |join_point, object, *args|
+    p join_point.inspect
   end
-  after do |join_point, object, *args|
+}
+
+Aspect.new {
+  after
+  pointcut {
+    within {
+      named_pointcuts {
+        matching /^STATE/
+        within_types_and_descendents /Foo|Bar/
+      } 
+      exclude_pointcuts {
+        calls_from /callback$/
+        in_types_and_descendents_of /Active/
+      }
+    } 
+    pointcut {
+      calls_to /index/
+      in_types_and_ancestors_of [String, Fixnum]
+    } 
+    pointcut {
+      calls_to /outdex/
+      in_types_and_ancestors_of /^Foo/
+    }
+  }
+  invoke_advice do |join_point, object, *args|
     p join_point.inspect
   end
-end
+}
+
+
+
+after :named_pointcuts => { :matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :named_pointcuts => { :with_names_matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :named_pointcuts => { :named => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+
+after :named_pointcuts => { :constants_matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :named_pointcuts => { :constants_with_names_matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :named_pointcuts => { :constants_named => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+
+after :named_pointcuts => { :class_variables_matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :named_pointcuts => { :class_variables_with_names_matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :named_pointcuts => { :class_variables_named => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+
+after :constant_pointcuts => { :matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :class_variable_pointcuts => { :matching => /^state/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+  
+regex=  /(constants_|instance_variables_|class_variables_)?(with_)?(named_matching|named|matching)/
+after :pointcuts => { :named => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :pointcuts => { :constants_named => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :pointcuts => { :class_variables_named => /^state/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :pointcuts => { :instance_variables_named => /^state/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+
+after :named_pointcuts => { :matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :named_pointcuts => { :matching => 'STATE_CHANGE', :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :constant_pointcuts => { :matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :class_variables_pointcuts => { :matching => /^state/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+after :instance_variables_pointcuts => { :matching => /^state/, :within_types_and_descendents => /Foo|Bar/ } do ... end
+
+after :pointcuts_matching => { :constants_named => /^STATE/, :within_types_and_ancestors => /Foo|Bar/ }
+after :pointcuts_matching => { :class_variables_named => /^STATE/, :within_types_and_ancestors => /Foo|Bar/ }

data/examples/aspect_design_example.rb

@@ -34,8 +34,20 @@ end
 include Aquarium::Aspects
 
 # Observe state changes in the class, using the class-defined pointcut.
+# 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.
 
-observer = Aspect.new :after, :pointcut => Aquarium::ClassWithStateAndBehavior::STATE_CHANGE do |jp, obj, *args|
+observer1 = Aspect.new :after, 
+  :pointcut => Aquarium::ClassWithStateAndBehavior::STATE_CHANGE do |jp, obj, *args|
+  p "State has changed. "
+  state = obj.state
+  p "  New state is #{state.nil? ? 'nil' : state.inspect}"
+  p "  Equivalent to *args: #{args.inspect}"
+end  
+
+observer2 = Aspect.new :after, :named_pointcuts => {:matching => /CHANGE/, 
+    :within_types => Aquarium::ClassWithStateAndBehavior} do |jp, obj, *args|
   p "State has changed. "
   state = obj.state
   p "  New state is #{state.nil? ? 'nil' : state.inspect}"