module 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.

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.

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)

Example demonstrating how to use the TypeFinder class to conveniently “introduce” new methods and attributes in a set of types, like you might do with AspectJ in Java. Of course, in Ruby, you can simply use Object#extend(module). However, if you want to do this in a cross-cutting way, TypeFinder. is convenient.

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.

Example demonstrating “around” advice that traces calls to all methods in classes Foo and Bar

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!!

Adding useful methods to Regexp.

Find methods and types and objects.

Finds pointcuts by name, either class variables, class constants or both.

Finds types known to the runtime environment.