mongoid 2.0.0.beta.20 → 2.0.0.rc.1

data/lib/mongoid/relations/cascading.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+require "mongoid/relations/cascading/strategy"
+require "mongoid/relations/cascading/delete"
+require "mongoid/relations/cascading/destroy"
+require "mongoid/relations/cascading/nullify"
+
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+
+    # This module defines the behaviour for setting up cascading deletes and
+    # nullifies for relations, and how to delegate to the approriate strategy.
+    module Cascading
+      extend ActiveSupport::Concern
+
+      included do
+        class_inheritable_accessor :cascades
+        self.cascades = []
+        delegate :cascades, :to => "self.class"
+      end
+
+      # Perform all cascading deletes, destroys, or nullifies. Will delegate to
+      # the appropriate strategy to perform the operation.
+      #
+      # @example Execute cascades.
+      #   document.cascade!
+      #
+      # @since 2.0.0.rc.1
+      def cascade!
+        cascades.each do |name|
+          metadata = relations[name]
+          strategy = metadata.cascade_strategy
+          strategy.new(self, metadata).cascade
+        end
+      end
+
+      module ClassMethods #:nodoc:
+
+        # Attempt to add the cascading information for the document to know how
+        # to handle associated documents on a removal.
+        #
+        # @example Set up cascading information
+        #   Movie.cascade(metadata)
+        #
+        # @param [ Metadata ] metadata The metadata for the relation.
+        #
+        # @return [ Class ] The class of the document.
+        #
+        # @since 2.0.0.rc.1
+        def cascade(metadata)
+          tap { cascades << metadata.name.to_s if metadata.dependent? }
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/cascading/delete.rb

@@ -0,0 +1,19 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Cascading #:nodoc:
+      class Delete < Strategy
+
+        # Execute the cascading deletion for the relation if it already exists.
+        # This should be optimized in the future potentially not to load all
+        # objects from the db.
+        #
+        # @example Perform the cascading delete.
+        #   strategy.cascade
+        def cascade
+          relation.to_a.each { |doc| doc.delete } if relation
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/cascading/destroy.rb

@@ -0,0 +1,19 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Cascading #:nodoc:
+      class Destroy < Strategy
+
+        # Execute the cascading deletion for the relation if it already exists.
+        # This should be optimized in the future potentially not to load all
+        # objects from the db.
+        #
+        # @example Perform the cascading destroy.
+        #   strategy.cascade
+        def cascade
+          relation.to_a.each { |doc| doc.destroy } if relation
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/cascading/nullify.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Cascading #:nodoc:
+      class Nullify < Strategy
+
+        # This cascade does not delete the referenced relations, but instead
+        # sets the foreign key values to nil.
+        #
+        # @example Nullify the reference.
+        #   strategy.cascade
+        def cascade
+          relation.nullify
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/cascading/strategy.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Cascading #:nodoc:
+      class Strategy
+
+        attr_accessor :document, :relation, :metadata
+
+        # Initialize the new cascade strategy, which will set up the relation
+        # and the metadata.
+        #
+        # @example Instantiate the strategy
+        #   Strategy.new(document, metadata)
+        #
+        # @param [ Document ] document The document to cascade from.
+        # @param [ Metadata ] metadata The relation's metadata.
+        #
+        # @return [ Strategy ] The new strategy.
+        def initialize(document, metadata)
+          @document, @metadata = document, metadata
+          @relation = document.send(metadata.name)
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/cyclic.rb

