Class: Mongoid::Relations::Metadata

Inherits:
Hash show all
Defined in:
lib/mongoid/relations/metadata.rb

Overview

The “Grand Poobah” of information about any relation is this class. It contains everything you could ever possible want to know.

Instance Method Summary collapse

Methods included from Extensions::Hash::Scoping

#scoped

Methods included from Extensions::Hash::CriteriaHelpers

#expand_complex_criteria

Constructor Details

#initialize(properties = {}) ⇒ Metadata

Instantiate new metadata for a relation.

Examples:

Create the new metadata.

Metadata.new(:name => :addresses)

Parameters:

  • properties (Hash) (defaults to: {}) —

    The relation options.

Since:

  • 2.0.0.rc.1



321
322
323
324
 
# File 'lib/mongoid/relations/metadata.rb', line 321

def initialize(properties = {})
  Options.validate!(properties)
  merge!(properties)
end

Instance Method Details

#as ⇒ true, false

Returns the as option of the relation.

Examples:

Get the as option.

metadata.as

Returns:

  • (true, false) —

    The as option.

Since:

  • 2.1.0



19
20
21
 
# File 'lib/mongoid/relations/metadata.rb', line 19

def as
  self[:as]
end

#as? ⇒ true, false

Tells whether an as option exists.

Examples:

Is the as option set?

metadata.as?

Returns:

  • (true, false) —

    True if an as exists, false if not.

Since:

  • 2.0.0.rc.1



31
32
33
 
# File 'lib/mongoid/relations/metadata.rb', line 31

def as?
  !!as
end

#autosave ⇒ true, false

Returns the autosave option of the relation.

Examples:

Get the autosave option.

metadata.autosave

Returns:

  • (true, false) —

    The autosave option.

Since:

  • 2.1.0



43
44
45
 
# File 'lib/mongoid/relations/metadata.rb', line 43

def autosave
  self[:autosave]
end

#autosave? ⇒ true, false

Does the metadata have a autosave option?

Examples:

Is the relation autosaving?

metadata.autosave?

Returns:

  • (true, false) —

    If the relation autosaves.

Since:

  • 2.1.0



55
56
57
 
# File 'lib/mongoid/relations/metadata.rb', line 55

def autosave?
  !!autosave
end

#builder(object, loading = false) ⇒ Builder

Gets a relation builder associated with the relation this metadata is for.

Examples:

Get the builder.

metadata.builder(document)

Parameters:

  • object (Object) —

    A document or attributes to give the builder.

Returns:

  • (Builder) —

    The builder for the relation.

Since:

  • 2.0.0.rc.1



70
71
72
 
# File 'lib/mongoid/relations/metadata.rb', line 70

def builder(object, loading = false)
  relation.builder(self, object, loading)
end

#cascade_strategy ⇒ Object

Returns the name of the strategy used for handling dependent relations.

Examples:

Get the strategy.

metadata.cascade_strategy

Returns:

  • (Object) —

    The cascading strategy to use.

Since:

  • 2.0.0.rc.1



82
83
84
85
86
87
88
89
90
 
# File 'lib/mongoid/relations/metadata.rb', line 82

