aquarium 0.4.0 → 0.4.1

data/CHANGES

@@ -1,3 +1,24 @@
+== Version 0.4.1
+
+V0.4.1 adds a few bug fixes, a few more user examples, internal refactoring and some performance
+improvements.
+
+Bug fixes:
+19116	When an exception is thrown during advice execution, the error message always reports the advice type is :before!
+19261	after_raising DSL method provides no way to specify exceptions
+
+Enhancements:
+18705	Remove duplication and complexity in options-handling code
+19320	Move the Aquarium::...::AspectDSL file to Aquarium::DSL for convenience
+19399	Improve the Design by Contract example
+
+I added a new :exceptions argument (synonym :exception) that takes a single exception or list thereof. 
+You can only use this argument with :after_raising. If you specify exceptions with the latter and use
+the :exceptions argument, the values will be merged.
+
+I thought it was ugly to have to type "include Aquarium::Aspects::DSL::AspectDSL", so I moved the code so
+now it's "include Aquarium::DSL". However, for backwards compatibility, the old module still works.
+
 == Version 0.4.0
 
 V0.4.0 adds specs to characterize and test advising Java classes when running on JRuby and adds several 
@@ -300,7 +321,7 @@ Fixing 13650 required an API change, which is why I've tagged this release "0.1.
 something like "0.1.1" (and the changes don't seem big enough to warrant "0.2.0"...).
 
 Previously, requiring "aquarium.rb" in the top-level "lib" directory would implicitly require 
-lib/aquarium/aspects/dsl/aspect_dsl.rb, which
+lib/aquarium/dsl/aspect_dsl.rb, which
 has Object include the AspectDSL module. This module adds methods like :before and :after to Object. 
 Unfortunately, those methods collide with methods of the same name that Rails adds to Object. It was 
 also a bit presumptuous of me to assume that everyone wanted those methods on Object ;)
@@ -314,22 +335,22 @@ then do the following:
 
 	class MyClass   # reopen "MyClass"
 		# Add the methods as _class_ methods
-		include Aquarium::Aspects::DSL::AspectDSL
+		include Aquarium::DSL
 	end
 
 or, use (class|module)_eval:
 
-	require 'aquarium/aspects/dsl/aspect_dsl'
+	require 'aquarium/dsl/aspect_dsl'
 
 	MyClass.class_eval do
 		# Add the methods as _class_ methods
-		include Aquarium::Aspects::DSL::AspectDSL
+		include Aquarium::DSL
 	end
 
 To add the methods as _instance_ methods on individual objects:
 
 	object = MyClass.new
-	object.extend(Aquarium::Aspects::DSL::AspectDSL)
+	object.extend(Aquarium::DSL)
 
 
 Note: as discussed at http://practicalruby.blogspot.com/2007/02/reopen-with-moduleeval.html, 

data/README

