Module: Mongoid::Factory

Extended by:
Factory
Included in:
Factory
Defined in:
lib/mongoid/factory.rb

Overview

Instantiates documents that came from the database.

Defined Under Namespace

Classes: Instantiator

Instance Method Summary collapse

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.



154
155
156
 
# 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 part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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 https://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.



175
176
177
178
179
180
 
# 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) || klass
  type.construct_document(attributes, options)
end

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

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.

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) (defaults to: Threaded.execute_callbacks?) —

    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.



230
231
232
233
234
235
 
# File 'lib/mongoid/factory.rb', line 230

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:

  1. If the criteria has a list of fields specified via #only, only those fields are populated in the returned document.
  2. 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.



208
209
210
 
# File 'lib/mongoid/factory.rb', line 208

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