aquarium 0.5.1 → 0.7.1

data/UPGRADE

@@ -1,29 +1,39 @@
+== Updating to Aquarium-0.7.1
+
+Version 0.7.1 supports only Ruby 2.6. It was tested with 2.6.3p62 (2019-04-16 revision 67580). Basic JRuby 9.2.7.0 (2.5.3) 2019-04-09 8a269e3 support is provided, but using JRuby currently does *not* pass all the custom Java specs in the `jruby/spec` directory, which specifically test working with Java classes. However, JRuby does pass all the Ruby specs in the `spec` directory. This is a long-standing issue with JRuby support in Aquarium. Patches are welcome!
+
+> TODO: There are currently a _lot_ of deprecation warnings.
+
+== Updating to Aquarium-0.6.X
+
+Version 0.6.0 supports only Ruby 2.0.0p247. Basic JRuby 1.7.4 (1.9.3p392) support is provided, but using JRuby currently does *not* pass all the custom Java specs in the `jruby/spec` directory, which specifically test working with Java classes. However, JRuby does pass all the Ruby specs in the `spec` directory. I didn't want to release v0.6.0 with the Java-specific specs not working, but I didn't have time to resolve the issues. Patches are welcome.
+
 == Updating to Aquarium-0.5.X
 
-This release introduces a few small API changes that are described in 
-CHANGES. The primary goal of the release is to add full support for 
+This release introduces a few small API changes that are described in
+CHANGES. The primary goal of the release is to add full support for
 Ruby 1.9.3 and JRuby 1.6.7.
 
-It was not tested on early versions of Ruby 1.9 and JRuby 1.X, so users 
-of earlier releases should use caution upgrading. Post any issues to the 
+It was not tested on early versions of Ruby 1.9 and JRuby 1.X, so users
+of earlier releases should use caution upgrading. Post any issues to the
 GitHub project.
 
 == Updating to Aquarium-0.4.X
 
-This release is fully backwards-compatible with previous releases. It 
-expands the API slightly and adds internal improvements to better support 
-JRuby. There should be no upgrade issues. 
+This release is fully backwards-compatible with previous releases. It
+expands the API slightly and adds internal improvements to better support
+JRuby. There should be no upgrade issues.
 
 == 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. 
+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 
+There are no known upgrade issues with this release. Although many new synonyms
 were added for API method parameters, all changes are backwards compatible.
 
 == Updating to Aquarium-0.2.0
@@ -31,46 +41,46 @@ were added for API method parameters, all changes are backwards compatible.
 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 corresponding to 
-the advised join point.  Therefore, when you upgrade, you will need to modify 
-your advices to take this extra argument, even if you don't use it. Since an 
-advice of |jp, *args| would silently "absorb" the object into the beginning of 
-"*args", thereby potentially causing confusion, Aquarium will raise an exception 
-if the advice block or proc has this obsolete signature. 
-
-Note that "JoinPoint#Context.advised_object" is still supported, even if it is 
+  |join_point, object, *method_args|
+where "object" is the current object receiving the message corresponding to
+the advised join point.  Therefore, when you upgrade, you will need to modify
+your advices to take this extra argument, even if you don't use it. Since an
+advice of |jp, *args| would silently "absorb" the object into the beginning of
+"*args", thereby potentially causing confusion, Aquarium will raise an exception
+if the advice block or proc has this obsolete signature.
+
+Note that "JoinPoint#Context.advised_object" is still supported, even if it is
 now less useful.
 
 == 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 
+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.
 
 == Updating to Aquarium-0.1.7
 
-This is primarily a bug-fix release, so there should be no upgrading or 
+This is primarily a bug-fix release, so there should be no upgrading or
 incompatibility issues.
 
 == 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. 
+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.
 
 == 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 their names overlap with methods 
-added by Rails. 
+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. 
+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 
+As an alternative, if you just want these methods added selectively in certain
 types, then do the following:
 
   require 'aquarium/dsl/aspect_dsl'

