Home > Articles > Web Development

  • Print
  • + Share This
This chapter is from the book

This chapter is from the book

5.4 Associations

DataMapper also supports the defining of associations between models. If you’ve used ActiveRecord before, these are nearly the same. Otherwise, know that associations allow you to define the relationships between models (one-to-one, one-to-many, etc.), automatically creating database keys where necessary while also making it possible to conveniently pull up related model objects from associates. Let’s survey the various relationships possible with DataMapper.

5.4.1 Belongs to

In general, you should know that a belongs-to association is meant to help you quickly retrieve an associated resource by defining a one-to-something association between two models (specifically, a child and its parent), where the child class should store its parent’s key as a property. So, for instance, the following associates a comment with a user:

class Comment
  include DataMapper::Resource

  property :id, Serial
  property :body, Text

  belongs_to :user
end

Note that upon automigration the belongs-to association automatically creates the column user_id within the comments table. This means that any model object now has two new methods accessible, user_id and user. The first is simply the ID of the associated user, but the second actually retrieves the user resource for you. These defaults may not always fit your domain logic, however, so they can be altered.

class Paper
  include DataMapper::Resource

  property :id, Serial
  property :body, Text

  belongs_to :author, :class_name => "User",
    :child_key => [:author_id]

  belongs_to :reviewer, :class_name => "User",
    :child_key => [:reviewer_id]
end

Here we have two user objects parenting our paper object. To handle ambiguity, we use the hash keys class_name and child_key. The first is a string representation of the parent class name, and the second is an array indicating how the key should be stored within our child. At the end this produces the methods author_id, reviewer_id, author, and reviewer on papers, where the first two are essentially association properties and the second two are means of retrieving the associated objects.

Let’s take a look at how the belongs_to magic is performed:

module DataMapper::Associations
  def belongs_to(name, options={})
    @_valid_relations = false

    if options.key?(:class_name) &&
      !options.key?(:child_key)

      warn "..." # must set both
    end

    relationship = ManyToOne.setup(name, self, options)
  end
end


