Class: Mongoid::Relations::Referenced::ManyToMany

Inherits:
Many show all
Defined in:
lib/mongoid/relations/referenced/many_to_many.rb

Overview

This class defines the behaviour for all relations that are a many-to-many between documents in different collections.

Instance Attribute Summary

Attributes inherited from Proxy

#base, #loaded, #metadata, #target

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Many

#bind, #clear, #count, #find, #load!

Methods inherited from Many

#exists?, #find_or_create_by, #find_or_initialize_by, #nil?, #respond_to?, #serializable_hash, #size

Methods inherited from Proxy

#init

Constructor Details

#initialize(base, target, metadata) ⇒ ManyToMany

Instantiate a new references_many relation. Will set the foreign key and the base on the inverse object.

Examples:

Create the new relation.

Referenced::ManyToMany.new(base, target, metadata)

Parameters:

  • base (Document) —

    The document this relation hangs off of.

  • target (Array<Document>) —

    The target of the relation.

  • metadata (Metadata) —

    The relation’s metadata.



146
147
148
149
150
151
152
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 146

def initialize(base, target, metadata)
  init(base, target, metadata) do
    unless base.frozen?
      base.send(metadata.foreign_key_setter, target.map(&:id))
    end
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Mongoid::Relations::Referenced::Many

Class Method Details

.builder(meta, object) ⇒ Builder

Return the builder that is responsible for generating the documents that will be used by this relation.

Examples:

Get the builder.

Referenced::ManyToMany.builder(meta, object)

Parameters:

  • meta (Metadata) —

    The metadata of the relation.

  • object (Document, Hash) —

    A document or attributes to build with.

Returns:

  • (Builder) —

    A new builder object.

Since:

  • 2.0.0.rc.1



302
303
304
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 302

def builder(meta, object)
  Builders::Referenced::ManyToMany.new(meta, object)
end

.embedded? ⇒ false

Returns true if the relation is an embedded one. In this case always false.

Examples:

Is this relation embedded?

Referenced::ManyToMany.embedded?

Returns:

  • (false) —

    Always false.

Since:

  • 2.0.0.rc.1



315
316
317
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 315

def embedded?
  false
end

.foreign_key_default ⇒ Array

Get the default value for the foreign key.

Examples:

Get the default.

Referenced::ManyToMany.foreign_key_default

Returns:

  • (Array) —

    Always an empty array.

Since:

  • 2.0.0.rc.1



327
328
329
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 327

def foreign_key_default
  []
end

.foreign_key_suffix ⇒ String

Returns the suffix of the foreign key field, either “_id” or “_ids”.

Examples:

Get the suffix for the foreign key.

Referenced::ManyToMany.foreign_key_suffix

Returns:

Since:

  • 2.0.0.rc.1



339
340
341
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 339

def foreign_key_suffix
  "_ids"
end

.macro ⇒ Symbol

Returns the macro for this relation. Used mostly as a helper in reflection.

Examples:

Get the macro.

Referenced::ManyToMany.macro

Returns:

  • (Symbol) —

    :references_and_referenced_in_many



350
351
352
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 350

def macro
  :references_and_referenced_in_many
end

.nested_builder(metadata, attributes, options) ⇒ NestedBuilder

Return the nested builder that is responsible for generating the documents that will be used by this relation.

Examples:

Get the nested builder.

Referenced::ManyToMany.builder(attributes, options)

Parameters:

  • metadata (Metadata) —

    The relation metadata.

  • attributes (Hash) —

    The attributes to build with.

  • options (Hash) —

    The options for the builder.

Options Hash (options):

  • :allow_destroy (true, false) —

    Can documents be deleted?

  • :limit (Integer) —

    Max number of documents to create at once.

  • :reject_if (Proc, Symbol) —

    If documents match this option then they are ignored.

  • :update_only (true, false) —

    Only existing documents can be modified.

Returns:

  • (NestedBuilder) —

    A newly instantiated nested builder object.

Since:

  • 2.0.0.rc.1



376
377
378
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 376

def nested_builder(metadata, attributes, options)
  Builders::NestedAttributes::Many.new(metadata, attributes, options)
end

.stores_foreign_key? ⇒ true

Tells the caller if this relation is one that stores the foreign key on its own objects.

Examples:

Does this relation store a foreign key?

Referenced::Many.stores_foreign_key?

Returns:

  • (true) —

    Always true.

Since:

  • 2.0.0.rc.1



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

def stores_foreign_key?
  true
end

Instance Method Details

#<<(*args) ⇒ Object Also known as: concat, push

Appends a document or array of documents to the relation. Will set the parent and update the index in the process.

Examples:

Append a document.

person.addresses << address

Push a document.

person.addresses.push(address)

Concat with other documents.

person.addresses.concat([ address_one, address_two ])

Parameters:



23
24
25
26
27
28
29
30
31
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 23

def <<(*args)
  options = default_options(args)
  args.flatten.each do |doc|
    return doc unless doc
    append(doc, options)
    base.add_to_set(metadata.foreign_key, doc.id)
    doc.save if base.persisted? && !options[:binding]
  end
end

#build(attributes = {}, type = nil, &block) ⇒ Document Also known as: new

Builds a new document in the relation and appends it to the target. Takes an optional type if you want to specify a subclass.

Examples:

Build a new document on the relation.

person.people.build(:name => "Bozo")

