Overall, the most common way to register a callback method is to declare it at the top of the class using a typical Rails macro-style class method. However, there’s a less verbose way to do it also. Simply implement the callback as a method in your class. In other words, I could have coded the prior example as follows:

class Beethoven < ActiveRecord::Base
  ...

  protected

    def before_destroy
      logger.info "Friends applaud, the comedy is over"
    end

end

This is a rare case of the less-verbose solution being bad. In fact, it is almost always preferable, dare I say it is the Rails way, to use the callback macros over implementing callback methods, for the following reasons:

class Napoleon < ActiveRecord::Base
  before_destroy {|r| logger.info "Josephine..." }
  ...
end

In total, there are 14 types of callbacks you can register on your models! Twelve of them are matching before/after callback pairs, such as before_validation and after_validation. (The other two, after_initialize and after_find, are special, and we’ll discuss them later in this section.)

If you return a Boolean false (not nil) from a callback method, ActiveRecord halts the execution chain. No further callbacks are executed. The save method will return false, and save! will raise a RecordNotSaved error.

Keep in mind that since the last expression of a Ruby method is returned implicitly, it is a pretty common bug to write a callback that halts execution unintentionally. If you have an object with callbacks that mysteriously fails to save, make sure you aren’t returning false by mistake.

Of course, the callback you should use for a given situation depends on what you’re trying to accomplish. The best I can do is to serve up some examples to inspire you with your own code.

class CreditCard < ActiveRecord::Base
  ...
  private

    def before_validation_on_create
      # Strip everything in the number except digits
      self.number = number.gsub(/[^0-9]/, "")
    end

end

class Address < ActiveRecord::Base
  include GeoKit::Geocoders

  before_save :geolocate
  validates_presence_of :line_one, :state, :zip
  ...

  private

    def geolocate
      res = GoogleGeocoder.geocode(to_s)
      self.latitude = res.lat
      self.longitude = res.lng
    end
end

def geolocate
  res = GoogleGeocoder.geocode(to_s)
  return false if not res.success     # halt execution

  self.latitude = res.lat
  self.longitude = res.lng
end

def geolocate
  res = GoogleGeocoder.geocode(to_s)
  if res.success
    self.latitude = res.lat
    self.longitude = res.lng
  else
    errors.add_to_base("Geocoding failed. Please check address.")
    return false
  end
end

class Account < ActiveRecord::Base
  ...
  def before_destroy
     update_attribute(:deleted_at, Time.now) and return false
  end

end

# Destroys the file.  Called in the after_destroy callback
def destroy_file
  FileUtils.rm(full_filename)
  ...