module DataMapper::Associations::ManyToOne

  # Set up many-to-one relationship between two models
  # -
  # @api private
  def self.setup(name, model, options = {})
    assert_kind_of 'name',    name,    Symbol
    assert_kind_of 'model',   model,   Model
    assert_kind_of 'options', options, Hash

    repository_name = model.repository.name

    model.class_eval <<-EOS, _ _FILE_ _, _ _LINE_ _
      def #{name}
        #{name}_association.nil? ?
          nil : #{name}_association
      end

      def #{name}=(parent)
        #{name}_association.replace(parent)
      end

      private

      def #{name}_association
        @#{name}_association ||= begin
          unless relationship = model.relationships(
            #{repository_name.inspect})[:#{name}]
            raise ArgumentError,
              "Relationship #{name.inspect} "+
              "does not exist in \#{model}"
          end

          association = Proxy.new(relationship, self)
          child_associations << association
          association
        end
      end
    EOS

    model.relationships(repository_name)[name] =
      Relationship.new(
        name,
        repository_name,
        model,
        options.fetch(:class_name,
          Extlib::Inflection.classify(name)),
        options
      )
  end
end

Starting with the Associations module, we can see that belongs_to fires off the creation of a many-to-one association. Moving on to ManyToOne.setup, we find extensive class evaluation where new methods for the association are defined. These allow us to get or set the association. Note that the reader method essentially proxies to the parent model (using a Proxy class later defined within ManyToOne). It also employs the Relationship class, DataMapper’s most generalized way of storing information on associations within model classes. Finally, note that the use of ManyToOne does not strictly indicate that the relationship between the two models needs to be many-to-one. It may indeed be one-to-one (as determined within the other model), but from the perspective of the child model the more generalized ManyToOne class is appropriate for handling both possibilities.

5.4.2 Has

At this point you may be wondering about the flip side of the relationship, that is, the parent. Has associations are meant to handle this. The characteristics of has associations, however, differ in that they are meant to associate varying numbers of related model resources without storing information within the model object itself.

Let’s create the counterpoint of the comment model we created in the previous section:

class User
  include DataMapper::Resource

  property :id, Serial
  property :login, String, :nullable => false

  has n, :comments
end

Note that the has method takes a minimum of two parameters. The first of these is the cardinality, which may be specified by a number, series, or n, and the second is the symbolized name of the associated class. If you’re scratching your head over n, just know that it is equivalent to 1.0/0 and that it allows an indefinite number of associates. If you’re coming from the ActiveRecord world, you can think of this as the “many” in has_many.

As we did before, we can tweak our relationship for the sake of the domain logic:

class User
  include DataMapper::Resource

  property :id, Serial
  property :login, String, :nullable => false

  has 1, :authored_papers, :class_name => "Paper",
    :child_key => [:author_id],
    :remote_name => :author

  has n, :reviewed_papers, :class_name => "Paper,
    :child_key => [:reviewer_id],
    :remote_name => :reviewer

end

There are plenty of things to notice this time. Once again, we’ve specified the associated class name along with the child_key, but we’ve also set remote_name, which is the symbolized name of the relationship in our other model. Last, note that we set the cardinality of the first to 1, which limits users to authoring only one paper, effectively making the relationship one-to-one.

Having now seen the use of has, let’s go into the source to understand how it works:

module DataMapper::Associations
  def has(cardinality, name, options = {})
    if name.kind_of?(Hash)
      name_through, through =
      name.keys.first, name.values.first
    end

    options = options.merge(
      extract_min_max(cardinality))
    options = options.merge(
      extract_throughness(name))

    # ... some warnings

    klass = options[:max] == 1 ? OneToOne : OneToMany

    # ... we'll show you later

    relationship = klass.setup(
      options.delete(:name), self, options)
  end

  private

  def extract_min_max(constraints)
    assert_kind_of 'constraints', constraints,
      Integer, Range unless constraints == n

    case constraints
      when Integer
        { :min => constraints, :max => constraints }
      when Range
        if constraints.first > constraints.last
          raise ArgumentError, "..."
        end
        { :min => constraints.first,
          :max => constraints.last }
      when n
        { :min => 0, :max => n }
    end
  end

 end

From this we can see that has_many, like belongs_to, creates an association, but that it may be OneToOne or OneToMany based upon the max cardinality. Because we’ve already looked inside one of these associations and because the others are set up in similar ways, we’ll leave it up to you to explore further if you like.

5.4.3 Has through

You may need to work with one-to-many-through or many-to-many relationships. To handle these, DataMapper uses through. Let’s tackle one-to-many-through first and then take a look at many-to-many relationships:

class Post
  include DataMapper::Resource

  has n, :taggings
  has n, :tags, :through => :taggings
end

class Tagging
  include DataMapper::Resource

  belongs_to :post
  belongs_to :tag
end

class Tag
  include DataMapper::Resource

  property :id, Serial
  property :value, String

  has n, :taggings
  has n, :posts, :through => :taggings
end

These examples show us three associated models where the Tagging class acts like a join table bridging the one-to-many relationships from both sides. Sometimes, though, you don’t want to explicitly define this middle table. DataMapper lets you do this by setting through to Resource:

class Post
  include DataMapper::Resource

  has n, :post
  has n, :tags, :through => Resource
end

class Tag
  include DataMapper::Resource

  property :id, Serial
  property :value, String
  has n, :posts, :through => Resource
end

This automatically creates the bridging model for us dynamically. But this isn’t magic; remember the line from the def has snippet of source code that we didn’t show you? Here it is:

  klass = ManyToMany if options[:through] ==
    DataMapper::Resource

With that inside the previous snippet, it’s easy to see that the use of the through option with Resource changes the association setup to a ManyToMany. This special association is used to create a join table model for you. Here’s part of the setup method showing just that:

module DataMapper::Associations::ManyToMany

  def self.setup
    # ... the usual

    unless Object.const_defined?(model_name)
      model = DataMapper::Model.new(storage_name)

      model.class_eval <<-EOS, _ _FILE_ _, _ _LINE_ _
        def self.name; #{model_name.inspect} end
        def self.default_repository_name
          #{repository_name.inspect}
        end
        def self.many_to_many; true end
      EOS

      names.each do |n|
        model.belongs_to(
          Extlib::Inflection.underscore(n).gsub(
            '/', '_').to_sym)
      end

      Object.const_set(model_name, model)
    end

    relationship
  end

Note the particularly unique creation of a model through Model.new as opposed to a standard class definition. This is meant only for dynamically defined models like the one above.

  • + Share This
  • 🔖 Save To Your Account