Aquarium uses Ruby’s metaprogramming API extensively and the JRuby team has done some pretty sophisticated work to integrate Java types with Ruby. Hence, it’s not too surprising there are some gotchas. Hopefully, workarounds will be possible for all of them.

The details are discussed on the JRuby page, the README on the Aquarium site, and of course the “specs” in the distribution’s jruby/spec directory. I’ll summarize them here, after discussing the pros and cons of Aquarium vs. the venerable AspectJ and showing you an example of using Aquarium for Java.

Briefly, Aquarium’s advantages over AspectJ are these:

1. You can add and remove advice dynamically at runtime. You can’t remove AspectJ advice.
2. You can advise JDK types easily with Aquarium. AspectJ won’t do this by default, but this is really more of a legacy licensing issue than a real technical limitation.
3. You can advise individual objects, not just types.

Aquarium’s disadvantages compared to AspectJ include:

1. Aquarium will be slower than using AspectJ (although this has not been studied in depth yet).
2. Aquarium’s pointcut language is not as full-featured as AspectJ’s.
3. There are the bugs and limitations I mentioned above in this initial V0.4.0 release, which I’ll elaborate shortly.

Here is an example of adding tracing calls to a method doIt in all classes that implement the Java interface com.foo.Work.

Aspect.new :before, :calls_to => [:doIt, :do_it], :in_types_and_descendents => Java::com.foo.Work do |jp, obj, *args|
  log "Entering: #{jp.target_type.name}##{jp.method_name}: object = #{object}, args = #{args.inspect}" 
end

There are two important points to notice in this example:

1. You can choose to refer to the method as do_it (Ruby style) or doIt, but these variants are effectively treated as separate methods; advice on one will not affect invocations of the other. So, if you want to be sure to catch all invocations, use both forms. There is a bug (18326) that happens in certain conditions if you use just the Java naming convention.
2. If the type is an interface, you must use :types_and_descendents (or one of the supported variants on the word types...). Since interfaces don’t have method implementations, you will match no join points unless you use the _and_descendents clause. (By default, Aquarium warns you when no join points are matched by an aspect.) However, there is a bug (18325) with this approach if Java types are subtyped in Ruby.

Limitations and Bugs

Okay, here’s the “fine print”...

In this (V0.4.0) release, there are some important limitations.

1. Aquarium advice on a method in a Java type will only be invoked when the method is called directly from Ruby.
2. To have the advice invoked when the method is called from either Java or Ruby, it is necessary to create a Ruby subclass of the Java type and override the method(s) you want to advise. These overrides can just call super. Note that it will also be necessary for instances of this Ruby type to be used throughout the application, in both the Java and Ruby code. So, you’ll have to instantiate the object in your Ruby code.

Yea, this isn’t so great, but if you’re motivated… ;)

There are also a few outstanding Aquarium bugs (which could actually be JRuby bugs or quirks of the Aquarium-JRuby “interaction”; I’m not yet sure which).

1. Bug #18325: If you have Ruby subclasses of Java types and you advise a Java method in the hierarchy using :types_and_descendents => MyJavaBaseClassOrInterface and you call unadvise on the aspect, the advice “infrastructure” is not correctly removed from the Ruby types. Workaround: Either don’t “unadvise” such Ruby types or only advise methods in such Ruby types where the method is explicitly overridden in the Ruby class. (The spec and the Rubyforge bug report provide examples.)
2. Bug #18326: Normally, you can use either Java- or Ruby-style method names (e.g., doSomething vs. do_something), for Java types. However, if you write an aspect using the Java-style for a method name and a Ruby subclass of the Java type where the method is actually defined (i.e., the Ruby class doesn’t override the method), Aquarium acts like the JoinPoint is advised, but the advice is never actually called. Workaround: Use the Ruby-style name in this scenario.

So, there is still some work to do, but it’s promising that you can use an aspect framework in one language with another. A primary goal of Aquarium is to make it easy to write simple aspects. My hope is that people who might find AspectJ daunting will still give Aquarium a try.