rescue
  logger.info "Exception destroying  #{full_filename ... }"
  logger.warn $!.backtrace.collect { |b| " > #{b}" }.join("
")
end

The after_initialize callback is invoked whenever a new ActiveRecord model is instantiated (either from scratch or from the database). Having it available prevents you from having to muck around with overriding the actual initialize method.

The after_find callback is invoked whenever ActiveRecord loads a model object from the database, and is actually called before after_initialize, if both are implemented. Because after_find and after_initialize are called for each object found and instantiated by finders, performance constraints dictate that they can only be added as methods, and not via the callback macros.

What if you want to run some code only the first time that a model is ever instantiated, and not after each database load? There is no native callback for that scenario, but you can do it using the after_initialize callback. Just add a condition that checks to see if it is a new record:

def after_initialize
 if new_record?
   ...
 end
end

In a number of Rails apps that I’ve written, I’ve found it useful to capture user preferences in a serialized hash associated with the User object. The serialize feature of ActiveRecord models makes this possible, since it transparently persists Ruby object graphs to a text column in the database. Unfortunately, you can’t pass it a default value, so I have to set one myself:

class User < ActiveRecord::Base
  serialize :preferences # defaults to nil
  ...

  private

    def after_initialize
      self.preferences ||= Hash.new
    end
end

Using the after_initialize callback, I can automatically populate the preferences attribute of my user model with an empty hash, so that I never have to worry about it being nil when I access it with code such as user.preferences [:show_help_text] = false. Of course, you would only want to store data in serialized columns that you had no interest in querying with SQL in the future.

Ruby’s metaprogramming capabilities combined with the ability to run code whenever a model is loaded using the after_find callback are a powerful mix. Since we’re not done learning about callbacks yet, we’ll come back to uses of after_find later on in the chapter, in the section “Modifying ActiveRecord Classes at Runtime.”

It is common enough to want to reuse callback code for more than one object that Rails gives you a way to write callback classes. All you have to do is pass a given callback queue an object that responds to the name of the callback and takes the model object as a parameter.

Here’s our paranoid example from the previous section as a callback class:

class MarkDeleted
  def self.before_destroy(model)
     model.update_attribute(:deleted_at, Time.now) and return false
  end
end

The behavior of MarkDeleted is stateless, so I added the callback as a class method. Now you don’t have to instantiate MarkDeleted objects for no good reason. All you do is pass the class to the callback queue for whichever models you want to have the mark-deleted behavior:

class Account < ActiveRecord::Base
  before_destroy MarkDeleted
  ...
end

class Invoice < ActiveRecord::Base
  before_destroy MarkDeleted
  ...

end

class Auditor
  def initialize(audit_log)
    @audit_log = audit_log
  end

  def after_create(model)
    @audit_log.created(model.inspect)
  end

  def after_update(model)
    @audit_log.updated(model.inspect)
  end

  def after_destroy(model)
    @audit_log.destroyed(model.inspect)
  end
end

class Account < ActiveRecord::Base
  after_create Auditor.new(DEFAULT_AUDIT_LOG)
  after_update Auditor.new(DEFAULT_AUDIT_LOG)
  after_destroy Auditor.new(DEFAULT_AUDIT_LOG)
  ...
end

class ActiveRecord::Base
  def self.acts_as_audited(audit_log=DEFAULT_AUDIT_LOG)
    auditor = Auditor.new(audit_log)
    after_create auditor
    after_update auditor
    after_destroy auditor
  end
end

class Account < ActiveRecord::Base
  acts_as_audited
  ...
end

def test_auditor_logs_created
  (model = mock).expects(:inspect).returns('foo')
  (log = mock).expects(:created).with('foo')

  Auditor.new(log).after_create(model)
end

When ActiveRecord::Observer is subclassed, it breaks down the name of the subclass by stripping off the “Observer” part. In the case of our AccountObserver in the preceding example, it would know that you want to observe the Account class. However, that’s not always desirable behavior. In fact, with general-purpose code such as our Auditor, it’s positively a step backward, so it’s possible to overrule the naming convention with the use of the observe macro-style method. We still extend ActiveRecord::Observer, but we can call the subclass whatever we want and tell it explicitly what to observe:

class Auditor < ActiveRecord::Observer
  observe Account, Invoice, Payment

  def after_create(model)
    DEFAULT_AUDIT_LOG.created(model.inspect)
  end

  def after_update(model)
    DEFAULT_AUDIT_LOG.updated(model.inspect)
  end

  def after_destroy(model)
    DEFAULT_AUDIT_LOG.destroyed(model.inspect)
  end
end

If there weren’t a place for you to tell Rails which observers to load, they would never get loaded at all, since they’re not referenced from any other code in your application. As mentioned in Chapter 1, “Rails Environments and Configuration,” your application’s boilerplate config/environment.rb has a commented-out line where you should define the observers to be loaded:

# Activate observers that should always be running
config.active_record.observers = [:auditor]

Observers are notified before the in-object callbacks are triggered. Otherwise, it wouldn’t be possible to act on the whole object in something like a before_destroy observer without having the object’s own callbacks executed first.

Mapping object inheritance effectively to a relational database is not one of those problems with a definitive solution. We’re only going to talk about the one mapping strategy that Rails supports natively, which is single-table inheritance, called STI for short.

In STI, you establish one table in the database to holds all of the records for any object in a given inheritance hierarchy. In ActiveRecord STI, that one table is named after the top parent class of the hierarchy. In the example we’ve been considering, that table would be named timesheets.

Hey, that’s what it was called before, right? Yes, but to enable STI we have to add a type column to contain a string representing the type of the stored object. The following migration would properly set up the database for our example:

class AddTypeToTimesheet < ActiveRecord::Migration
  def self.up
    add_column :timesheets, :type, :string
  end

  def self.down
    remove_column :timesheets, :type
  end
end

No default value is needed. Once the type column is added to an ActiveRecord model, Rails will automatically take care of keeping it populated with the right value. Using the console, we can see this behavior in action:

>> d = DraftTimesheet.create
>> d.type
=> 'DraftTimesheet'

When you try to find an object using the find methods of a base STI class, Rails will automatically instantiate objects using the appropriate subclass. This is especially useful in cases such as the timesheet example we’ve been describing, where we retrieve all the records for a particular user and then call methods that behave differently depending on the object’s class.

>> Timesheet.find(:first)
=> #<DraftTimesheet:0x2212354...>

set_inheritance_column "not_sti"

Although Rails makes it extremely simple to use single-table inheritance, there are a few caveats that you should keep in mind.

To begin with, you cannot have an attribute on two different subclasses with the same name but a different type. Since Rails uses one table to store all subclasses, these attributes with the same name occupy the same column in the table. Frankly, there’s not much of a reason why that should be a problem unless you’ve made some pretty bad data-modeling decisions.

More importantly, you need to have one column per attribute on any subclass and any attribute that is not shared by all the subclasses must accept nil values. In the recurring example, PaidTimesheet has a paid_hours column that is not used by any of the other subclasses. DraftTimesheet and SubmittedTimesheet will not use the paid_hours column and leave it as null in the database. In order to validate data for columns not shared by all subclasses, you must use ActiveRecord validations and not the database.

Third, it is not a good idea to have subclasses with too many unique attributes. If you do, you will have one database table with many null values in it. Normally, a tree of subclasses with a large number of unique attributes suggests that something is wrong with your application design and that you should refactor. If you have an STI table that is getting out of hand, it is time to reconsider your decision to use inheritance to solve your particular problem. Perhaps your base class is too abstract?

Finally, legacy database constraints may require a different name in the database for the type column. In this case, you can set the new column name using the class method set_inheritance_column in the base class. For the Timesheet example, we could do the following:

class Timesheet < ActiveRecord::Base
  set_inheritance_column 'object_type'
end

Now Rails will automatically populate the object_type column with the object’s type.

It seems pretty common for applications, particularly data-management ones, to have models that are very similar in terms of their data payload, mostly varying in their behavior and associations to each other. If you used object-oriented languages prior to Rails, you’re probably already accustomed to breaking down problem domains into hierarchical structures.

Take for instance, a Rails application that deals with the population of states, counties, cities, and neighborhoods. All of these are places, which might lead you to define an STI class named Place as shown in Listing 9.2. I’ve also included the database schema for clarity:^[6]

# == Schema Information
#
# Table name: places
#
#  id                :integer(11)   not null, primary key
#  region_id         :integer(11)
#  type              :string(255)
#  name              :string(255)
#  description       :string(255)
#  latitude          :decimal(20, 1)
#  longitude         :decimal(20, 1)
#  population        :integer(11)
#  created_at        :datetime
#  updated_at        :datetime

class Place < ActiveRecord::Base
end

Place is in essence an abstract class. It should not be instantiated, but there is no foolproof way to enforce that in Ruby. (No big deal, this isn’t Java!) Now let’s go ahead and define concrete subclasses of Place:

class State < Place
  has_many :counties, :foreign_key => 'region_id'
  has_many :cities, :through => :counties
end

class County < Place
  belongs_to :state, :foreign_key => 'region _id'
  has_many :cities, :foreign_key => 'region _id'
end

class City < Place
  belongs_to :county, :foreign_key => 'region _id'
end

You might be tempted to try adding a cities association to State, knowing that has_many :through works with both belongs_to and has_many target associations. It would make the State class look something like this:

class State < Place
  has_many :counties, :foreign_key => 'region_id'
  has_many :cities, :through => :counties
end

That would certainly be cool, if it worked. Unfortunately, in this particular case, since there’s only one underlying table that we’re querying, there simply isn’t a way to distinguish among the different kinds of objects in the query:

Mysql::Error: Not unique table/alias: 'places': SELECT places.* FROM
places INNER JOIN places ON places.region_id = places.id WHERE
((places.region_id = 187912) AND ((places.type = 'County'))) AND
((places.`type` = 'City' ))

What would we have to do to make it work? Well, the most realistic would be to use specific foreign keys, instead of trying to overload the meaning of region_id for all the subclasses. For starters, the places table would look like the example in Listing 9.3.

# == Schema Information
#
# Table name: places
#
#  id                :integer(11)   not null, primary key
#  state_id          :integer(11)
#  county_id         :integer(11)
#  type              :string(255)
#  name              :string(255)
#  description       :string(255)
#  latitude          :decimal(20, 1)
#  longitude         :decimal(20, 1)
#  population        :integer(11)
#  created_at        :datetime
#  updated_at        :datetime

The subclasses would be simpler without the :foreign_key options on the associations. Plus you could use a regular has_many relationship from State to City, instead of the more complicated has_many :through.

class State < Place
  has_many :counties
  has_many :cities
end

class County < Place
  belongs_to :state
  has_many :cities
end

class City < Place
  belongs_to :county
end

Of course, all those null columns in the places table won’t win you any friends with relational database purists. That’s nothing, though. Just a little bit later in this chapter we’ll take a second, more in-depth look at polymorphic has_many relationships, which will make the purists positively hate you.

In our recurring Time and Expenses example, let’s assume that we want both BillableWeek and Timesheet to have many comments (a shared Comment class). A naive way to solve this problem might be to have the Comment class belong to both the BillableWeek and Timesheet classes and have billable_week_id and timesheet_id as columns in its database table.

class Comment < ActiveRecord::Base
  belongs_to :timesheet
  belongs_to :expense_report
end

That approach is naive because it would be difficult to work with and hard to extend. Among other things, you would need to add code to the application to ensure that a Comment never belonged to both a BillableWeek and a Timesheet at the same time. The code to figure out what a given comment is attached to would be cumbersome to write. Even worse, every time you want to be able to add comments to another type of class, you’d have to add another nullable foreign key column to the comments table.

Rails solves this problem in an elegant fashion, by allowing us to define what it terms polymorphic associations, which we covered when we described the :polymorphic => true option of the belongs_to association in Chapter 7, “ActiveRecord Associations.”

class Comment < ActiveRecord::Base
  belongs_to :commentable, :polymorphic => true
end

class Timesheet < ActiveRecord::Base
  has_many :comments, :as => :commentable
end

class BillableWeek < ActiveRecord::Base
  has_many :comments, :as => :commentable
end

class CreateComments < ActiveRecord::Migration
  def self.up
    create_table :comments do |t|
      t.column :text,             :text
      t.column :commentable_id,   :integer
      t.column :commentable_type, :string
    end
  end
end

>> c = Comment.create(:text => "I could be commenting anything.")
>> t = TimeSheet.create
>> b = BillableWeek.create
>> c.update_attribute(:commentable, t)
=> true
>> "#{c.commentable_type}: #{c.commentable_id}"
=> "Timesheet: 1"
>> c.update_attribute(:commentable, b)
=> true
>> "#{c.commentable_type}: #{c.commentable_id}"
=> "BillableWeek: 1"

class Comment < ActiveRecord::Base
  belongs_to :user
  belongs_to :commentable, :polymorphic => true
end

class User < ActiveRecord::Base
  has_many :comments
  has_many :commentables, :through => :comments
end

>> User.find(:first).comments
ActiveRecord::HasManyThroughAssociationPolymorphicError: Cannot have
a has_many :through association 'User#commentables' on the polymorphic
object 'Comment#commentable'.

class User < ActiveRecord::Base
  has_many :comments
  has_many :commented_timesheets, :through => :comments,
           :source => :commentable, :source_type => 'Timesheet'
  has_many :commented_billable_weeks, :through => :comments,
           :source => :commentable, :source_type => 'BillableWeek'
end

>> User.find(:first).commented_timesheets
=> [#<Timesheet:0x575b98 @attributes={}> ]

As we work toward the end of this book’s coverage of ActiveRecord, you might have noticed that we haven’t really touched on a subject of particular importance to many programmers: foreign-key constraints in the database. That’s mainly because use of foreign-key constraints simply isn’t the Rails way to tackle the problem of relational integrity. To put it mildly, that opinion is controversial and some developers have written off Rails (and its authors) for expressing it.

There really isn’t anything stopping you from adding foreign-key constraints to your database tables, although you’d do well to wait until after the bulk of development is done. The exception, of course, is those polymorphic associations, which are probably the most extreme manifestation of the Rails opinion against foreign-key constraints. Unless you’re armed for battle, you might not want to broach that particular subject with your DBA.

In many other interpreted, OO programming languages, you have two phases of execution—one in which the interpreter loads the class definitions and says “this is the definition of what I have to work with,” followed by the phase in which it executes the code. This makes it difficult (though not necessarily impossible) to add new methods to a class dynamically during execution.

In contrast, Ruby lets you add methods to a class at any time. In Ruby, when you type class MyClass, you’re doing more than simply telling the interpreter to define a class; you’re telling it to “execute the following code in the scope of this class.”

Let’s say you have the following Ruby script:

1  class Foo < ActiveRecord::Base
2    has_many :bars
3  end

4  class Foo
5    belongs_to :spam
6  end

When the interpreter gets to line 1, you are telling it to execute the following code (up to the matching end) in the context of the Foo class object. Because the Foo class object doesn’t exist yet, it goes ahead and creates the class. At line 2, we execute the statement has_many :bars in the context of the Foo class object. Whatever the has_many message does, it does right now.

When we again say class Foo at line 4, we are once again telling the interpreter to execute the following code in the context of the Foo class object, but this time, the interpreter already knows about class Foo; it doesn’t actually create another class. Therefore, on line 5, we are simply telling the interpreter to execute the belongs_to :spam statement in the context of that same Foo class object.

In order to execute the has_many and belongs_to statements, those methods need to exist in the context in which they are executed. Because these are defined as class methods in ActiveRecord::Base, and we have previously defined class Foo as extending ActiveRecord::Base, the code will execute without a problem.

However, when we defined our Commentable module like this:

module Commentable
  has_many :comments, :as => :commentable do
    def approved
      find( :all,
        :conditions => ['approved = ?', true ] )
    end
  end
end

...we get an error when it tries to execute the has_many statement. That’s because the has_many method is not defined in the context of the Commentable module object.

Given what we now know about how Ruby is interpreting the code, we now realize that what we really want is for that has_many statement to be executed in the context of the including class.

Luckily, Ruby’s Module class defines a handy callback that we can use to do just that. If a Module object defines the method included, it gets run whenever that module is included in another module or class. The argument passed to this method is the module/class object into which this module is being included.

We can define an included method on our Commentable module object so that it executes the has_many statement in the context of the including class (Timesheet, ExpenseReport, and so on):

module Commentable
  def self.included(base)
    base.class_eval do
      has_many :comments, :as => :commentable do
        def approved
          find(:all, :conditions => ['approved = ?', true ])
        end
      end
    end
  end
end

Now, when we include the Commentable module in our model classes, it will execute the has_many statement just as if we had typed it into each of those classes’ bodies.

has_many :comments, :as => :commentable, :extend => Commentable

A relatively complete description of everything you can do with Ruby metaprogramming, and how to do it correctly, would fill its own book. For instance, you might realize that doing things like executing arbitrary Ruby code straight out of the database is inherently dangerous. That’s why I emphasize again that the examples shown here are very simplified. All I want to do is give you a taste of the possibilities.

If you do decide to begin leveraging these kinds of techniques in real-world applications, you’ll have to consider security and approval workflow and a host of other important concerns. Instead of allowing arbitrary Ruby code to be executed, you might feel compelled to limit it to a small subset related to the problem at hand. You might design a compact API, or even delve into authoring a domain-specific language (DSL), crafted specifically for expressing the business rules and behaviors that should be loaded dynamically. Proceeding down the rabbit hole, you might write custom parsers for your DSL that could execute it in different contexts —some for error detection and others for reporting. It’s one of those areas where the possibilities are quite limitless.

My former colleague Jay Fields and I pioneered the mix of Ruby metaprogramming, Rails, and internal^[9] domain-specific languages while doing Rails application development for ThoughtWorks clients. I still occasionally speak at conferences and blog about writing DSLs in Ruby.

Jay has also continued writing and speaking about his evolution of Ruby DSL techniques, which he calls Business Natural Languages (or BNL for short^[10]). When developing BNLs, you craft a domain-specific language that is not necessarily valid Ruby syntax, but is close enough to be transformed easily into Ruby and executed at runtime, as shown in Listing 9.6.

employee John Doe
compensate 500 dollars for each deal closed in the past 30 days
compensate 100 dollars for each active deal that closed more than
365 days ago
compensate 5 percent of gross profits if gross profits are greater
than
1,000,000 dollars
compensate 3 percent of gross profits if gross profits are greater
than
2,000,000 dollars
compensate 1 percent of gross profits if gross profits are greater
than
3,000,000 dollars

The ability to leverage advanced techniques such as DSLs is yet another powerful tool in the hands of experienced Rails developers.