data/aquarium.gemspec

@@ -0,0 +1,50 @@
+# -*- encoding: utf-8 -*-
+# This GemSpec adapted from http://rakeroutes.com/blog/lets-write-a-gem-part-one/
+
+# -- this is magic line that ensures "../lib" is in the load path -------------
+$:.push File.expand_path("../lib", __FILE__)
+require 'aquarium/version'
+
+Gem::Specification.new do |s|
+  s.name = "aquarium"
+  s.version = Aquarium::VERSION::STRING
+  s.summary = Aquarium::VERSION::DESCRIPTION
+  s.authors = ["Dean Wampler and other contributors"]
+  s.email = "deanwampler@gmail.com"
+  s.homepage = "https://deanwampler.github.io/open-source/aquarium/index.html"
+  s.rubyforge_project = "aquarium"
+  s.description = <<-EOF
+    Aquarium is a full-featured Aspect-Oriented Programming (AOP) framework for Ruby that is
+    designed to provide an intuitive syntax and support for large-scale, dynamic aspects.
+  EOF
+
+  # Use all files managed with Git.
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  s.bindir = 'bin'
+
+  # Where any executable files included with the gem live.
+  # These go in bin by convention. In our case, we have none.
+  # s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.executables = []
+  s.require_paths = ["lib"]
+
+  # Specify dependencies. Some of these are for building the documentation.
+  s.add_development_dependency('bundler', '>= 2.0.1')
+  s.add_development_dependency('coderay', '>= 1.1.2')
+  s.add_development_dependency('meta_project', '>= 0.4.15')
+  s.add_development_dependency('rake', '>= 12.3.2')
+  s.add_development_dependency('rdoc', '>= 6.1.1')
+  s.add_development_dependency('RedCloth', '>= 4.3.2')
+  s.add_development_dependency("rspec", '>= 2.14.1')
+  s.add_development_dependency("rspec-core", '>= 3.8.0')
+  s.add_development_dependency("rspec-expectations", '>= 3.8.3')
+  s.add_development_dependency('webgen', '>= 1.5.2')
+
+  # s.has_rdoc = true
+  # s.rdoc_options = rd.options
+  # s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$|^EXAMPLES.rd$/ }.to_a
+
+  s.autorequire = 'aquarium'
+end

data/examples/README.txt

@@ -0,0 +1,6 @@
+Aquarium Examples README
+
+There are several examples here and four corresponding versions that are RSpec examples (so they are testable!). 
+
+I keep the non-RSpec versions primarily for the documentation pages, but it's a bit risky keeping them as they could break in the future, so buyer beware!
+

data/examples/aspect_design_example_spec.rb

@@ -40,7 +40,7 @@ describe "An example of an aspect referencing a particular class-defined pointcu
     observer = Aspect.new :after, 
       :pointcut => Aquarium::ClassWithStateAndBehavior::STATE_CHANGE do |jp, obj, *args|
       @new_state = obj.state
-      @new_state.should be_eql(*args)
+      expect(@new_state).to eq(*args)
     end
     object = Aquarium::ClassWithStateAndBehavior.new(:a1, :a2, :a3)
     object.state = [:b1, :b2]
@@ -54,7 +54,7 @@ describe "An example of an aspect searching for class-defined pointcuts." do
     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)
+      expect(@new_state).to eq(*args)
     end
     object = Aquarium::ClassWithStateAndBehavior.new(:a1, :a2, :a3)
     object.state = [:b1, :b2]

data/examples/design_by_contract_example_spec.rb

@@ -24,7 +24,7 @@ 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)
+    expect { Aquarium::PreCondExample.new.action }.to raise_error(Aquarium::Extras::DesignByContract::ContractError)
   end
 end
 
@@ -49,7 +49,7 @@ 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)
+    expect { Aquarium::PostCondExample.new.action }.to raise_error(Aquarium::Extras::DesignByContract::ContractError)
   end
 end
 