@@ -0,0 +1,97 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+
+    # This module provides convenience macros for using cyclic embedded
+    # relations.
+    module Cyclic
+      extend ActiveSupport::Concern
+
+      module ClassMethods #:nodoc:
+
+        # Create a cyclic embedded relation that creates a tree hierarchy for
+        # the document and many embedded child documents.
+        #
+        # @example Set up a recursive embeds many.
+        #
+        #   class Role
+        #     include Mongoid::Document
+        #     recursively_embeds_many
+        #   end
+        #
+        # @example The previous example is a shorcut for this.
+        #
+        #   class Role
+        #     include Mongoid::Document
+        #     embeds_many :child_roles, :class_name => "Role", :cyclic => true
+        #     embedded_in :parent_role, :class_name => "Role", :cyclic => true
+        #   end
+        #
+        # This provides the default nomenclature for accessing a parent document
+        # or its children.
+        #
+        # @since 2.0.0.rc.1
+        def recursively_embeds_many
+          embeds_many cyclic_child_name, :class_name => self.name, :cyclic => true
+          embedded_in cyclic_parent_name, :class_name => self.name, :cyclic => true
+        end
+
+        # Create a cyclic embedded relation that creates a single self
+        # referencing relationship for a parent and a single child.
+        #
+        # @example Set up a recursive embeds one.
+        #
+        #   class Role
+        #     include Mongoid::Document
+        #     recursively_embeds_one
+        #   end
+        #
+        # @example The previous example is a shorcut for this.
+        #
+        #   class Role
+        #     include Mongoid::Document
+        #     embeds_one :child_role, :class_name => "Role", :cyclic => true
+        #     embedded_in :parent_role, :class_name => "Role", :cyclic => true
+        #   end
+        #
+        # This provides the default nomenclature for accessing a parent document
+        # or its children.
+        #
+        # @since 2.0.0.rc.1
+        def recursively_embeds_one
+          embeds_one cyclic_child_name(false), :class_name => self.name, :cyclic => true
+          embedded_in cyclic_parent_name, :class_name => self.name, :cyclic => true
+        end
+
+        private
+
+        # Determines the parent name given the class.
+        #
+        # @example Determine the parent name.
+        #   Role.cyclic_parent_name
+        #
+        # @return [ String ] "parent_" plus the class name underscored.
+        #
+        # @since 2.0.0.rc.1
+        def cyclic_parent_name
+          ("parent_" << self.name.underscore.singularize).to_sym
+        end
+
+        # Determines the child name given the class.
+        #
+        # @example Determine the child name.
+        #   Role.cyclic_child_name
+        #
+        # @param [ true, false ] many Is the a many relation?
+        #
+        # @return [ String ] "child_" plus the class name underscored in
+        #   singular or plural form.
+        #
+        # @since 2.0.0.rc.1
+        def cyclic_child_name(many = true)
+          ("child_" << self.name.underscore.send(many ? :pluralize : :singularize)).to_sym
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/embedded/in.rb

