Class: DataMapper::Associations::Relationship

Inherits:
Object
  • Object
show all
Includes:
DataMapper::Assertions, Subject
Defined in:
lib/dm-core/associations/relationship.rb

Overview

Base class for relationships. Each type of relationship (1 to 1, 1 to n, n to m) implements a subclass of this class with methods like get and set overridden.

Constant Summary collapse

OPTIONS = 
[ :child_repository_name, :parent_repository_name, :child_key, :parent_key, :min, :max, :inverse, :reader_visibility, :writer_visibility, :default ].to_set

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Subject

#default?, #default_for

Methods included from DataMapper::Assertions

#assert_kind_of

Instance Attribute Details

#child_repository_name ⇒ Object (readonly)

Repository from where child objects are loaded



62
63
64
 
# File 'lib/dm-core/associations/relationship.rb', line 62

def child_repository_name
  @child_repository_name
end

#instance_variable_name ⇒ Object (readonly)

ivar used to store collection of child options in source

instance variable name for source will be @commits

Examples:

for :commits association in


class VersionControl::Branch
  # ...

  has n, :commits
end


57
58
59
 
# File 'lib/dm-core/associations/relationship.rb', line 57

def instance_variable_name
  @instance_variable_name
end

#max ⇒ Object (readonly)

Maximum number of child objects for relationship

maximum is 5

Examples:

for :fouls association in


class Basketball::Player
  # ...

  has 0..5, :fouls
end


98
99
100
 
# File 'lib/dm-core/associations/relationship.rb', line 98

def max
  @max
end

#min ⇒ Object (readonly)

Minimum number of child objects for relationship

minimum is 2

Examples:

for :cores association in


class CPU::Multicore
  # ...

  has 2..n, :cores
end


82
83
84
 
# File 'lib/dm-core/associations/relationship.rb', line 82

def min
  @min
end

#name ⇒ Object (readonly)

Relationship name

name is :parent

Examples:

for :parent association in


class VersionControl::Commit
  # ...

  belongs_to :parent
end


27
28
29
 
# File 'lib/dm-core/associations/relationship.rb', line 27

def name
  @name
end

#options ⇒ Object (readonly)

Options used to set up association of this relationship

options is a hash with a single key, :model

Examples:

for :author association in


class VersionControl::Commit
  # ...

  belongs_to :author, :model => 'Person'
end


42
43
44
 
# File 'lib/dm-core/associations/relationship.rb', line 42

def options
  @options
end

#parent_repository_name ⇒ Object (readonly)

Repository from where parent objects are loaded



67
68
69
 
# File 'lib/dm-core/associations/relationship.rb', line 67

def parent_repository_name
  @parent_repository_name
end

#query ⇒ Object (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns query options for relationship.

For this base class, always returns query options has been initialized with. Overriden in subclasses.



123
124
125
 
# File 'lib/dm-core/associations/relationship.rb', line 123

def query
  @query
end

#reader_visibility ⇒ Symbol (readonly)

Returns the visibility for the source accessor

Returns:

  • (Symbol) —

    the visibility for the accessor added to the source



106
107
108
 
# File 'lib/dm-core/associations/relationship.rb', line 106

def reader_visibility
  @reader_visibility
end

#writer_visibility ⇒ Symbol (readonly)

Returns the visibility for the source mutator

Returns:

  • (Symbol) —

    the visibility for the mutator added to the source



114
115
116
 
# File 'lib/dm-core/associations/relationship.rb', line 114

def writer_visibility
  @writer_visibility
end

Instance Method Details

#==(other) ⇒ Boolean

Compares another Relationship for equivalency

Parameters:

  • other (Relationship) —

    the other Relationship to compare with

Returns:

  • (Boolean) —

    true if they are equal, false if not



368
369
370
371
372
373
374
375
376
377
 
# File 'lib/dm-core/associations/relationship.rb', line 368

def ==(other)
  return true  if equal?(other)
  other.respond_to?(:cmp_repository?, true) &&
  other.respond_to?(:cmp_model?, true)      &&
  other.respond_to?(:cmp_key?, true)        &&
  other.respond_to?(:min)                   &&
  other.respond_to?(:max)                   &&
  other.respond_to?(:query)                 &&
  cmp?(other, :==)
end

#child_key ⇒ PropertySet Also known as: relationship_child_key

Returns a set of keys that identify the target model