@@ -79,7 +79,7 @@ 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)
+    expect { Aquarium::InvarCondExample.new.bad_action }.to raise_error(Aquarium::Extras::DesignByContract::ContractError)
   end
 end
 

data/examples/exception_wrapping_example_spec.rb

@@ -41,9 +41,9 @@ describe "Rescuing one exception type and raising a second type" do
   end
   
   it "should intercept the specified type of exception" do
-    lambda { @raiser.raise_exception1 }.should raise_error(Aquarium::NewException)
+    expect { @raiser.raise_exception1 }.to raise_error(Aquarium::NewException)
   end
   it "should not intercept other types of exceptions" do
-    lambda { @raiser.raise_exception2 }.should raise_error(Aquarium::Exception2)
+    expect { @raiser.raise_exception2 }.to raise_error(Aquarium::Exception2)
   end
 end

data/examples/introductions_example_spec.rb

@@ -30,7 +30,7 @@ describe "Using TypeFinder to introduce modules in a set of other types" do
      Aquarium::TypeFinderIntroductionExampleTargetModule2,
      Aquarium::TypeFinderIntroductionExampleTargetClass1,
      Aquarium::TypeFinderIntroductionExampleTargetClass2].each do |t|
-       t.methods.should include('introduced_method')
+       expect(t.methods).to include(:introduced_method)
     end
   end
 end

data/examples/method_tracing_example_spec.rb

@@ -69,10 +69,11 @@ describe "An example with advice on the public instance methods (excluding ances
     foo = Aquarium::Foo.new :a5, :a6
     foo.do_it :b5, :b6
     foo.logged_messages.size.should == 4
-    foo.logged_messages[0].should include("Inside: Aquarium::Foo#initialize")
-    foo.logged_messages[1].should include("Entering")
-    foo.logged_messages[2].should include("Inside: Aquarium::Foo#do_it")
-    foo.logged_messages[3].should include("Leaving")
+    
+    expect(foo.logged_messages[0]).to include("Inside: Aquarium::Foo#initialize")
+    expect(foo.logged_messages[1]).to include("Entering")
+    expect(foo.logged_messages[2]).to include("Inside: Aquarium::Foo#do_it")
+    expect(foo.logged_messages[3]).to include("Leaving")
     aspect.unadvise    
   end
 end
@@ -114,10 +115,10 @@ describe "An example with advice on the public instance methods (including ances
     bar = Aquarium::Bar.new :a9, :a10
     bar.do_something_else :b9, :b10
     bar.logged_messages.size.should == 4
-    bar.logged_messages[0].should include("Inside: Aquarium::BarModule#initialize")
-    bar.logged_messages[1].should include("Entering: Aquarium::Bar#do_something_else")
-    bar.logged_messages[2].should include("Inside: Aquarium::BarModule#do_something_else")
-    bar.logged_messages[3].should include("Leaving: Aquarium::Bar#do_something_else")
+    expect(bar.logged_messages[0]).to include("Inside: Aquarium::BarModule#initialize")
+    expect(bar.logged_messages[1]).to include("Entering: Aquarium::Bar#do_something_else")
+    expect(bar.logged_messages[2]).to include("Inside: Aquarium::BarModule#do_something_else")
+    expect(bar.logged_messages[3]).to include("Leaving: Aquarium::Bar#do_something_else")
     aspect.unadvise    
   end
 end
@@ -139,18 +140,18 @@ describe "An example with advice on the private initialize method of Foo and Bar
     foo = Aquarium::Foo.new :a11, :a12
     foo.do_it :b11, :b12
     foo.logged_messages.size.should == 4
