Klank Boom Klang

Part II of this series on Ruby class methods is a look at annotations in Ruby.

The term annotation here refers to a Ruby technique that belongs to the same family as Java annotations, C# attributes, and C compiler directives. These language features are of course not identical, and the class method derived Ruby version is its own beast altogether. Nevertheless, there are family resemblances. Ruby class methods can be used to issue what might be called interpreter directives. They can also be used to allow for an Aspect Oriented Programming (AOP) like abstraction of cross cutting concerns.

Take for an example a valuable but long running test that should only be run as part of an acceptance build. In the (hopefully) rare case when the tests fails in the build environment, the developers responsible for the failed check-in can run the test locally to resolve the issue, but as a general rule developers don’t want to take the performance hit as part of their local test suite execution.

require 'test/unit' class CalculatorTest<Test::Unit::TestCase def test_some_complex_calculation assert_equal 2, Calculator.new(4).complex_calculation end end

A simple interpreter directive might be implemented as…

class CalculatorTest<Test::Unit::TestCase if ENV["BUILD"] == "ACCEPTANCE" def test_some_complex_calculation assert_equal 2, Calculator.new(4).complex_calculation end end end

On some systems, the incidence of this sort of test might climb to include a handful of “acceptance build only” tests. At this point, it makes good sense to implement a custom interpreter directive. There are three implementation options here…

Annotating Keyword…

class CalculatorTest<Test::Unit::TestCase extend TestDirectives acceptance_only def test_some_complex_calculation assert_equal 2, Calculator.new(4).complex_calculation end end

Annotated Block…

class CalculatorTest<Test::Unit::TestCase extend TestDirectives acceptance_only do def test_some_complex_calculation assert_equal 2, Calculator.new(4).complex_calculation end end end

Annotated Method Declaration…

class CalculatorTest<Test::Unit::TestCase extend TestDirectives acceptance_only :test_some_complex_calculation do assert_equal 2, Calculator.new(4).complex_calculation end end

Let’s take a look at the implementation of an Annotating Keyword…

module TestDirectives def acceptance_only @acceptance_build = ENV["BUILD"] == "ACCEPTANCE" end def method_added(method_name) remove_method(method_name) unless @acceptance_build @acceptance_build = false end end

CalculatorTest extends the TestDirective Module, so methods defined in TestDirective will be included as class methods in CalculatorTest. When the interpreter encounters the acceptance_only keyword, it’s recognized as a call to the acceptance_only class method. This method simply sets a class level instance variable indicating wether or not the current build is an acceptance build. The real work is done by method_added, a hook method provided by the Module class. When a class (or module) is defined in Ruby, the actual class or module is created as soon as the interpreter encounters the opening declaration (e.g. “class Foo”). As the interpreter encounters method definitions, it adds methods to the method table of the class. After a new method is added, the method_added class method is called with the method name passed as a parameter. In the Annotating Keyword implementation, method_added checks if the new method is valid based on state set by calls to acceptance_only. If the method is not valid in the current context, method_added removes the method from the class definition. As a final step, state is reset back to “normal”. Note that we could choose to not reset state, making method_added work very much like method accessibility keywords (public/protected/private).

The implementation of an Annotated Block…

module TestDirectives def acceptance_only &block block.call if ENV["BUILD"] == "ACCEPTANCE" end end

The greatest strength of an Annotated Block is its exceedingly straight forward implementation. The method declaration itself is a parameter to the acceptance_only class method. acceptance_only then chooses wether of not to evaluate the method definition based on on a check of the environment variable.

Lastly, here is the implementation of Annotated Method Declaration…

module TestDirectives def acceptance_only(method_name, &method_body) if ENV["BUILD"] == "ACCEPTANCE" define_method method_name, method_body end end end

Conceptually, Annotated Method Declaration is very similar to Annotated Block. The difference is that instead of passing a method declaration to the annotating class method, the method body and method name are passed, and the annotating method takes care of the plumbing of actually defining the method.

The CalculatorTest example demonstrates an interpreter directive style use of annotations. These same techniques are useful for more AOPish situations. Take the canonical AOP example of logging. Logging is a cross cutting concern. That is to say, logging code can be found throughout an application, tangled up with the actual work of a method. Take an example of a requirement that certain method calls must logged…

class Approval def decline(approver, comment) Logger.log("called decline with #{approver.inspect} #{coment.inspect}") #implementation end end class ApprovalFormatter def render_comment Logger.log("called render_comment}") #implementation end end

An Annotating Keyword implementation would allow for a better separation of concerns …

class Approval extend Loggable logged def decline(approver, comment) #implementation end end class ApprovalFormatter extend Loggable logged def render_comment #implementation end end

The Loggable implementation demonstrates the primary weaknesses of Annotating Keyword, the complexity of it’s implementation…

module Loggable def logged @logged = true end def method_added(method_name) logged_method = @logged @logged = false if logged_method original_method = :"unlogged_#{method_name.to_s}" alias_method original_method, method_name define_method(method_name) do |*args| arg_string = args.collect{ |arg| arg.inspect + " " } unless args.empty? log_message = "called #{method_name}" log_message << " with #{arg_string}" if arg_string Logger.log log_message self.send(original_method, *args) end end end end

Briefly, method_added aliases the method to be logged and redefines the accessor to return a method which logs relevant information before calling the original method.

So which style is appropriate where? Annotating Keyword is certainly the most aesthetically pleasant to use, but it suffer from what Anders Hejlsberg calls simplexity. The simple usage syntax hides a complex implementation. Truly simple solutions are simple from top to bottom. This complexity increases when multiple annotations come into play. I’m inclined to use it for interpreter directive style annotations, or where I need to chain AOP style annotations.

Annotated Block is the middle-ground option. It avoids the use of the method_added hook, leaving it free for other uses (some of which may not be fully within the developers control). Like Annotating Keyword, it’s chain-able, albeit only through some unfortunately indented code. Simplicity is a double edged sword here. Because an Annotating Block know so little about the methods it wraps, it is limited in how it can interact with those methods. In particular, it does not have access to the arguments of the methods it wraps. The only way it can supplement its weak position is to maintain some sort of state that interacts with method_added, adding the complexity of Annotating Keyword. I prefer it for simple interpreter directive usages limited to including or excluding the definition of methods or execution of a code block.

Annotated Method Declaration is the only option that allows for code execution before the annotated method is defined. This is a powerful property when coupled with its access to the parameters passed to the called method. The major drawback of Annotated Method Declaration is that it cannot be chained. I prefer to use it for AOP style annotations when an inability to add multiple annotations is acceptable.

Martin Fowler has an entry on RubyAnnotations on his bliki. Be sure to read Jay Field’s recent write up on class method declaration syntax. Thanks to Paul Gross for pointing out that a post on annotations should be part of this series.

Thanks for reading. As always your comments are appreciated.

Friday, October 26th, 2007 at 12:46 pm.
Filed under patterns/idiom/style.
Subscribe to RSS 2.0.
Comments and trackbacks disabled.