Returns:

  • (PropertySet) —

    a set of properties that identify the target model



195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/dm-core/associations/relationship.rb', line 195

def child_key
  return @child_key if defined?(@child_key)

  repository_name = child_repository_name || parent_repository_name
  properties      = child_model.properties(repository_name)

  @child_key = if @child_properties
    child_key = properties.values_at(*@child_properties)
    properties.class.new(child_key).freeze
  else
    properties.key
  end
end

#child_model ⇒ Resource

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns model class used by child side of the relationship

Returns:

  • (Resource) —

    Model for association child



168
169
170
171
172
173
174
 
# File 'lib/dm-core/associations/relationship.rb', line 168

def child_model
  return @child_model if defined?(@child_model)
  child_model_name = self.child_model_name
  @child_model = DataMapper::Ext::Module.find_const(@parent_model || Object, child_model_name)
rescue NameError
  raise NameError, "Cannot find the child_model #{child_model_name} for #{parent_model_name} in #{name}"
end

#child_model? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


177
178
179
180
181
182
 
# File 'lib/dm-core/associations/relationship.rb', line 177

def child_model?
  child_model
  true
rescue NameError
  false
end

#child_model_name ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



185
186
187
 
# File 'lib/dm-core/associations/relationship.rb', line 185

def child_model_name
  @child_model ? child_model.name : @child_model_name
end

#eager_load(source, query = nil) ⇒ Collection

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Eager load the collection using the source as a base

Parameters:

  • source (Collection) —

    the source collection to query with

  • query (Query, Hash) (defaults to: nil) —

    optional query to restrict the collection

Returns:

  • (Collection) —

    the loaded collection for the source



307
308
309
310
311
312
313
314
315
316
 
# File 'lib/dm-core/associations/relationship.rb', line 307

def eager_load(source, query = nil)
  targets = source.model.all(query_for(source, query))

  # FIXME: cannot associate targets to m:m collection yet
  if source.loaded? && !source.kind_of?(ManyToMany::Collection)
    associate_targets(source, targets)
  end

  targets
end

#eql?(other) ⇒ Boolean

Compares another Relationship for equality

Parameters:

  • other (Relationship) —

    the other Relationship to compare with

Returns:

  • (Boolean) —

    true if they are equal, false if not



354
355
356
357
 
# File 'lib/dm-core/associations/relationship.rb', line 354

def eql?(other)
  return true if equal?(other)
  instance_of?(other.class) && cmp?(other, :eql?)
end

#field ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the String the Relationship would use in a Hash

Returns:

  • (String) —

    String name for the Relationship



131
132
133
 
# File 'lib/dm-core/associations/relationship.rb', line 131

def field
  name.to_s
end

#get(resource, other_query = nil) ⇒ Object

Loads and returns “other end” of the association. Must be implemented in subclasses.

Raises:

  • (NotImplementedError) 


266
267
268
 
# File 'lib/dm-core/associations/relationship.rb', line 266

def get(resource, other_query = nil)
  raise NotImplementedError, "#{self.class}#get not implemented"
end

#get!(resource) ⇒ Object

Gets “other end” of the association directly as @ivar on given resource. Subclasses usually use implementation of this class.



275
276
277
 
# File 'lib/dm-core/associations/relationship.rb', line 275

def get!(resource)
  resource.instance_variable_get(instance_variable_name)
end

#hash ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



416
417
418
419
420
421
422
423
424
425
426
427
428
 
# File 'lib/dm-core/associations/relationship.rb', line 416

def hash
  self.class.hash             ^
  name.hash                   ^
  child_repository_name.hash  ^
  parent_repository_name.hash ^
  child_model.hash            ^
  parent_model.hash           ^
  child_properties.hash       ^
  parent_properties.hash      ^
  min.hash                    ^
  max.hash                    ^
  query.hash
end

#inverse ⇒ Object

Get the inverse relationship from the target model



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
 
# File 'lib/dm-core/associations/relationship.rb', line 382

def inverse
  return @inverse if defined?(@inverse)

  @inverse = options[:inverse]

  if kind_of_inverse?(@inverse)
    return @inverse
  end

  relationships = target_model.relationships(relative_target_repository_name)

  @inverse = relationships.detect { |relationship| inverse?(relationship) } ||
    invert

  @inverse.child_key

  @inverse
end

#loaded?(resource) ⇒ Boolean