-    foo.logged_messages[0].should include("Entering: Aquarium::Foo#initialize")
-    foo.logged_messages[1].should include("Inside: Aquarium::Foo#initialize")
-    foo.logged_messages[2].should include("Leaving: Aquarium::Foo#initialize")
-    foo.logged_messages[3].should include("Inside: Aquarium::Foo#do_it")
+    expect(foo.logged_messages[0]).to include("Entering: Aquarium::Foo#initialize")
+    expect(foo.logged_messages[1]).to include("Inside: Aquarium::Foo#initialize")
+    expect(foo.logged_messages[2]).to include("Leaving: Aquarium::Foo#initialize")
+    expect(foo.logged_messages[3]).to include("Inside: Aquarium::Foo#do_it")
 
     bar = Aquarium::Bar.new :a13, :a14
     bar.do_something_else :b13, :b14
     bar.logged_messages.size.should == 4
-    bar.logged_messages[0].should include("Entering: Aquarium::Bar#initialize")
-    bar.logged_messages[1].should include("Inside: Aquarium::BarModule#initialize")
-    bar.logged_messages[2].should include("Leaving: Aquarium::Bar#initialize")
-    bar.logged_messages[3].should include("Inside: Aquarium::BarModule#do_something_else")
+    expect(bar.logged_messages[0]).to include("Entering: Aquarium::Bar#initialize")
+    expect(bar.logged_messages[1]).to include("Inside: Aquarium::BarModule#initialize")
+    expect(bar.logged_messages[2]).to include("Leaving: Aquarium::Bar#initialize")
+    expect(bar.logged_messages[3]).to include("Inside: Aquarium::BarModule#do_something_else")
     aspect.unadvise    
     after_methods = Aquarium::Foo.private_instance_methods.sort #- Object.private_methods.sort
     (before_methods - after_methods).should == []

data/examples/reusable_aspect_hack_example_spec.rb

@@ -55,26 +55,26 @@ describe "Reusable aspect defined in a module can be evaluated at 'include' time
   
   it "should not advise types that don't include the module with the aspect" do
     NotTraced1.new.doit
-    Aquarium::Reusables::TraceMethods.advice_invoked?.should be_false
+    Aquarium::Reusables::TraceMethods.advice_invoked?.should be_falsey
   end
   
   it "should not advise any methods if the module with the aspect is included before any methods are defined!" do
     NotTraced2.new.doit
-    Aquarium::Reusables::TraceMethods.advice_invoked?.should be_false
+    Aquarium::Reusables::TraceMethods.advice_invoked?.should be_falsey
   end
   
   it "should advise methods if the module with the aspect is included after the methods are defined" do
     Traced1.new.doit
-    Aquarium::Reusables::TraceMethods.advice_invoked?.should be_true
+    Aquarium::Reusables::TraceMethods.advice_invoked?.should be_truthy
   end
 
   it "should advise methods after the module with the aspect is included" do
     Traced2.new.doit
-    Aquarium::Reusables::TraceMethods.advice_invoked?.should be_false
+    Aquarium::Reusables::TraceMethods.advice_invoked?.should be_falsey
     class Traced2
       include Aquarium::Reusables::TraceMethods
     end
     Traced2.new.doit
-    Aquarium::Reusables::TraceMethods.advice_invoked?.should be_true
+    Aquarium::Reusables::TraceMethods.advice_invoked?.should be_truthy
   end
 end

data/jruby/Rakefile