@@ -0,0 +1,172 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Embedded
+
+      # This class defines the behaviour necessary to handle relations that are
+      # embedded within another relation, either as a single document or
+      # multiple documents.
+      class In < Relations::One
+
+        # 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.
+        #
+        # @example Bind the relation.
+        #   name.person.bind(:continue => true)
+        #
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :building Are we in build mode?
+        # @option options [ true, false ] :continue Continue binding the
+        #   inverse?
+        #
+        # @since 2.0.0.rc.1
+        def bind(options = {})
+          binding.bind(options)
+          base.save if target.persisted? && !options[:building]
+        end
+
+        # Instantiate a new embedded_in relation.
+        #
+        # @example Create the new relation.
+        #   Embedded::In.new(name, person, metadata)
+        #
+        # @param [ Document ] base The document the relation hangs off of.
+        # @param [ Document ] target The target (parent) of the relation.
+        # @param [ Metadata ] metadata The relation metadata.
+        #
+        # @return [ In ] The proxy.
+        def initialize(base, target, metadata)
+          init(base, target, metadata) do
+            base.parentize(target)
+          end
+        end
+
+        # 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.
+        #
+        # @example Unbind the relation.
+        #   name.person.unbind(:continue => false)
+        #
+        # @param [ Proxy ] old_target The previous target of the relation.
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :building Are we in build mode?
+        # @option options [ true, false ] :continue Continue binding the
+        #   inverse?
+        #
+        # @since 2.0.0.rc.1
+        def unbind(old_target, options = {})
+          binding(old_target).unbind(options)
+          base.delete if old_target.persisted? && !base.destroyed?
+        end
+
+        private
+
+        # Instantiate the binding associated with this relation.
+        #
+        # @example Get the binding.
+        #   binding([ address ])
+        #
+        # @param [ Proxy ] new_target The new documents to bind with.
+        #
+        # @return [ Binding ] A binding object.
+        #
+        # @since 2.0.0.rc.1
+        def binding(new_target = nil)
+          Bindings::Embedded::In.new(base, new_target || target, metadata)
+        end
+
+        class << self
+
+          # Return the builder that is responsible for generating the documents
+          # that will be used by this relation.
+          #
+          # @example Get the builder.
+          #   Embedded::In.builder(meta, object, person)
+          #
+          # @param [ Metadata ] meta The metadata of the relation.
+          # @param [ Document, Hash ] object A document or attributes to build with.
+          #
+          # @return [ Builder ] A newly instantiated builder object.
+          #
+          # @since 2.0.0.rc.1
+          def builder(meta, object)
+            Builders::Embedded::In.new(meta, object)
+          end
+
+          # Returns true if the relation is an embedded one. In this case
+          # always true.
+          #
+          # @example Is this relation embedded?
+          #   Embedded::In.embedded?
+          #
+          # @return [ true ] true.
+          #
+          # @since 2.0.0.rc.1
+          def embedded?
+            true
+          end
+
+          # Returns the macro for this relation. Used mostly as a helper in
+          # reflection.
+          #
+          # @example Get the macro.
+          #   Mongoid::Relations::Embedded::In.macro
+          #
+          # @return [ Symbol ] :embedded_in.
+          #
+          # @since 2.0.0.rc.1
+          def macro
+            :embedded_in
+          end
+
+          # Return the nested builder that is responsible for generating
+          # the documents that will be used by this relation.
+          #
+          # @example Get the builder.
+          #   NestedAttributes::One.builder(attributes, options)
+          #
+          # @param [ Metadata ] metadata The relation metadata.
+          # @param [ Hash ] attributes The attributes to build with.
+          # @param [ Hash ] options The options for the builder.
+          #
+          # @option options [ true, false ] :allow_destroy Can documents be
+          #   deleted?
+          # @option options [ Integer ] :limit Max number of documents to
+          #   create at once.
+          # @option options [ Proc, Symbol ] :reject_if If documents match this
+          #   option then they are ignored.
+          # @option options [ true, false ] :update_only Only existing documents
+          #   can be modified.
+          #
+          # @return [ Builder ] A newly instantiated nested builder object.
+          #
+          # @since 2.0.0.rc.1
+          def nested_builder(metadata, attributes, options)
+            Builders::NestedAttributes::One.new(metadata, attributes, options)
+          end
+
+          # Tells the caller if this relation is one that stores the foreign
+          # key on its own objects.
+          #
+          # @example Does this relation store a foreign key?
+          #   Embedded::In.stores_foreign_key?
+          #
+          # @return [ false ] false.
+          #
+          # @since 2.0.0.rc.1
+          def stores_foreign_key?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/embedded/many.rb