Parameters:

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

    The attributes to build the document with.

  • type (Class) (defaults to: nil) —

    Optional class to build the document with.

Returns:



45
46
47
48
49
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 45

def build(attributes = {}, type = nil, &block)
  super.tap do |doc|
    base.send(metadata.foreign_key).push(doc.id)
  end
end

#create(attributes = nil, type = nil, &block) ⇒ Document

Creates a new document on the references many relation. This will save the document if the parent has been persisted.

Examples:

Create and save the new document.

person.preferences.create(:text => "Testing")

Parameters:

  • attributes (Hash) (defaults to: nil) —

    The attributes to create with.

  • type (Class) (defaults to: nil) —

    The optional type of document to create.

Returns:

  • (Document) —

    The newly created document.



62
63
64
65
66
67
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 62

def create(attributes = nil, type = nil, &block)
  build(attributes, type, &block).tap do |doc|
    base.add_to_set(metadata.foreign_key, doc.id)
    doc.save if base.persisted?
  end
end

#create!(attributes = nil, type = nil, &block) ⇒ Document

Creates a new document on the references many relation. This will save the document if the parent has been persisted and will raise an error if validation fails.

Examples:

Create and save the new document.

person.preferences.create!(:text => "Testing")

Parameters:

  • attributes (Hash) (defaults to: nil) —

    The attributes to create with.

  • type (Class) (defaults to: nil) —

    The optional type of document to create.

Returns:

  • (Document) —

    The newly created document.

Raises:



82
83
84
85
86
87
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 82

def create!(attributes = nil, type = nil, &block)
  build(attributes, type, &block).tap do |doc|
    base.add_to_set(metadata.foreign_key, doc.id)
    doc.save! if base.persisted?
  end
end

#delete(document, options = {}) ⇒ Object

Delete a single document from the relation.

Examples:

Delete a document.

person.preferences.delete(preference)

Parameters:

  • document (Document) —

    The document to delete.

Since:

  • 2.0.0.rc.1



97
98
99
100
101
102
103
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 97

def delete(document, options = {})
  target.delete(document).tap do |doc|
    if doc
      binding.unbind_one(doc, default_options.merge!(options))
    end
  end
end

#delete_all(conditions = nil) ⇒ Integer

Deletes all related documents from the database given the supplied conditions.

Examples:

Delete all documents in the relation.

person.preferences.delete_all

Conditonally delete all documents in the relation.

person.preferences.delete_all(:conditions => { :title => "Testing" })

Parameters:

  • conditions (Hash) (defaults to: nil) —

    Optional conditions to delete with.

Returns:

  • (Integer) —

    The number of documents deleted.



117
118
119
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 117

def delete_all(conditions = nil)
  remove_all(conditions, :delete_all)
end

#destroy_all(conditions = nil) ⇒ Integer

Destroys all related documents from the database given the supplied conditions.

Examples:

Destroy all documents in the relation.

person.preferences.destroy_all

Conditonally destroy all documents in the relation.

person.preferences.destroy_all(:conditions => { :title => "Testing" })

Parameters:

  • conditions (Hash) (defaults to: nil) —

    Optional conditions to destroy with.

Returns:

  • (Integer) —

    The number of documents destroyd.



133
134
135
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 133

def destroy_all(conditions = nil)
  remove_all(conditions, :destroy_all)
end

#nullify ⇒ Object Also known as: nullify_all

Removes all associations between the base document and the target documents by deleting the foreign keys and the references, orphaning the target documents in the process.

Examples:

Nullify the relation.

person.preferences.nullify

Since:

  • 2.0.0.rc.1



162
163
164
165
166
167
168
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 162

def nullify
  load! and target.each do |doc|
    base.send(metadata.foreign_key).delete(doc.id)
    dereference(doc)
  end
  target.clear
end

#substitute(new_target, options = {}) ⇒ Many

Substitutes the supplied target documents for the existing documents in the relation. If the new target is nil, perform the necessary deletion.

Examples:

Replace the relation.

person.posts.substitute(new_name)

Parameters:

  • target (Array<Document>) —

    The replacement target.

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

    The options to bind with.

Options Hash (options):

  • :binding (true, false) —

    Are we in build mode?

  • :continue (true, false) —

    Continue binding the inverse?

Returns:

  • (Many) —

    The relation.

Since:

  • 2.0.0.rc.1



188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 188

def substitute(new_target, options = {})
  tap do |relation|
    if new_target
      binding.unbind(options)
      relation.target = new_target.to_a
      base.send(metadata.foreign_key_setter, new_target.map(&:id))
      bind(options)
    else
      relation.target = unbind(options)
    end
    base.save if base.persisted? && !options[:binding]
  end
end

#unbind(options = {}) ⇒ Object

Unbinds the base object to the inverse of the relation. This occurs when setting a side of the relation to nil.

Will delete the object if necessary.

Examples:

Unbind the target.

person.posts.unbind

Parameters:

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

    The options to bind with.

Options Hash (options):

  • :binding (true, false) —

    Are we in build mode?

  • :continue (true, false) —

    Continue binding the inverse?

Since:

  • 2.0.0.rc.1



217
218
219
220
221
 
# File 'lib/mongoid/relations/referenced/many_to_many.rb', line 217

def unbind(options = {})
  target.each(&:delete) if base.persisted?
  binding.unbind(options)
  []
end