@@ -0,0 +1,61 @@
+# Rakefile for the separate testing of JRuby support
+# (Separate because we need to run JRuby, not MRI...)
+
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+
+# Use RSpec's files.
+require 'rspec/core/rake_task'
+
+task :default => [:jruby]
+
+task :jruby => [:aquarium_spec, :jruby_spec] 
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new do |t|
+  # t.spec_files = FileList['spec/**/*_spec.rb', 'examples/**/*_spec.rb']
+  t.rspec_opts = ['--colour'] + FileList['spec/**/*_spec.rb', 'examples/**/*_spec.rb']
+end
+task :spec => :verify_jruby
+
+desc "Run all specs in reverse"
+RSpec::Core::RakeTask.new(:spec_in_reverse) do |t|
+  #t.spec_files = FileList['spec/**/*_spec.rb', 'examples/**/*_spec.rb']
+  t.rspec_opts = ['--reverse', '--colour'] + FileList['spec/**/*_spec.rb', 'examples/**/*_spec.rb']
+end
+task :spec => :verify_jruby
+
+desc "Run all of aquarium's specs using JRuby"
+task :aquarium_spec => :verify_jruby do
+  output = nil
+  Dir.chdir '..' do
+    sh "rake spec"
+  end
+end
+
+task :verify_jruby do
+  unless self.class.const_defined? "JRUBY_VERSION"
+    raise "ERROR: You must run these rake tasks with jruby."
+  else
+    #raise "WARNING: JRuby support is not provided in this release. See ../CHANGES for details."
+  end
+end
+
+CLEAN.include('java/example.jar')
+CLEAN.include('java/**/*.class')
+SRC = FileList['java/**/*.java']
+OBJ = SRC.ext('class')
+
+rule '.class' => '.java' do |t|
+  sh "javac -cp java #{t.source}"
+end
+
+file 'java/example.jar' => OBJ do
+  classes = OBJ.map {|c| c.gsub(/^java\//, '')}
+  Dir.chdir 'java' do
+    sh "jar -cf example.jar #{classes}"
+  end
+end
+
+task :jruby_spec => ['java/example.jar', :spec, :spec_in_reverse]

data/jruby/java/example/Worker.java

@@ -0,0 +1,9 @@
+package example;
+
+/**
+ * An ad-hoc interface that demonstrates advising Java classes with Aquarium.
+ * See the specs that use this interface for examples of what you can and can't do with them!
+ */
+public interface Worker<Input, Output> {
+	Output doWork(Input input);
+}

data/jruby/java/example/sorter/StringListSorter.java

@@ -0,0 +1,22 @@
+package example.sorter;
+
+import example.*;
+import java.util.*;
+
+/**
+ * An ad-hoc class that demonstrates advising Java classes with Aquarium.
+ * See the specs that use this class for examples of what you can and can't do with them!
+ */
+public class StringListSorter implements Worker<List<String>, List<String>> {
+	protected Comparator<String> comparator;
+	
+	public StringListSorter(Comparator<String> comparator) {
+		this.comparator = comparator;
+	}
+	
+	public List<String> doWork(List<String> input) {
+		List<String> newList = new ArrayList<String>(input);
+		Collections.sort(newList, comparator);
+		return newList;
+	}
+}

data/jruby/java/example/sorter/converter/StringListCaseConverterAndSorter.java

@@ -0,0 +1,42 @@
+package example.sorter.converter;
+
+import example.sorter.*;
+import java.util.*;
+
+/**
+ * A really ad-hoc, strange class that demonstrates advising Java classes with Aquarium.
+ * Disclaimer:
+ * Normally, the "and" in the class name would be a sign of a bad design and it's usually
+ * a bad idea to extend concreate classes and override concrete methods! So, don't take this
+ * class as an example of good Java design, please! ;)
+ */
+public class StringListCaseConverterAndSorter extends StringListSorter {
+	private boolean convertToLowerCase = true;
+
+	public StringListCaseConverterAndSorter(boolean convertToLowerCase, Comparator<String> comparator) {
+		super(comparator);
+		this.convertToLowerCase = convertToLowerCase;
+	}
+	
+	public StringListCaseConverterAndSorter(Comparator<String> comparator) {
+		super(comparator);
+	}
+	
+	public List<String> doWork(List<String> input) {
+		List<String> newList = convertCase(input);
+/*		return super.doWork(newList); */
+		Collections.sort(newList, comparator);
+		return newList;
+	}
+	
+	public List<String> convertCase(List<String> input) {
+		List<String> newList = new ArrayList<String>(input.size());
+		for (String s: input) {
+			if (convertToLowerCase)
+				newList.add(s.toLowerCase());
+			else
+				newList.add(s.toUpperCase());
+		}
+		return newList;
+	}
+}