This chapter is from the book
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.