@@ -0,0 +1,450 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Embedded #:nodoc:
+
+      # This class handles the behaviour for a document that embeds many other
+      # documents within in it as an array.
+      class Many < Relations::Many
+
+        # 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.
+        #
+        # @example Bind the relation.
+        #   person.addresses.bind(:continue => true)
+        #
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :building Are we in build mode?
+        # @option options [ true, false ] :continue Continue binding the
+        #   inverse?
+        #
+        # @since 2.0.0.rc.1
+        def bind(options = {})
+          binding.bind(options)
+          target.each(&:save) if base.persisted? && !options[:building]
+        end
+
+        # Bind the inverse relation between a single document in this proxy
+        # instead of the entire target.
+        #
+        # Used when appending to the target instead of setting the entire
+        # thing.
+        #
+        # @example Bind a single document.
+        #   person.addressses.bind_one(address)
+        #
+        # @param [ Document ] document The document to bind.
+        #
+        # @since 2.0.0.rc.1
+        def bind_one(document, options = {})
+          binding.bind_one(document, options)
+        end
+
+        # Clear the relation. Will delete the documents from the db if they are
+        # already persisted.
+        #
+        # @example Clear the relation.
+        #   person.addresses.clear
+        #
+        # @return [ Many ] The empty relation.
+        def clear
+          substitute(nil)
+        end
+
+        # Create a new document in the relation. This is essentially the same
+        # as doing a #build then #save on the new document.
+        #
+        # @example Create a new document in the relation.
+        #   person.movies.create(:name => "Bozo")
+        #
+        # @param [ Hash ] attributes The attributes to build the document with.
+        # @param [ Class ] type Optional class to create the document with.
+        #
+        # @return [ Document ] The newly created document.
+        def create(attributes = {}, type = nil)
+          build(attributes, type).tap(&:save)
+        end
+
+        # Create a new document in the relation. This is essentially the same
+        # as doing a #build then #save on the new document. If validation
+        # failed on the document an error will get raised.
+        #
+        # @example Create the document.
+        #   person.addresses.create!(:street => "Unter der Linden")</tt>
+        #
+        # @param [ Hash ] attributes The attributes to build the document with.
+        # @param [ Class ] type Optional class to create the document with.
+        #
+        # @raise [ Errors::Validations ] If a validation error occured.
+        #
+        # @return [ Document ] The newly created document.
+        def create!(attributes = {}, type = nil)
+          build(attributes, type).tap(&:save!)
+        end
+
+        # Delete the supplied document from the target. This method is proxied
+        # in order to reindex the array after the operation occurs.
+        #
+        # @example Delete the document from the relation.
+        #   perosn.addresses.delete(address)
+        #
+        # @param [ Document ] document The document to be deleted.
+        #
+        # @return [ Document, nil ] The deleted document or nil if nothing deleted.
+        #
+        # @since 2.0.0.rc.1
+        def delete(document)
+          target.delete(document).tap { reindex }
+        end
+
+        # Delete all the documents in the association without running callbacks.
+        #
+        # @example Delete all documents from the relation.
+        #   person.addresses.delete_all
+        #
+        # @example Conditionally delete documents from the relation.
+        #   person.addresses.delete_all(:conditions => { :street => "Bond" })
+        #
+        # @param [ Hash ] conditions Conditions on which documents to delete.
+        #
+        # @return [ Integer ] The number of documents deleted.
+        def delete_all(conditions = {})
+          remove_all(conditions, false)
+        end
+
+        # Destroy all the documents in the association whilst running callbacks.
+        #
+        # @example Destroy all documents from the relation.
+        #   person.addresses.destroy_all
+        #
+        # @example Conditionally destroy documents from the relation.
+        #   person.addresses.destroy_all(:conditions => { :street => "Bond" })
+        #
+        # @param [ Hash ] conditions Conditions on which documents to destroy.
+        #
+        # @return [ Integer ] The number of documents destroyed.
+        def destroy_all(conditions = {})
+          remove_all(conditions, true)
+        end
+
+        # Finds a document in this association through several different
+        # methods.
+        #
+        # @example Find a document by its id.
+        #   person.addresses.find(BSON::ObjectId.new)
+        #
+        # @example Find documents for multiple ids.
+        #   person.addresses.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
+        #
+        # @example Find documents based on conditions.
+        #   person.addresses.find(:all, :conditions => { :number => 10 })
+        #   person.addresses.find(:first, :conditions => { :number => 10 })
+        #   person.addresses.find(:last, :conditions => { :number => 10 })
+        #
+        # @param [ Array<Object> ] args Various arguments.
+        #
+        # @return [ Array<Document>, Document ] A single or multiple documents.
+        def find(*args)
+          type, criteria = Criteria.parse!(self, true, *args)
+          case type
+          when :first then return criteria.one
+          when :last then return criteria.last
+          else
+            criteria.tap do |crit|
+              crit.documents = target if crit.is_a?(Criteria)
+            end
+          end
+        end
+
+        # Instantiate a new embeds_many relation.
+        #
+        # @example Create the new relation.
+        #   Many.new(person, addresses, metadata)
+        #
+        # @param [ Document ] base The document this relation hangs off of.
+        # @param [ Array<Document> ] target The child documents of the relation.
+        # @param [ Metadata ] metadata The relation's metadata
+        #
+        # @return [ Many ] The proxy.
+        def initialize(base, target, metadata)
+          init(base, target, metadata) do
+            target.each_with_index do |doc, index|
+              doc.parentize(base)
+              doc._index = index
+            end
+          end
+        end
+
+        # Paginate the association. Will create a new criteria, set the documents
+        # on it and execute in an enumerable context.
+        #
+        # @example Paginate the relation.
+        #   person.addresses.paginate(:page => 1, :per_page => 20)
+        #
+        # @param [ Hash ] options The pagination options.
+        #
+        # @option options [ Integer ] :page The page number.
+        # @option options [ Integer ] :per_page The number on each page.
+        #
+        # @return [ WillPaginate::Collection ] The paginated documents.
+        def paginate(options)
+          criteria = Mongoid::Criteria.translate(metadata.klass, true, options)
+          criteria.documents = target
+          criteria.paginate(options)
+        end
+
+        # Substitutes the supplied target documents for the existing documents
+        # in the relation.
+        #
+        # @example Substitute the relation's target.
+        #   person.addresses.substitute([ address ])
+        #
+        # @param [ Array<Document> ] new_target The replacement array.
+        # @param [ true, false ] building Are we in build mode?
+        #
+        # @return [ Many ] The proxied relation.
+        #
+        # @since 2.0.0.rc.1
+        def substitute(new_target, options = {})
+          old_target = target
+          tap do |relation|
+            relation.target = new_target || []
+            if !new_target.blank?
+              unbind(old_target, options)
+              bind(options)
+            else
+              unbind(old_target, options)
+            end
+          end
+        end
+
+        # Get this relation as as its representation in the database.
+        #
+        # @example Convert the relation to an attributes hash.
+        #   person.addresses.to_hash
+        #
+        # @return [ Array<Hash> ] The relation as stored in the db.
+        #
+        # @since 2.0.0.rc.1
+        def to_hash
+          target.inject([]) do |attributes, doc|
+            attributes.tap do |attr|
+              attr << doc.to_hash
+            end
+          end
+        end
+
+        # Unbind the inverse relation from this set of documents. Used when the
+        # entire proxy has been cleared, set to nil or empty, or replaced.
+        #
+        # @example Unbind the relation.
+        #   person.addresses.unbind(target, :continue => false)
+        #
+        # @param [ Array<Document> ] old_target The relations previous target.
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :building Are we in build mode?
+        # @option options [ true, false ] :continue Continue binding the
+        #   inverse?
+        #
+        # @since 2.0.0.rc.1
+        def unbind(old_target, options = {})
+          binding(old_target).unbind(options)
+          if base.persisted?
+            old_target.each do |doc|
+              doc.delete unless doc.destroyed?
+            end
+          end
+        end
+
+        private
+
+        # Appends the document to the target array, updating the index on the
+        # document at the same time.
+        #
+        # @example Append to the document.
+        #   relation.append(document)
+        #
+        # @param [ Document ] document The document to append to the target.
+        #
+        # @since 2.0.0.rc.1
+        def append(document, options = {})
+          target << document
+          metadatafy(document)
+          bind_one(document, options)
+          document._index = target.size - 1
+        end
+
+        # Instantiate the binding associated with this relation.
+        #
+        # @example Create the binding.
+        #   relation.binding([ address ])
+        #
+        # @param [ Array<Document> ] new_target The new documents to bind with.
+        #
+        # @return [ Binding ] The many binding.
+        #
+        # @since 2.0.0.rc.1
+        def binding(new_target = nil)
+          Bindings::Embedded::Many.new(base, new_target || target, metadata)
+        end
+
+        # Returns the criteria object for the target class with its documents set
+        # to target.
+        #
+        # @example Get a criteria for the relation.
+        #   relation.criteria
+        #
+        # @return [ Criteria ] A new criteria.
+        def criteria
+          metadata.klass.criteria(true).tap do |criterion|
+            criterion.documents = target
+          end
+        end
+
+        # If the target array does not respond to the supplied method then try to
+        # find a named scope or criteria on the class and send the call there.
+        #
+        # If the method exists on the array, use the default proxy behavior.
+        #
+        # @param [ Symbol, String ] name The name of the method.
+        # @param [ Array ] args The method args
+        # @param [ Proc ] block Optional block to pass.
+        #
+        # @return [ Criteria, Object ] A Criteria or return value from the target.
+        def method_missing(name, *args, &block)
+          return super if target.respond_to?(name)
+          klass = metadata.klass
+          klass.send(:with_scope, criteria) do
+            klass.send(name, *args)
+          end
+        end
+
+        # Reindex all the target elements. This is useful when performing
+        # operations on the proxied target directly and the indices need to
+        # match that on the database side.
+        #
+        # @example Reindex the relation.
+        #   person.addresses.reindex
+        #
+        # @since 2.0.0.rc.1
+        def reindex
+          target.each_with_index do |doc, index|
+            doc._index = index
+          end
+        end
+
+        # Remove all documents from the relation, either with a delete or a
+        # destroy depending on what this was called through.
+        #
+        # @example Destroy documents from the relation.
+        #   relation.remove_all(:conditions => { :num => 1 }, true)
+        #
+        # @param [ Hash ] conditions Conditions to filter by.
+        # @param [ true, false ] destroy If true then destroy, else delete.
+        #
+        # @return [ Integer ] The number of documents removed.
+        def remove_all(conditions = {}, destroy = false)
+          criteria = find(conditions || {})
+          criteria.size.tap do
+            criteria.each do |doc|
+              target.delete(doc)
+              destroy ? doc.destroy : doc.delete
+            end
+            reindex
+          end
+        end
+
+        class << self
+
+          # Return the builder that is responsible for generating the documents
+          # that will be used by this relation.
+          #
+          # @example Get the builder.
+          #   Embedded::Many.builder(meta, object)
+          #
+          # @param [ Metadata ] meta The metadata of the relation.
+          # @param [ Document, Hash ] object A document or attributes to build
+          #   with.
+          #
+          # @return [ Builder ] A newly instantiated builder object.
+          #
+          # @since 2.0.0.rc.1
+          def builder(meta, object)
+            Builders::Embedded::Many.new(meta, object)
+          end
+
+          # Returns true if the relation is an embedded one. In this case
+          # always true.
+          #
+          # @example Is the relation embedded?
+          #   Embedded::Many.embedded?
+          #
+          # @return [ true ] true.
+          #
+          # @since 2.0.0.rc.1
+          def embedded?
+            true
+          end
+
+          # Returns the macro for this relation. Used mostly as a helper in
+          # reflection.
+          #
+          # @example Get the relation macro.
+          #   Mongoid::Relations::Embedded::Many.macro
+          #
+          # @return [ Symbol ] :embeds_many
+          #
+          # @since 2.0.0.rc.1
+          def macro
+            :embeds_many
+          end
+
+          # Return the nested builder that is responsible for generating the
+          # documents that will be used by this relation.
+          #
+          # @example Get the nested builder.
+          #   NestedAttributes::Many.builder(attributes, options)
+          #
+          # @param [ Metadata ] metadata The relation metadata.
+          # @param [ Hash ] attributes The attributes to build with.
+          # @param [ Hash ] options The builder options.
+          #
+          # @option options [ true, false ] :allow_destroy Can documents be
+          #   deleted?
+          # @option options [ Integer ] :limit Max number of documents to
+          #   create at once.
+          # @option options [ Proc, Symbol ] :reject_if If documents match this
+          #   option then they are ignored.
+          # @option options [ true, false ] :update_only Only existing documents
+          #   can be modified.
+          #
+          # @return [ NestedBuilder ] The nested attributes builder.
+          #
+          # @since 2.0.0.rc.1
+          def nested_builder(metadata, attributes, options)
+            Builders::NestedAttributes::Many.new(metadata, attributes, options)
+          end
+
+          # Tells the caller if this relation is one that stores the foreign
+          # key on its own objects.
+          #
+          # @example Does this relation store a foreign key?
+          #   Embedded::Many.stores_foreign_key?
+          #
+          # @return [ false ] false.
+          #
+          # @since 2.0.0.rc.1
+          def stores_foreign_key?
+            false
+          end
+        end
+      end
+    end
+  end
+end