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 = 
i(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_properties ⇒ 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. 



424
425
426
 
# File 'lib/dm-core/associations/relationship.rb', line 424

def child_properties
  @child_properties
end

#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_properties ⇒ 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. 



427
428
429
 
# File 'lib/dm-core/associations/relationship.rb', line 427

def parent_properties
  @parent_properties
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



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

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



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

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
175
 
# 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) 


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

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. 



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

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



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

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

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

  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
358
 
# 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) 


268
269
270
 
# File 'lib/dm-core/associations/relationship.rb', line 268

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.



277
278
279
 
# File 'lib/dm-core/associations/relationship.rb', line 277

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
 
# File 'lib/dm-core/associations/relationship.rb', line 416

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

#inverse ⇒ Object

Get the inverse relationship from the target model



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

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

  @inverse = options[:inverse]

  return @inverse if kind_of_inverse?(@inverse)

  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



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

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



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

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) 


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

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. 



240
241
242
 
# File 'lib/dm-core/associations/relationship.rb', line 240

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) 


285
286
287
 
# File 'lib/dm-core/associations/relationship.rb', line 285

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.



294
295
296
 
# File 'lib/dm-core/associations/relationship.rb', line 294

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:

  • value (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