aquarium 0.1.0 → 0.1.5

data/CHANGES

@@ -1,3 +1,56 @@
+== Version 0.1.5
+
+Bug fixes:
+13514	Protected and private methods are made public when advised and left that way when unadvised
+13650	Loading Aquarium interferes with Rails filters
+13864	Bug with negative object_id
+
+Enhancements:
+13392	Convert examples to specs.
+13463	Support running in JRuby
+
+Fixing 13650 required an API change, which is why I've tagged this release "0.1.5" instead of
+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
+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 ;)
+
+In this release, aspect_dsl.rb is still implicitly included and it still defines the AspectDSL 
+module. Now, however, it does not include the AspectDSL module in Object. Instead, if you want this 
+behavior for all types, you must require the new lib/aquarium/aspects/dsl/object_dsl.rb explicitly. 
+
+As an alternative, if you just want the AspectDSL module included selectively in certain types, 
+then do the following:
+
+	class MyClass   # reopen "MyClass"
+		# Add the methods as _class_ methods
+		include Aquarium::Aspects::DSL::AspectDSL
+	end
+
+or, use (class|module)_eval:
+
+	require 'aquarium/aspects/dsl/aspect_dsl'
+
+	MyClass.class_eval do
+		# Add the methods as _class_ methods
+		include Aquarium::Aspects::DSL::AspectDSL
+	end
+
+To add the methods as _instance_ methods on individual objects:
+
+	object = MyClass.new
+	object.extend(Aquarium::Aspects::DSL::AspectDSL)
+
+
+Note: as discussed at http://practicalruby.blogspot.com/2007/02/reopen-with-moduleeval.html, 
+using "class_eval" or "module_eval" is safer that just reopening a class if 
+you're not sure that "MyClass" has actually been defined yet. However, in our particular case, it 
+probably doesn't matter, as AspectDSL doesn't change anything about the type, like aliasing existing 
+methods. Still, we can't guarantee that this won't change in the future.
+
 == Version 0.1.0
 
 This is the initial version.

data/README

@@ -53,7 +53,7 @@ Many of AspectJ's behaviors that aren't currently supported are planned for futu
 
 Several complete examples are provided in the "examples" directory.
 
-In most cases, you can either declare the appropriate classes or use the optional DSL, which adds methods to Object.
+In most cases, you can either declare the appropriate classes or use the optional DSL, which adds methods to classes, objects, or even Object itself.
 
 Here is an example that traces invocations of all public instance methods of the classes or modules Foo and Bar.
 
@@ -64,9 +64,9 @@ Here is an example that traces invocations of all public instance methods of the
 		p "Leaving: #{execution_point.type.name}##{execution_point.method_name}"
 	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, etc.) Here is the same example using the convenience DSL that adds aspectual behavior to 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, 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!).
 
-	require 'aquarium'
+	require 'aquarium/aspects/dsl/object_dsl'
 	around :types => [Foo, Bar], :methods => :all do |execution_point, *args|
 		p "Entering: #{execution_point.type.name}##{execution_point.method_name}"
 		execution_point.proceed
@@ -75,9 +75,25 @@ The advice to execute at each join point is the block. The pointcut is the set o
 
 See "examples/method_tracing_example.rb" for a more detailed version of this example.
 
+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'
+	...
+	module MyModule
+		include Aquarium::Aspects::DSL::AspectDSL
+	end
+
+	class MyClass
+		include Aquarium::Aspects::DSL::AspectDSL
+	end
+
+	my_object = MyOtherClass.new
+	my_object.extend (Aquarium::Aspects::DSL::AspectDSL)
+
 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
 		...
 		def critical_operation *args
 			...
@@ -92,7 +108,7 @@ If you use the DSL inside a class and omit the :type(s) and :object(s) options,
 		end
 	end
 
-Here are some more succinct examples, illustrating the API.
+Here are some more succinct examples, illustrating the API (using the DSL methods).
 
 You can pass in pointcuts defined elsewhere:
 

data/Rakefile

@@ -31,7 +31,7 @@ task :default => [:verify_rcov]
 
 desc "Run all specs"
 Spec::Rake::SpecTask.new do |t|