Checks if “other end” of association is loaded on given resource.

Returns:

  • (Boolean) 


322
323
324
 
# File 'lib/dm-core/associations/relationship.rb', line 322

def loaded?(resource)
  resource.instance_variable_defined?(instance_variable_name)
end

#parent_key ⇒ PropertySet

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a set of keys that identify parent model

Returns:

  • (PropertySet) —

    a set of properties that identify parent model



248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/dm-core/associations/relationship.rb', line 248

def parent_key
  return @parent_key if defined?(@parent_key)

  repository_name = parent_repository_name || child_repository_name
  properties      = parent_model.properties(repository_name)

  @parent_key = if @parent_properties
    parent_key = properties.values_at(*@parent_properties)
    properties.class.new(parent_key).freeze
  else
    properties.key
  end
end

#parent_model ⇒ Resource

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns model class used by parent side of the relationship

Returns:

  • (Resource) —

    Class of association parent



221
222
223
224
225
226
227
 
# File 'lib/dm-core/associations/relationship.rb', line 221

def parent_model
  return @parent_model if defined?(@parent_model)
  parent_model_name = self.parent_model_name
  @parent_model = DataMapper::Ext::Module.find_const(@child_model || Object, parent_model_name)
rescue NameError
  raise NameError, "Cannot find the parent_model #{parent_model_name} for #{child_model_name} in #{name}"
end

#parent_model? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


230
231
232
233
234
235
 
# File 'lib/dm-core/associations/relationship.rb', line 230

def parent_model?
  parent_model
  true
rescue NameError
  false
end

#parent_model_name ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



238
239
240
 
# File 'lib/dm-core/associations/relationship.rb', line 238

def parent_model_name
  @parent_model ? parent_model.name : @parent_model_name
end

#query_for(source, other_query = nil) ⇒ Object

Creates and returns Query instance that fetches target resource(s) (ex.: articles) for given target resource (ex.: author)



150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/dm-core/associations/relationship.rb', line 150

def query_for(source, other_query = nil)
  repository_name = relative_target_repository_name_for(source)

  DataMapper.repository(repository_name).scope do
    query = target_model.query.dup
    query.update(self.query)
    query.update(:conditions => source_scope(source))
    query.update(other_query) if other_query
    query.update(:fields => query.fields | target_key)
  end
end

#relative_target_repository_name ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



402
403
404
 
# File 'lib/dm-core/associations/relationship.rb', line 402

def relative_target_repository_name
  target_repository_name || source_repository_name
end

#relative_target_repository_name_for(source) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



407
408
409
410
411
412
413
 
# File 'lib/dm-core/associations/relationship.rb', line 407

def relative_target_repository_name_for(source)
  target_repository_name || if source.respond_to?(:repository)
    source.repository.name
  else
    source_repository_name
  end
end

#set(resource, association) ⇒ Object

Sets value of the “other end” of association on given resource. Must be implemented in subclasses.

Raises:

  • (NotImplementedError) 


283
284
285
 
# File 'lib/dm-core/associations/relationship.rb', line 283

def set(resource, association)
  raise NotImplementedError, "#{self.class}#set not implemented"
end

#set!(resource, association) ⇒ Object

Sets “other end” of the association directly as @ivar on given resource. Subclasses usually use implementation of this class.



292
293
294
 
# File 'lib/dm-core/associations/relationship.rb', line 292

def set!(resource, association)
  resource.instance_variable_set(instance_variable_name, association)
end

#source_scope(source) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a hash of conditions that scopes query that fetches target object

Returns:

  • (Hash) —

    Hash of conditions that scopes query



142
143
144
 
# File 'lib/dm-core/associations/relationship.rb', line 142

def source_scope(source)
  { inverse => source }
end

#valid?(value, negated = false) ⇒ Boolean

Test the resource to see if it is a valid target

Parameters:

  • source (Object) —

    the resource or collection to be tested

Returns:

  • (Boolean) —

    true if the resource is valid



335
336
337
338
339
340
341
342
343
 
# File 'lib/dm-core/associations/relationship.rb', line 335

def valid?(value, negated = false)
  case value
    when Enumerable then valid_target_collection?(value, negated)
    when Resource   then valid_target?(value)
    when nil        then true
    else
      raise ArgumentError, "+value+ should be an Enumerable, Resource or nil, but was a #{value.class.name}"
  end
end