@@ -85,9 +85,9 @@ Here is an example that traces invocations of all public instance methods (inclu
 		result  # block needs to return the result of the "proceed"!
 	end
 
-The advice to execute at each join point is the block. The pointcut is the set of all public instance methods in Foo and Bar. (There are additional options available for specifying class methods, protected methods, excluding inherited (ancestor) methods, etc.) Here is the same example using the convenience DSL that adds aspect methods to Object (available only if you require aquarium/aspects/dsl/object_dsl', since other toolkits, like Rails, define similar methods on Object!).
+The advice to execute at each join point is the block. The pointcut is the set of all public instance methods in Foo and Bar. (There are additional options available for specifying class methods, protected methods, excluding inherited (ancestor) methods, etc.) Here is the same example using the convenience DSL that adds aspect methods to Object (available only if you require aquarium/dsl/object_dsl', since other toolkits, like Rails, define similar methods on Object!).
 
-	require 'aquarium/aspects/dsl/object_dsl'
+	require 'aquarium/dsl/object_dsl'
 	around :calls_to => :all_methods, :on_types => [Foo, Bar] do |join_point, object, *args|
 		p "Entering: #{join_point.target_type.name}##{join_point.method_name} for object #{object}"
 		result = join_point.proceed
@@ -99,23 +99,23 @@ See "examples/method_tracing_example.rb" for a more detailed version of this exa
 
 If you don't want to add these methods to Object, you can also add them individually to modules, classes, or objects:
 
-	require 'aquarium/aspects/dsl/aspect_dsl'  # NOT object_dsl
+	require 'aquarium'
 	...
 	module MyModule
-		include Aquarium::Aspects::DSL::AspectDSL
+		include Aquarium::DSL
 	end
 
 	class MyClass
-		include Aquarium::Aspects::DSL::AspectDSL
+		include Aquarium::DSL
 	end
 
 	my_object = MyOtherClass.new
-	my_object.extend (Aquarium::Aspects::DSL::AspectDSL)
+	my_object.extend (Aquarium::DSL)
 
 If you use the DSL inside a class and omit the :type(s) and :object(s) options, "self" is assumed.
 
 	class Foo
-		include Aquarium::Aspects::DSL::AspectDSL
+		include Aquarium::DSL
 		...
 		def critical_operation *args
 			...
@@ -199,7 +199,7 @@ Some of the synonyms:
 If no types or objects are specified, the object defaults to "self". However, this default is only supported when using the DSL to create an aspect, e.g.,
 
 	class MyClass
-		include Aquarium::Aspects::DSL::AspectDSL
+		include Aquarium::DSL
 		def doit; ...; end
 	
 		around :method => doit, ...   # Implicit :object => self, i.e., MyClass

data/RELEASE-PLAN

@@ -4,7 +4,7 @@
 
 Mostly bug fixes and enhancements. Only "minor" breakages of backwards compatibility.
 
-=== Versions 0.2.0
+=== Versions 0.2
 
 Change the argument list for advice to |join_point, object, *args| from |join_point, *args|, 
 where "*args" are the arguments passed to the invoked join point (method). Since nontrivial 
@@ -13,7 +13,7 @@ advice usually needs the object being advised, it became clear that having to ca
 
 This change will obvious break existing aspects.
 
-=== Versions 0.3+.0
+=== Versions 0.3+
 
 More refinements and simplifications to the API and functionality, including much-needed 
 redundancy reduction. I haven't used mocks much in the specs, but they would help improve the
@@ -43,6 +43,24 @@ composition of complex pointcuts easier.
 
 I also want to ensure full support for running in JRuby. In particular, you should be able to
 advise Java types!
+
+=== Version 0.5
+
+My goals for this release are 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.
+
+I'll maintain the current form for backwards compatibility and also because it is convenient for
+simpler aspects.
+
+=== Version 0.6+
+
+I have been thinking about higher-order abstractions that work above the "Pointcut + Advice
+Model" of Aquarium (and AspectJ...) today. I consider the pointcut + advice model to be an 
+important, maybe essential, building block of AOP, but if that's all AOP is, then we've probably
+already hit the limit of what we can expect AOP to do. That doesn't seem right to me, but it's 
+not at all clear what the higher-order abstractions should be.
 	
 === Version 1.0.0
 

data/TODO.rb

@@ -0,0 +1,26 @@
+
+# New DSL ideas.
+Aspect.new do
+
+  pointcut do
+    named_pointcuts :matching => /^STATE/, :within_types_and_descendents => /Foo|Bar/
+    or {
+      calls_to /index/
+      in_types_and_ancestors_of [String, Fixnum]
+    } and {
+      calls_to /outdex/
+      in_types_and_ancestors_of /^Foo/
+    }    
+  end
+  within_pointcuts do
+    calls_to main
+    in_type TopLevel
+  end
+  but_not_within pointcuts do
+    calls_from /callback$/
+    in_types_and_descendents_of /Active/
+  end
+  after do |join_point, object, *args|
+    p join_point.inspect
+  end
+end

data/UPGRADE

@@ -53,21 +53,21 @@ As an alternative, if you just want these methods added selectively in certain t
 following:
 
 <ruby>
-require 'aquarium/aspects/dsl/aspect_dsl'
+require 'aquarium/dsl/aspect_dsl'
 
 class MyClass   # reopen "MyClass"
 	# Add the methods as _class_ methods
-	include Aquarium::Aspects::DSL::AspectDSL
+	include Aquarium::DSL
 end
 </ruby>
 
 or, use (class|module)_eval:
 <ruby>
-require 'aquarium/aspects/dsl/aspect_dsl'
+require 'aquarium/dsl/aspect_dsl'
 
 MyClass.class_eval do
 	# Add the methods as _class_ methods
-	include Aquarium::Aspects::DSL::AspectDSL
+	include Aquarium::DSL
 end
 </ruby>
 
@@ -75,7 +75,7 @@ To add the methods as _instance_ methods on individual objects:
 
 <ruby>
 object = MyClass.new
-object.extend(Aquarium::Aspects::DSL::AspectDSL)
+object.extend(Aquarium::DSL)
 </ruby>
 
 See the CHANGES for more details.

data/examples/aspect_design_example.rb

@@ -12,7 +12,7 @@ require 'aquarium'
 
 module Aquarium
   class ClassWithStateAndBehavior
-    include Aquarium::Aspects::DSL::AspectDSL
+    include Aquarium::DSL
     def initialize *args
       @state = args
       p "Initializing: #{args.inspect}"

data/examples/aspect_design_example_spec.rb

@@ -11,7 +11,7 @@ require 'aquarium'
 
 module Aquarium
   class ClassWithStateAndBehavior
-    include Aquarium::Aspects::DSL::AspectDSL
+    include Aquarium::DSL
     def initialize *args
       @state = args
     end

data/examples/design_by_contract_example.rb

@@ -33,12 +33,12 @@ Aquarium::PreCond.new.action :a1
 module Aquarium
   class PostCond
     def action *args
-      p "inside :action"
+      args.empty? ? args.dup : args + [:a]
     end
   
     postcondition :calls_to => :action, 
-      :message => "Must pass more than one argument and first argument must be non-empty." do |jp, obj, *args|
-      args.size > 0 && ! args[0].empty?
+      :message => "Must return a copy of the input args with :a appended to it." do |jp, obj, *args|
+      jp.context.returned_value.size == args.size + 1 && jp.context.returned_value[-1] == :a
     end
   end
 end
@@ -49,13 +49,8 @@ begin
 rescue Aquarium::Extras::DesignByContract::ContractError => e
   p e.inspect
 end
-begin
-  Aquarium::PostCond.new.action ""
-rescue Aquarium::Extras::DesignByContract::ContractError => e
-  p e.inspect
-end
 p "This call will pass because the postcondition is satisfied:"
-Aquarium::PostCond.new.action :a1
+Aquarium::PostCond.new.action  :x1, :x2
 
 module Aquarium
   class InvarCond

data/examples/design_by_contract_example_spec.rb

@@ -37,27 +37,25 @@ end
 module Aquarium
   class PostCondExample
     def action *args
-      @state = *args
+      args.empty? ? args.dup : args + [:a]
     end
-    attr_reader :state
-
+  
     postcondition :calls_to => :action, 
-      :message => "Must pass more than one argument and first argument must be non-empty." do |jp, obj, *args|
-      args.size > 0 && ! args[0].empty?
+      :message => "Must return a copy of the input args with :a appended to it." do |jp, obj, *args|
+      jp.context.returned_value.size == args.size + 1 && jp.context.returned_value[-1] == :a
     end
   end
 end
 
 describe "An example using a postcondition" do
   it "should fail at the call exit point if the postcondition is not satisfied." do
-    lambda { Aquarium::PostCondExample.new.action }.should    raise_error(Aquarium::Extras::DesignByContract::ContractError)
-    lambda { Aquarium::PostCondExample.new.action "" }.should raise_error(Aquarium::Extras::DesignByContract::ContractError)
+    lambda { Aquarium::PostCondExample.new.action }.should raise_error(Aquarium::Extras::DesignByContract::ContractError)
   end
 end
 
 describe "An example using a postcondition" do
-  it "should not fail at the call entry point if the postcondition is satisfied." do
-    Aquarium::PostCondExample.new.action :a1
+  it "should not fail at the call exit point if the postcondition is satisfied." do
+    Aquarium::PostCondExample.new.action :x1, :x2
   end
 end
 

data/examples/exception_wrapping_example.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# Example demonstrating "wrapping" an exception; rescuing an exception and 
+# throwing a different one. A common use for this is to map exceptions across
+# "domain" boundaries, e.g., persistence and application logic domains. 
+# Note that you must use :around advice, since :after_raising cannot change
+# the control flow.
+# (However, see feature request #19119)
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'aquarium'
+
+module Aquarium
+  class Exception1 < Exception; end
+  class Exception2 < Exception; end
+  class NewException < Exception; end
+
+  class Raiser
+    def raise_exception1
+      raise Exception1.new("one")
+    end
+    def raise_exception2
+      raise Exception2.new("two")
+    end
+  end
+end
+
+Aquarium::Aspects::Aspect.new :around, 
+  :calls_to => /^raise_exception/, :in_type => Aquarium::Raiser do |jp, obj, *args|
+  begin
+    jp.proceed
+  rescue Aquarium::Exception1 => e
+    raise Aquarium::NewException.new("Old exception message was \"#{e.message}\"")
+  end
+end
+
+p "The raised Aquarium::Exception2 raised here won't be intercepted:"
+begin
+  Aquarium::Raiser.new.raise_exception2
+rescue Aquarium::Exception2 => e
+  p "Rescued exception: #{e.class} with message: #{e}"
+end
+
+p "The raised Aquarium::Exception1 raised here will be intercepted and Aquarium::NewException will be raised:"
+begin
+  Aquarium::Raiser.new.raise_exception1
+rescue Aquarium::NewException => e
+  p "Rescued exception: #{e.class} with message: #{e}"
+end

data/examples/exception_wrapping_example_spec.rb

@@ -0,0 +1,49 @@
+require File.dirname(__FILE__) + '/../spec/aquarium/spec_helper'
+require 'aquarium'
+
+# Example demonstrating "wrapping" an exception; rescuing an exception and 
+# throwing a different one. A common use for this is to map exceptions across
+# "domain" boundaries, e.g., persistence and application logic domains. 
+# Note that you must use :around advice, since :after_raising cannot change
+# the control flow.
+# (However, see feature request #19119)
+
+module Aquarium
+  class Exception1 < Exception; end
+  class Exception2 < Exception; end
+  class NewException < Exception; end
+
+  class Raiser
+    def raise_exception1
+      raise Exception1.new("one")
+    end
+    def raise_exception2
+      raise Exception2.new("two")
+    end
+  end
+end
+
+describe "Rescuing one exception type and raising a second type" do
+  before :all do
+    @aspect = Aquarium::Aspects::Aspect.new :around, 
+      :calls_to => /^raise_exception/, :in_type => Aquarium::Raiser do |jp, obj, *args|
+      begin
+        jp.proceed
+      rescue Aquarium::Exception1 => e
+        raise Aquarium::NewException.new("New Exception: old exception message was: #{e.message}")
+      end
+    end
+    @raiser = Aquarium::Raiser.new
+  end
+  
+  after :all do
+    @aspect.unadvise
+  end
+  
+  it "should intercept the specified type of exception" do
+    lambda { @raiser.raise_exception1 }.should raise_error(Aquarium::NewException)
+  end
+  it "should not intercept other types of exceptions" do
+    lambda { @raiser.raise_exception2 }.should raise_error(Aquarium::Exception2)
+  end
+end

data/examples/reusable_aspect_hack_example.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# Example demonstrating a hack for defining a reusable aspect in a module
+# so that the aspect only gets created when the module is included by another
+# module or class.
+# Hacking like this defies the spirit of Aquarium's goal of being "intuitive",
+# so I created a feature request #19122 to address this problem.
+#
+# WARNING: put the "include ..." statement at the END of the class declaration,
+# as shown below. If you put the include statement at the beginning, as you
+# normally wouuld for including a module, it won't advice any join points, 
+# because no methods will have been defined at that point!!
+ 
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'aquarium'
+
+module Aquarium
+  module Reusables
+    module TraceMethods
+      def self.append_features mod
+        Aquarium::Aspects::Aspect.new :around, 
+            :type => mod, :methods => :all, :method_options => [:exclude_ancestor_methods] do |jp, object, *args|
+          p "Entering: "+jp.target_type.name+"#"+jp.method_name.to_s+": args = "+args.inspect
+          jp.proceed
+          p "Leaving:  "+jp.target_type.name+"#"+jp.method_name.to_s+": args = "+args.inspect
+        end
+      end
+    end    
+  end
+end
+
+class NotTraced1
+  def doit; p "NotTraced1#doit"; end
+end
+p "You will be warned that no join points in NotTraced2 were matched."
+p "This happens because the include statement and hence the aspect evaluation happen BEFORE any methods are defined!"
+class NotTraced2
+  include Aquarium::Reusables::TraceMethods
+  def doit; p "NotTraced2#doit"; end
+end
+class Traced1
+  def doit; p "Traced1#doit"; end
+  include Aquarium::Reusables::TraceMethods
+end
+class Traced2
+  def doit; p "Traced1#doit"; end
+  include Aquarium::Reusables::TraceMethods
+end
+
+p ""
+p "No method tracing:"
+NotTraced1.new.doit
+NotTraced1.new.doit
+p ""
+p "Method tracing:"
+Traced1.new.doit
+Traced2.new.doit