-  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_files = FileList['spec/**/*_spec.rb', 'examples/**/*_spec.rb']
   t.spec_opts = ['--options', 'spec.opts']
   t.rcov = true
   t.rcov_dir = '../doc/output/coverage'
@@ -40,7 +40,7 @@ end
 
 desc "Run all specs and store html output in doc/output/report.html"
 Spec::Rake::SpecTask.new('spec_html') do |t|
-  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_files = FileList['spec/**/*_spec.rb', 'examples/**/*_spec.rb']
   t.spec_opts = ['--format html:../doc/output/report.html','--backtrace']
 end
 
@@ -168,8 +168,10 @@ end
 desc "Upload Website to RubyForge"
 task :publish_website => [:verify_user, :website] do
   unless Aquarium::VERSION::RELEASE_CANDIDATE
+    # host = "aquarium-website@rubyforge.org"
+    host = "#{ENV['RUBYFORGE_USER']}@rubyforge.org"
     publisher = Rake::SshDirPublisher.new(
-      "aquarium-website@rubyforge.org",
+      "#{host}",
       "/var/www/gforge-projects/#{PKG_NAME}",
       "../doc/output"
     )
@@ -179,6 +181,18 @@ task :publish_website => [:verify_user, :website] do
   end
 end
 
+desc "Upload Website archive to RubyForge"
+task :archive_website => [:verify_user, :website] do
+  # host = "aquarium-website@rubyforge.org"
+  host = "#{ENV['RUBYFORGE_USER']}@rubyforge.org"
+  publisher = Rake::SshDirPublisher.new(
+    "#{host}",
+    "/var/www/gforge-projects/#{PKG_NAME}/#{Spec::VERSION::TAG}",
+    "../doc/output"
+  )
+  publisher.upload
+end
+
 desc "Publish gem+tgz+zip on RubyForge. You must make sure lib/version.rb is aligned with the CHANGELOG file"
 task :publish_packages => [:verify_user, :package] do
   release_files = FileList[
@@ -200,7 +214,8 @@ task :publish_packages => [:verify_user, :package] do
     puts "SINCE THIS IS A PRERELEASE, FILES ARE UPLOADED WITH SSH, NOT TO THE RUBYFORGE FILE SECTION"
     puts "YOU MUST TYPE THE PASSWORD #{release_files.length} TIMES..."
 
-    host = "aquarium-website@rubyforge.org"
+    # host = "aquarium-website@rubyforge.org"
+    host = "#{ENV['RUBYFORGE_USER']}@rubyforge.org"
     remote_dir = "/var/www/gforge-projects/#{PKG_NAME}"
 
     publisher = Rake::SshFilePublisher.new(

data/UPGRADE

@@ -1,3 +1,43 @@
-= Upgrading existing code to Aquarium-0.1.0
+== Upgrading existing code 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 
+their names overlap with methods added by Rails. 
+
+Now, if you want these methods added to Object, you must require the new 
+lib/aquarium/aspects/dsl/object_dsl.rb explicitly. 
+
+As an alternative, if you just want these methods added selectively in certain types, then do the 
+following:
+
+<ruby>
+require 'aquarium/aspects/dsl/aspect_dsl'
+
+class MyClass   # reopen "MyClass"
+	# Add the methods as _class_ methods
+	include Aquarium::Aspects::DSL::AspectDSL
+end
+</ruby>
+
+or, use (class|module)_eval:
+<ruby>
+require 'aquarium/aspects/dsl/aspect_dsl'
+
+MyClass.class_eval do
+	# Add the methods as _class_ methods
+	include Aquarium::Aspects::DSL::AspectDSL
+end
+</ruby>
+
+To add the methods as _instance_ methods on individual objects:
+
+<ruby>
+object = MyClass.new
+object.extend(Aquarium::Aspects::DSL::AspectDSL)
+</ruby>
+
+See the CHANGES for more details.
+
+== Upgrading existing code to Aquarium-0.1.0
 
 This is the first release of Aquarium.

data/examples/aspect_design_example.rb

@@ -12,6 +12,7 @@ require 'aquarium'
 
 module Aquarium
   class ClassWithStateAndBehavior
+    include Aquarium::Aspects::DSL::AspectDSL
     def initialize *args
       @state = args
       p "Initializing: #{args.inspect}"
@@ -24,9 +25,11 @@ module Aquarium
   end
 end
 
+include Aquarium::Aspects
+
 # Observe state changes in the class, using the class-defined pointcut.
 
-observer = after :pointcut => Aquarium::ClassWithStateAndBehavior::STATE_CHANGE do |jp, *args|
+observer = Aspect.new :after, :pointcut => Aquarium::ClassWithStateAndBehavior::STATE_CHANGE do |jp, *args|
   p "State has changed. "
   p "  New state is #{jp.context.advised_object.state.inspect}"
   p "  Equivalent to *args: #{args.inspect}"

data/examples/aspect_design_example_spec.rb

@@ -0,0 +1,41 @@
+require File.dirname(__FILE__) + '/../spec/aquarium/spec_helper.rb'
+require 'aquarium'
+
+# Example demonstrating emerging ideas about good aspect-oriented design. Specifically, this 
+# example follows ideas of Jonathan Aldrich on "Open Modules", where a "module" (in the generic
+# sense of the word...) is responsible for defining and maintaining the pointcuts that it is 
+# willing to expose to potential aspects. Aspects are only allowed to advise the module through
+# the pointcut. (Enforcing this constraint is TBD)
+# Griswold, Sullivan, and collaborators have expanded on these ideas. See their IEEE Software,
+# March 2006 paper.
+
+module Aquarium
+  class ClassWithStateAndBehavior
+    include Aquarium::Aspects::DSL::AspectDSL
+    def initialize *args
+      @state = args
+    end
+    attr_accessor :state
+
+    # A simpler version of the following would be 
+    # STATE_CHANGE = pointcut :method => :state
+    STATE_CHANGE = pointcut :attribute => :state, :attribute_options => :writer
+  end
+end
+
+include Aquarium::Aspects
+
+describe "An example of an aspect using a 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, *args|
+      @new_state = jp.context.advised_object.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
+

data/examples/design_by_contract_example.rb

@@ -3,9 +3,8 @@
 # specifying the contract of use for a class or module and testing it at runtime (usually
 # during the testing process)
 # This example is adapted from spec/extras/design_by_contract_spec.rb.
-# Note: the DesignByContract module uses the AspectDSL module. The #precondition, #postcondition,
-# and #invariant methods shown below delegate to AspectDSL methods. Those methods implicitly use
-# "self" as the :object to advise. 
+# Note: the DesignByContract module adds the #precondition, #postcondition, and #invariant
+# methods shown below to Object and they use "self" as the :object to advise.  
  
 $LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
 require 'aquarium/extras/design_by_contract'

data/examples/design_by_contract_example_spec.rb

@@ -0,0 +1,92 @@
+require File.dirname(__FILE__) + '/../spec/aquarium/spec_helper.rb'
+require 'aquarium'
+require 'aquarium/extras/design_by_contract'
+
+# Example demonstrating "Design by Contract", Bertrand Meyer's idea for programmatically-
+# specifying the contract of use for a class or module and testing it at runtime (usually
+# during the testing process)
+# This example is adapted from spec/extras/design_by_contract_spec.rb.
+# Note: the DesignByContract module adds the #precondition, #postcondition, and #invariant
+# methods shown below to Object and they use "self" as the :object to advise.  
+
+module Aquarium
+  class PreCondExample
+    def action *args
+      @state = *args
+    end
+    attr_reader :state
+
+    precondition :method => :action, :message => "Must pass more than one argument." do |jp, *args|
+      args.size > 0
+    end
+  end
+end
+  
+describe "An example using a precondition" do
+  it "should fail at the call entry point if the precondition is not satisfied." do
+    lambda { Aquarium::PreCondExample.new.action }.should raise_error(Aquarium::Extras::DesignByContract::ContractError)
+  end
+end
+
+describe "An example using a precondition" do
+  it "should not fail at the call entry point if the precondition is satisfied." do
+    Aquarium::PreCondExample.new.action :a1
+  end
+end
+
+module Aquarium
+  class PostCondExample
+    def action *args
+      @state = *args
+    end
+    attr_reader :state
+
+    postcondition :method => :action, 
+      :message => "Must pass more than one argument and first argument must be non-empty." do |jp, *args|
+      args.size > 0 && ! args[0].empty?
+    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)
+  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
+  end
+end
+
+module Aquarium
+  class InvarCondExample
+    def initialize 
+      @invar = 0
+    end
+    attr_reader :invar
+    def good_action
+    end
+    def bad_action
+      @invar = 1
+    end
+
+    invariant :methods => /action$/, :message => "Must not change the @invar value." do |jp, *args|
+      jp.context.advised_object.invar == 0
+    end
+  end
+end
+
+describe "An example using an invariant" do
+  it "should fail at the call entry or exit point if the invariant is not satisfied." do
+    lambda { Aquarium::InvarCondExample.new.bad_action }.should    raise_error(Aquarium::Extras::DesignByContract::ContractError)
+  end
+end
+
+describe "An example using an invariant" do
+  it "should pass at the call entry and exit point if the invariant is satisfied." do
+    Aquarium::InvarCondExample.new.good_action
+  end
+end

data/examples/method_missing_example.rb

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

data/examples/method_missing_example_spec.rb

@@ -0,0 +1,59 @@
+require File.dirname(__FILE__) + '/../spec/aquarium/spec_helper.rb'
+require 'aquarium'
+
+# Example demonstrating "around" advice for method_missing. This is a technique for
+# avoiding collisions when different toolkits want to override method_missing in the
+# same classes, e.g., Object. Using around advice as shown allows a toolkit to add 
+# custom behavior while invoking the "native" method_missing to handle unrecognized
+# method calls.
+# Note that it is essential to use around advice, not before or after advice, because
+# neither can prevent the call to the "wrapped" method_missing, which is presumably
+# not what you want.
+# In this (contrived) example, an Echo class uses method_missing to simply echo
+# the method name and arguments. An aspect is used to intercept any calls to a 
+# fictitious "log" method and handle those in a different way.
+
+module Aquarium
+  class Echo
+    def method_missing sym, *args
+      @log ||= []
+      @log << "Echoing: #{sym.to_s}: #{args.join(" ")}"
+    end
+    def logged_messages; @log; end
+  end
+end
+
+describe "An example of a class' method_missing without around advice" do
+  it "should handle all invocations of method_missing." do
+    echo = Aquarium::Echo.new
+    echo.say "hello", "world!"
+    echo.log "something", "interesting..."
+    echo.shout "theater", "in", "a", "crowded", "firehouse!"
+    echo.logged_messages.size.should == 3
+    echo.logged_messages[0].should == "Echoing: say: hello world!"
+    echo.logged_messages[1].should == "Echoing: log: something interesting..."
+    echo.logged_messages[2].should == "Echoing: shout: theater in a crowded firehouse!"
+  end
+end
+
+describe "An example of a class' method_missing with around advice" do
+  it "should only handle invocations not processed by the around advice." do
+    @intercepted_message = nil
+    aspect = Aquarium::Aspects::Aspect.new :around, :type => Aquarium::Echo, :method => :method_missing do |join_point, sym, *args|
+      if sym == :log 
+        @intercepted_message = "log: #{args.join(" ")}" 
+      else
+        join_point.proceed
+      end
+    end
+    echo = Aquarium::Echo.new
+    echo.say "hello", "world!"
+    echo.log "something", "interesting..."
+    echo.shout "theater", "in", "a", "crowded", "firehouse!"
+    echo.logged_messages.size.should == 2
+    echo.logged_messages[0].should == "Echoing: say: hello world!"
+    echo.logged_messages[1].should == "Echoing: shout: theater in a crowded firehouse!"
+    @intercepted_message.should == "log: something interesting..."
+    aspect.unadvise
+  end
+end