def cascade_strategy
  if dependent?
    strategy =
      %{Mongoid::Relations::Cascading::#{dependent.to_s.classify}}
    strategy.constantize
  else
    return nil
  end
end

#class_name ⇒ String

Returns the name of the class that this relation contains. If the class_name was provided as an option this will return that, otherwise it will determine the name from the name property.

Examples:

Get the class name.

metadata.class_name

Returns:

  • (String) —

    The name of the relation’s proxied class.

Since:

  • 2.0.0.rc.1



102
103
104
 
# File 'lib/mongoid/relations/metadata.rb', line 102

def class_name
  @class_name ||= (self[:class_name] || classify)
end

#constraint ⇒ Constraint

Get the foreign key contraint for the metadata.

Examples:

Get the constaint.

metadata.constraint

Returns:

Since:

  • 2.0.0.rc.1



114
115
116
 
# File 'lib/mongoid/relations/metadata.rb', line 114

def constraint
  @constraint ||= Constraint.new(self)
end

#criteria(object, type = nil) ⇒ Criteria

Get the criteria that is used to query for this metadata’s relation.

Examples:

Get the criteria.

metadata.criteria([ id_one, id_two ])

Parameters:

  • object (Object) —

    The foreign key used for the query.

Returns:

Since:

  • 2.1.0



128
129
130
131
 
# File 'lib/mongoid/relations/metadata.rb', line 128

def criteria(object, type = nil)
  query = relation.criteria(self, object, type)
  order ? query.order_by(order) : query
end

#cyclic ⇒ true, false

Returns the cyclic option of the relation.

Examples:

Get the cyclic option.

metadata.cyclic

Returns:

  • (true, false) —

    The cyclic option.

Since:

  • 2.1.0



141
142
143
 
# File 'lib/mongoid/relations/metadata.rb', line 141

def cyclic
  self[:cyclic]
end

#cyclic? ⇒ true, false

Does the metadata have a cyclic option?

Examples:

Is the metadata cyclic?

metadata.cyclic?

Returns:

  • (true, false) —

    If the metadata is cyclic.

Since:

  • 2.1.0



153
154
155
 
# File 'lib/mongoid/relations/metadata.rb', line 153

def cyclic?
  !!cyclic
end

#dependent ⇒ Symbol

Returns the dependent option of the relation.

Examples:

Get the dependent option.

metadata.dependent

Returns:

  • (Symbol) —

    The dependent option.

Since:

  • 2.1.0



165
166
167
 
# File 'lib/mongoid/relations/metadata.rb', line 165

def dependent
  self[:dependent]
end

#dependent? ⇒ true, false

Does the metadata have a dependent option?

Examples:

Is the metadata performing cascades?

metadata.dependent?

Returns:

  • (true, false) —

    If the metadata cascades.

Since:

  • 2.1.0



177
178
179
 
# File 'lib/mongoid/relations/metadata.rb', line 177

def dependent?
  !!dependent
end

#destructive? ⇒ true, false

Does the relation have a destructive dependent option specified. This is true for :dependent => :delete and :dependent => :destroy.

Examples:

Is the relation destructive?

metadata.destructive?

Returns:

  • (true, false) —

    If the relation is destructive.

Since:

  • 2.1.0



583
584
585
 
# File 'lib/mongoid/relations/metadata.rb', line 583

def destructive?
  @destructive ||= (dependent == :delete || dependent == :destroy)
end

#eager_load(criteria) ⇒ Criteria

Get the criteria needed to eager load this relation.

Examples:

Get the eager loading criteria.

metadata.eager_load(criteria)

Parameters:

  • criteria (Criteria) —

    The criteria to load from.

Returns:

  • (Criteria) —

    The eager loading criteria.

Since:

  • 2.2.0



191
192
193
 
# File 'lib/mongoid/relations/metadata.rb', line 191

def eager_load(criteria)
  relation.eager_load(self, criteria.clone)
end

#embedded? ⇒ true, false

Will determine if the relation is an embedded one or not. Currently only checks against embeds one and many.

Examples:

Is the document embedded.

metadata.embedded?

Returns:

  • (true, false) —

    True if embedded, false if not.

Since:

  • 2.0.0.rc.1



204
205
206
 
# File 'lib/mongoid/relations/metadata.rb', line 204

def embedded?
  @embedded ||= (macro == :embeds_one || macro == :embeds_many)
end

#extension ⇒ Module

Returns the extension of the relation.

Examples:

Get the relation extension.

metadata.extension

Returns:

  • (Module) —

    The extension or nil.

Since:

  • 2.0.0.rc.1



216
217
218
 
# File 'lib/mongoid/relations/metadata.rb', line 216

def extension
  self[:extend]
end

#extension? ⇒ true, false

Tells whether an extension definition exist for this relation.

Examples:

Is an extension defined?

metadata.extension?

Returns:

  • (true, false) —

    True if an extension exists, false if not.

Since:

  • 2.0.0.rc.1



228
229
230
 
# File 'lib/mongoid/relations/metadata.rb', line 228

def extension?
  !!extension
end

#forced_nil_inverse? ⇒ true, false

Does this metadata have a forced nil inverse_of defined. (Used in many to manies)

Examples:

Is this a forced nil inverse?

metadata.forced_nil_inverse?

Returns:

  • (true, false) —

    If inverse_of has been explicitly set to nil.

Since:

  • 2.3.3



241
242
243
 
# File 'lib/mongoid/relations/metadata.rb', line 241

def forced_nil_inverse?
  has_key?(:inverse_of) && inverse_of.nil?
end

#foreign_key ⇒ String

Handles all the logic for figuring out what the foreign_key is for each relations query. The logic is as follows:

  1. If the developer defined a custom key, use that.

  2. If the relation stores a foreign key, use the class_name_id strategy.

  3. If the relation does not store the key, use the inverse_class_name_id strategy.

Examples:

Get the foreign key.

metadata.foreign_key

Returns:

  • (String) —

    The foreign key for the relation.

Since:

  • 2.0.0.rc.1



260
261
262
 
# File 'lib/mongoid/relations/metadata.rb', line 260

def foreign_key
  @foreign_key ||= determine_foreign_key
end

#foreign_key_check ⇒ String

Get the name of the method to check if the foreign key has changed.

Examples:

Get the foreign key check method.

metadata.foreign_key_check

Returns:

  • (String) —

    The foreign key check.

Since:

  • 2.1.0



272
273
274
 
# File 'lib/mongoid/relations/metadata.rb', line 272

def foreign_key_check
  @foreign_key_check ||= "#{foreign_key}_changed?"
end

#foreign_key_setter ⇒ String

Returns the name of the method used to set the foreign key on a document.

Examples:

Get the setter for the foreign key.

metadata.foreign_key_setter

Returns:

  • (String) —

    The foreign_key plus =.

Since:

  • 2.0.0.rc.1



285
286
287
 
# File 'lib/mongoid/relations/metadata.rb', line 285

def foreign_key_setter
  @foreign_key_setter ||= "#{foreign_key}="
end

#index ⇒ true, false

Returns the index option of the relation.

Examples:

Get the index option.

metadata.index

Returns:

  • (true, false) —

    The index option.

Since:

  • 2.1.0



297
298
299
 
# File 'lib/mongoid/relations/metadata.rb', line 297

def index
  self[:index]
end

#indexed? ⇒ true, false

Tells whether a foreign key index exists on the relation.

Examples:

Is the key indexed?

metadata.indexed?

Returns:

  • (true, false) —

    True if an index exists, false if not.

Since:

  • 2.0.0.rc.1



309
310
311
 
# File 'lib/mongoid/relations/metadata.rb', line 309

def indexed?
  !!index
end

#inspect ⇒ String

Since a lot of the information from the metadata is inferred and not explicitly stored in the hash, the inspection needs to be much more detailed.

Examples:

Inspect the metadata.

metadata.inspect

Returns:

  • (String) —

    Oodles of information in a nice format.

Since:

  • 2.0.0.rc.1



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
 
# File 'lib/mongoid/relations/metadata.rb', line 336

def inspect
  "#<Mongoid::Relations::Metadata\n" <<
  "  class_name:           #{class_name},\n" <<
  "  cyclic:               #{cyclic || "No"},\n" <<
  "  dependent:            #{dependent || "None"},\n" <<
  "  inverse_of:           #{inverse_of || "N/A"},\n" <<
  "  key:                  #{key},\n" <<
  "  macro:                #{macro},\n" <<
  "  name:                 #{name},\n" <<
  "  order:                #{order.inspect || "No"},\n" <<
  "  polymorphic:          #{polymorphic? || "No"},\n" <<
  "  relation:             #{relation},\n" <<
  "  setter:               #{setter},\n" <<
  "  versioned:            #{versioned? || "No"}>\n"
end

#inverse(other = nil) ⇒ Symbol

Get the name of the inverse relation if it exists. If this is a polymorphic relation then just return the :as option that was defined.

Examples:

Get the name of the inverse.

metadata.inverse

Parameters:

  • other (Document) (defaults to: nil) —

    The document to aid in the discovery.

Returns:

  • (Symbol) —

    The inverse name.

Since:

  • 2.0.0.rc.1



363
364
365
366
367
 
# File 'lib/mongoid/relations/metadata.rb', line 363

def inverse(other = nil)
  return self[:inverse_of] if has_key?(:inverse_of)
  return self[:as] || lookup_inverse(other) if polymorphic?
  @inverse ||= (cyclic? ? cyclic_inverse : inverse_relation)
end

#inverse_class_name ⇒ true, false

Returns the inverse_class_name option of the relation.

Examples:

Get the inverse_class_name option.

metadata.inverse_class_name

Returns:

  • (true, false) —

    The inverse_class_name option.

Since:

  • 2.1.0



377
378
379
 
# File 'lib/mongoid/relations/metadata.rb', line 377

def inverse_class_name
  self[:inverse_class_name]
end

#inverse_class_name? ⇒ true, false

Returns the if the inverse class name option exists.

Examples:

Is an inverse class name defined?

metadata.inverse_class_name?

Returns:

  • (true, false) —

    If the inverse if defined.

Since:

  • 2.1.0



389
390
391
 
# File 'lib/mongoid/relations/metadata.rb', line 389

def inverse_class_name?
  !!inverse_class_name
end

#inverse_foreign_key ⇒ String

Used for relational many to many only. This determines the name of the foreign key field on the inverse side of the relation, since in this case there are keys on both sides.

Examples:

Find the inverse foreign key

metadata.inverse_foreign_key

Returns:

  • (String) —

    The foreign key on the inverse.

Since:

  • 2.0.0.rc.1



403
404
405
406
407
 
# File 'lib/mongoid/relations/metadata.rb', line 403

def inverse_foreign_key
  @inverse_foreign_key ||=
    ( inverse_of ? inverse_of.to_s.singularize : inverse_class_name.demodulize.underscore ) <<
    relation.foreign_key_suffix
end

#inverse_klass ⇒ Class

Returns the inverse class of the proxied relation.

Examples:

Get the inverse class.

metadata.inverse_klass

Returns:

  • (Class) —

    The class of the inverse of the relation.

Since:

  • 2.0.0.rc.1



417
418
419
 
# File 'lib/mongoid/relations/metadata.rb', line 417

def inverse_klass
  @inverse_klass ||= inverse_class_name.constantize
end

#inverse_metadata(document) ⇒ Metadata

Get the metadata for the inverse relation.

Examples:

Get the inverse metadata.

metadata.inverse_metadata(doc)

Parameters:

  • document (Document) —

    The document to check.

Returns:

Since:

  • 2.1.0



431
432
433
 
# File 'lib/mongoid/relations/metadata.rb', line 431

def inverse_metadata(document)
  document.reflect_on_association(inverse(document))
end

#inverse_of ⇒ true, false

Returns the inverse_of option of the relation.

Examples:

Get the inverse_of option.

metadata.inverse_of

Returns:

  • (true, false) —

    The inverse_of option.

Since:

  • 2.1.0



443
444
445
 
# File 'lib/mongoid/relations/metadata.rb', line 443

def inverse_of
  self[:inverse_of]
end

#inverse_of? ⇒ true, false

Does the metadata have a inverse_of option?

Examples:

Is an inverse_of defined?

metadata.inverse_of?

Returns:

  • (true, false) —

    If the relation has an inverse_of defined.

Since:

  • 2.1.0



455
456
457
 
# File 'lib/mongoid/relations/metadata.rb', line 455

def inverse_of?
  !!inverse_of
end

#inverse_setter(other = nil) ⇒ String

Returns the setter for the inverse side of the relation.

Examples:

Get the inverse setter.

metadata.inverse_setter

Parameters:

  • other (Document) (defaults to: nil) —

    A document to aid in the discovery.

Returns:

  • (String) —

    The inverse setter name.

Since:

  • 2.0.0.rc.1



469
470
471
 
# File 'lib/mongoid/relations/metadata.rb', line 469

def inverse_setter(other = nil)
  "#{inverse(other)}="
end

#inverse_type ⇒ String

Returns the name of the field in which to store the name of the class for the polymorphic relation.

Examples:

Get the name of the field.

metadata.inverse_type

Returns:

  • (String) —

    The name of the field for storing the type.

Since:

  • 2.0.0.rc.1



482
483
484
485
 
# File 'lib/mongoid/relations/metadata.rb', line 482

def inverse_type
  @inverse_type ||=
    relation.stores_foreign_key? && polymorphic? ? "#{name}_type" : nil
end

#inverse_type_setter ⇒ String

Gets the setter for the field that sets the type of document on a polymorphic relation.

Examples:

Get the inverse type setter.

metadata.inverse_type_setter

Returns:

  • (String) —

    The name of the setter.

Since:

  • 2.0.0.rc.1



496
497
498
 
# File 'lib/mongoid/relations/metadata.rb', line 496

def inverse_type_setter
  @inverse_type_setter ||= inverse_type ? "#{inverse_type}=" : nil
end

#key ⇒ String

This returns the key that is to be used to grab the attributes for the relation or the foreign key or id that a referenced relation will use to query for the object.

Examples:

Get the lookup key.

metadata.key

Returns:

  • (String) —

    The association name, foreign key name, or _id.

Since:

  • 2.0.0.rc.1



510
511
512
 
# File 'lib/mongoid/relations/metadata.rb', line 510

def key
  @key ||= determine_key
end

#klass ⇒ Class

Returns the class of the proxied relation.

Examples:

Get the class.

metadata.klass

Returns:

  • (Class) —

    The class of the relation.

Since:

  • 2.0.0.rc.1



522
523
524
 
# File 'lib/mongoid/relations/metadata.rb', line 522

def klass
  @klass ||= class_name.constantize
end

#macro ⇒ Symbol

Returns the macro for the relation of this metadata.

Examples:

Get the macro.

metadata.macro

Returns:

Since:

  • 2.0.0.rc.1



546
547
548
 
# File 'lib/mongoid/relations/metadata.rb', line 546

def macro
  relation.macro
end

#many? ⇒ true, false

Is this metadata representing a one to many or many to many relation?

Examples:

Is the relation a many?

metadata.many?

Returns:

  • (true, false) —

    If the relation is a many.

Since:

  • 2.1.6



534
535
536
 
# File 'lib/mongoid/relations/metadata.rb', line 534

def many?
  @many ||= (relation.macro.to_s =~ /many/)
end

#name ⇒ Symbol

Get the name associated with this metadata.

Examples:

Get the name.

metadata.name

Returns:

Since:

  • 2.1.0



558
559
560
 
# File 'lib/mongoid/relations/metadata.rb', line 558

def name
  self[:name]
end

#name? ⇒ true, false

Is the name defined?

Examples:

Is the name defined?

metadata.name?

Returns:

  • (true, false) —

    If the name is defined.

Since:

  • 2.1.0



570
571
572
 
# File 'lib/mongoid/relations/metadata.rb', line 570

def name?
  !!name
end

#nested_builder(attributes, options) ⇒ NestedBuilder

Gets a relation nested builder associated with the relation this metadata is for. Nested builders are used in conjunction with nested attributes.

Examples:

Get the nested builder.

metadata.nested_builder(attributes, options)

Parameters:

  • attributes (Hash) —

    The attributes to build the relation with.

  • options (Hash) —

    Options for the nested builder.

Returns:

Since:

  • 2.0.0.rc.1



599
600
601
 
# File 'lib/mongoid/relations/metadata.rb', line 599

def nested_builder(attributes, options)
  relation.nested_builder(self, attributes, options)
end

#order ⇒ Criterion::Complex?

Returns default order for this association.

Examples:

Get default order

metadata.order

Returns:

Since:

  • 2.1.0



716
717
718
 
# File 'lib/mongoid/relations/metadata.rb', line 716

def order
  self[:order]
end

#order? ⇒ true, false

Is a default order set?

Examples:

Is the order set?

metadata.order?

Returns:

  • (true, false) —

    If the order is set.

Since:

  • 2.1.0



728
729
730
 
# File 'lib/mongoid/relations/metadata.rb', line 728

def order?
  !!order
end

#path(document) ⇒ Object

Get the path calculator for the supplied document.

Examples:

Get the path calculator.

metadata.path(document)

Parameters:

  • document (Document) —

    The document to calculate on.

Returns:

  • (Object) —

    The atomic path calculator.

Since:

  • 2.1.0



613
614
615
 
# File 'lib/mongoid/relations/metadata.rb', line 613

def path(document)
  relation.path(document)
end

#polymorphic? ⇒ true, false

Returns true if the relation is polymorphic.

Examples:

Is the relation polymorphic?

metadata.polymorphic?

Returns:

  • (true, false) —

    True if the relation is polymorphic, false if not.

Since:

  • 2.0.0.rc.1



625
626
627
 
# File 'lib/mongoid/relations/metadata.rb', line 625

def polymorphic?
  @polymorphic ||= (!!self[:as] || !!self[:polymorphic])
end

#relation ⇒ Proxy

Get the relation associated with this metadata.

Examples:

Get the relation.

metadata.relation

Returns:

  • (Proxy) —

    The relation proxy class.

Since:

  • 2.1.0



637
638
639
 
# File 'lib/mongoid/relations/metadata.rb', line 637

def relation
  self[:relation]
end

#setter ⇒ String

Gets the method name used to set this relation.

Examples:

Get the setter.

metadata = Metadata.new(:name => :person)
metadata.setter # => "person="

Returns:

  • (String) —

    The name plus “=”.

Since:

  • 2.0.0.rc.1



650
651
652
 
# File 'lib/mongoid/relations/metadata.rb', line 650

def setter
  @setter ||= "#{name.to_s}="
end

#type ⇒ String

Returns the name of the field in which to store the name of the class for the polymorphic relation.

Examples:

Get the name of the field.

metadata.inverse_type

Returns:

  • (String) —

    The name of the field for storing the type.

Since:

  • 2.0.0.rc.1



663
664
665
 
# File 'lib/mongoid/relations/metadata.rb', line 663

def type
  @type ||= polymorphic? ? "#{as.to_s}_type" : nil
end

#type_setter ⇒ String

Gets the setter for the field that sets the type of document on a polymorphic relation.

Examples:

Get the inverse type setter.

metadata.inverse_type_setter

Returns:

  • (String) —

    The name of the setter.

Since:

  • 2.0.0.rc.1



676
677
678
 
# File 'lib/mongoid/relations/metadata.rb', line 676

def type_setter
  @type_setter ||= type ? "#{type}=" : nil
end

#validate? ⇒ true, false

Are we validating this relation automatically?

Examples:

Is automatic validation on?

metadata.validate?

Returns:

  • (true, false) —

    True unless explictly set to false.

Since:

  • 2.0.0.rc.1



688
689
690
691
692
693
694
 
# File 'lib/mongoid/relations/metadata.rb', line 688

def validate?
  unless self[:validate].nil?
    self[:validate]
  else
    self[:validate] = relation.validation_default
  end
end

#versioned? ⇒ true, false

Is this relation using Mongoid’s internal versioning system?

Examples:

Is this relation versioned?

metadata.versioned?

Returns:

  • (true, false) —

    If the relation uses Mongoid versioning.

Since:

  • 2.1.0



704
705
706
 
# File 'lib/mongoid/relations/metadata.rb', line 704

def versioned?
  !!self[:versioned]
end