Module: Mongoid::Factory

Relationships & Source Files
Namespace Children
Classes: `Instantiator`
Defined in:	lib/mongoid/factory.rb

Overview

Instantiates documents that came from the database.

Instance Method Summary

#build(klass, attributes = nil) ⇒ Document

Builds a new Document from the supplied attributes.
#execute_build(klass, attributes = nil, options = {}) ⇒ Document Internal use only Internal use only

Execute the build.
#execute_from_db(klass, attributes = nil, criteria = nil, selected_fields = nil, execute_callbacks: Threaded.execute_callbacks?) ⇒ Document Internal use only Internal use only

Execute from_db.
#from_db(klass, attributes = nil, criteria = nil, selected_fields = nil) ⇒ Document

Builds a new Document from the supplied attributes loaded from the database.

Instance Method Details

#build(klass, attributes = nil) ⇒ Document

Builds a new Document from the supplied attributes.

This method either instantiates klass or a descendant of klass if the attributes include klass’ discriminator key.

If the attributes contain the discriminator key (which is _type by default) and the discriminator value does not correspond to a descendant of klass then this method would create an instance of klass.

Examples:

Build the document.

Mongoid::Factory.build(Person, { "name" => "Durran" })

Parameters:

klass (Class) —

The class to instantiate from if _type is not present.
attributes (Hash) (defaults to: nil) —

The document attributes.
options (Hash) —

a customizable set of options

Returns:

(Document) —

The instantiated document.

[ GitHub ]

# File 'lib/mongoid/factory.rb', line 154


def build(klass, attributes = nil)
  execute_build(klass, attributes)
end

#execute_build(klass, attributes = nil, options = {}) ⇒ Document

This method is for internal use only.

Note:

A Ruby 2.x bug prevents the options hash from being keyword arguments. Once we drop support for Ruby 2.x, we can reimplement the options hash as keyword arguments. See bugs.ruby-lang.org/issues/15753

Execute the build.

Parameters:

klass (Class) —

The class to instantiate from if _type is not present.
attributes (Hash) (defaults to: nil) —

The document attributes.
options (Hash) (defaults to: {}) —

The options to use.

Options Hash (options):

:execute_callbacks (true | false) —

Flag specifies whether callbacks should be run.

Returns:

(Document) —

The instantiated document.

[ GitHub ]

# File 'lib/mongoid/factory.rb', line 175


def execute_build(klass, attributes = nil, options = {})
  attributes ||= {}
  dvalue = attributes[klass.discriminator_key] || attributes[klass.discriminator_key.to_sym]
  type = klass.get_discriminator_mapping(dvalue)
  if type
    type.construct_document(attributes, options)
  else
    klass.construct_document(attributes, options)
  end
end

#execute_from_db(klass, attributes = nil, criteria = nil, selected_fields = nil, execute_callbacks: Threaded.execute_callbacks?) ⇒ Document

This method is for internal use only.

Execute from_db.

Parameters:

klass (Class) —

The class to instantiate from if _type is not present.
attributes (Hash) (defaults to: nil) —

The document attributes.
criteria (Criteria) (defaults to: nil) —

Optional criteria object.
selected_fields (Hash) (defaults to: nil) —

Fields which were retrieved via #only. If selected_fields are specified, fields not listed in it will not be accessible in the returned document.
execute_callbacks (true | false) —

Whether this method should invoke the callbacks. If true, the callbacks will be invoked normally. If false, the callbacks will be stored in the pending_callbacks list and caller is responsible for invoking run_pending_callbacks at a later time. Use this option to defer callback execution until the entire object graph containing embedded associations is constructed.

Returns:

(Document) —

The instantiated document.

[ GitHub ]

# File 'lib/mongoid/factory.rb', line 234


def execute_from_db(klass, attributes = nil, criteria = nil,
                    selected_fields = nil,
                    execute_callbacks: Threaded.execute_callbacks?)
  Instantiator.new(klass, attributes, criteria, selected_fields)
              .instance(execute_callbacks: execute_callbacks)
end

#from_db(klass, attributes = nil, criteria = nil, selected_fields = nil) ⇒ Document

Builds a new Document from the supplied attributes loaded from the database.

If the attributes contain the discriminator key (which is _type by default) and the discriminator value does not correspond to a descendant of klass then this method raises an UnknownModel error.

If a criteria object is given, it is used in two ways:

If the criteria has a list of fields specified via #only, only those fields are populated in the returned document.
If the criteria has a referencing association (i.e., this document is being instantiated as an association of another document), the other document is also populated in the returned document’s reverse association, if one exists.

Examples:

Build the document.

Mongoid::Factory.from_db(Person, { "name" => "Durran" })

Parameters:

klass (Class) —

The class to instantiate from if _type is not present.
attributes (Hash) (defaults to: nil) —

The document attributes.
criteria (Criteria) (defaults to: nil) —

Optional criteria object.
selected_fields (Hash) (defaults to: nil) —

Fields which were retrieved via #only. If selected_fields are specified, fields not listed in it will not be accessible in the returned document.

Returns:

(Document) —

The instantiated document.

[ GitHub ]

# File 'lib/mongoid/factory.rb', line 212


def from_db(klass, attributes = nil, criteria = nil, selected_fields = nil)
  execute_from_db(klass, attributes, criteria, selected_fields)
end