Class: Mongoid::Relations::Referenced::One

Inherits:
One show all
Defined in:
lib/mongoid/relations/referenced/one.rb

Overview

This class defines the behaviour for all relations that are a one-to-one 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 One

#substitute

Methods inherited from Proxy

#init

Constructor Details

#initialize(base, target, metadata) ⇒ One

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

Examples:

Create the new relation.

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

Parameters:

  • base (Document) —

    The document this relation hangs off of.

  • target (Document) —

    The target (child) of the relation.

  • metadata (Metadata) —

    The relation’s metadata.



41
42
43
44
45
 
# File 'lib/mongoid/relations/referenced/one.rb', line 41

def initialize(base, target, metadata)
  init(base, target, metadata) do
    characterize_one(target)
  end
end

Dynamic Method Handling

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

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::One.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



128
129
130
 
# File 'lib/mongoid/relations/referenced/one.rb', line 128

def builder(meta, object)
  Builders::Referenced::One.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::One.embedded?

Returns:

  • (false) —

    Always false.

Since:

  • 2.0.0.rc.1



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

def embedded?
  false
end

.foreign_key_default ⇒ nil

Get the default value for the foreign key.

Examples:

Get the default.

Referenced::One.foreign_key_default

Returns:

  • (nil) —

    Always nil.

Since:

  • 2.0.0.rc.1



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

def foreign_key_default
  nil
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::One.foreign_key_suffix

Returns:

Since:

  • 2.0.0.rc.1



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

def foreign_key_suffix
  "_id"
end

.macro ⇒ Symbol

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

Examples:

Get the macro.

Referenced::One.macro

Returns:

  • (Symbol) —

    :references_one.



176
177
178
 
# File 'lib/mongoid/relations/referenced/one.rb', line 176

def macro
  :references_one
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::One.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



202
203
204
 
# File 'lib/mongoid/relations/referenced/one.rb', line 202

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

.stores_foreign_key? ⇒ false

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::One.stores_foreign_key?

Returns:

  • (false) —

    Always false.

Since:

  • 2.0.0.rc.1



215
216
217
 
# File 'lib/mongoid/relations/referenced/one.rb', line 215

def stores_foreign_key?
  false
end

Instance Method Details

#bind(options = {}) ⇒ Object

Binds the base object to the inverse of the relation. This is so we are referenced to the actual objects themselves and dont hit the database twice when setting the relations up.

This is called after first creating the relation, or if a new object is set on the relation.

Examples:

Bind the relation.

person.game.bind(:continue => false)

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



27
28
29
30
 
# File 'lib/mongoid/relations/referenced/one.rb', line 27

def bind(options = {})
  binding.bind(options)
  target.save if base.persisted? && !options[:binding]
end

#load!(options = {}) ⇒ One

Will load the target into an array if the target had not already been loaded.

Examples:

Load the relation into memory.

relation.load!

Returns:

  • (One) —

    The relation.

Since:

  • 2.0.0.rc.5



56
57
58
59
 
# File 'lib/mongoid/relations/referenced/one.rb', line 56

def load!(options = {})
  raise_mixed if klass.embedded?
  super(options)
end

#nullify ⇒ Object

Removes the association between the base document and the target document by deleting the foreign key and the reference, orphaning the target document in the process.

Examples:

Nullify the relation.

person.game.nullify

Since:

  • 2.0.0.rc.1



69
70
71
72
73
74
 
# File 'lib/mongoid/relations/referenced/one.rb', line 69

def nullify
  target.send(metadata.foreign_key_setter, nil)
  target.send(:remove_instance_variable, "@#{metadata.inverse(target)}")
  base.send(:remove_instance_variable, "@#{metadata.name}")
  target.save
end

#unbind(old_target, 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 relation.

person.game.unbind(name, :continue => true)

Parameters:

  • old_target (Document) —

    The previous target of the relation.

  • 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



92
93
94
95
96
97
 
# File 'lib/mongoid/relations/referenced/one.rb', line 92

def unbind(old_target, options = {})
  binding(old_target).unbind(options)
  if base.persisted? && !old_target.destroyed? && !options[:binding]
    old_target.delete
  end
end