mongoid 2.4.10 → 3.0.0

data/lib/mongoid/relations/macros.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
-module Mongoid # :nodoc:
-  module Relations #:nodoc:
+module Mongoid
+  module Relations
 
     # This module contains the core macros for defining relations between
     # documents. They can be either embedded or referenced (relational).
@@ -8,9 +8,11 @@ module Mongoid # :nodoc:
       extend ActiveSupport::Concern
 
       included do
-        class_attribute :embedded, :instance_reader => false
+        class_attribute :embedded, instance_reader: false
+        class_attribute :embedded_relations
         class_attribute :relations
         self.embedded = false
+        self.embedded_relations = {}
         self.relations = {}
       end
 
@@ -26,7 +28,7 @@ module Mongoid # :nodoc:
         self.relations
       end
 
-      module ClassMethods #:nodoc:
+      module ClassMethods
 
         # Adds the relation back to the parent document. This macro is
         # necessary to set the references from the child back to the parent
@@ -49,10 +51,14 @@ module Mongoid # :nodoc:
         # @param [ Hash ] options The relation options.
         # @param [ Proc ] block Optional block for defining extensions.
         def embedded_in(name, options = {}, &block)
-          characterize(name, Embedded::In, options, &block).tap do |meta|
-            self.embedded = true
-            relate(name, meta)
+          if ancestors.include?(Mongoid::Versioning)
+            raise Errors::VersioningNotOnRoot.new(self)
           end
+          meta = characterize(name, Embedded::In, options, &block)
+          self.embedded = true
+          relate(name, meta)
+          builder(name, meta).creator(name, meta)
+          meta
         end
 
         # Adds the relation from a parent document to its children. The name
@@ -75,11 +81,12 @@ module Mongoid # :nodoc:
         # @param [ Hash ] options The relation options.
         # @param [ Proc ] block Optional block for defining extensions.
         def embeds_many(name, options = {}, &block)
-          characterize(name, Embedded::Many, options, &block).tap do |meta|
-            self.cyclic = true if options[:cyclic]
-            relate(name, meta)
-            validates_relation(meta)
-          end
+          meta = characterize(name, Embedded::Many, options, &block)
+          self.cyclic = true if options[:cyclic]
+          relate(name, meta)
+          embed(name, meta)
+          validates_relation(meta)
+          meta
         end
 
         # Adds the relation from a parent document to its child. The name
@@ -102,12 +109,13 @@ module Mongoid # :nodoc:
         # @param [ Hash ] options The relation options.
         # @param [ Proc ] block Optional block for defining extensions.
         def embeds_one(name, options = {}, &block)
-          characterize(name, Embedded::One, options, &block).tap do |meta|
-            self.cyclic = true if options[:cyclic]
-            relate(name, meta)
-            builder(name, meta).creator(name, meta)
-            validates_relation(meta)
-          end
+          meta = characterize(name, Embedded::One, options, &block)
+          self.cyclic = true if options[:cyclic]
+          relate(name, meta)
+          embed(name, meta)
+          builder(name, meta).creator(name, meta)
+          validates_relation(meta)
+          meta
         end
 
         # Adds a relational association from the child Document to a Document in
@@ -129,15 +137,11 @@ module Mongoid # :nodoc:
         # @param [ Hash ] options The relation options.
         # @param [ Proc ] block Optional block for defining extensions.
         def belongs_to(name, options = {}, &block)
-          characterize(name, Referenced::In, options, &block).tap do |meta|
-            relate(name, meta)
-            reference(meta)
-            autosave(meta)
-            validates_relation(meta)
-          end
+          meta = reference_one_to_one(name, options, Referenced::In, &block)
+          aliased_fields[name.to_s] = meta.foreign_key
+          touchable(meta)
+          meta
         end
-        alias :belongs_to_related :belongs_to
-        alias :referenced_in :belongs_to
 
         # Adds a relational association from a parent Document to many
         # Documents in another database or collection.
@@ -158,15 +162,14 @@ module Mongoid # :nodoc:
         # @param [ Hash ] options The relation options.
         # @param [ Proc ] block Optional block for defining extensions.
         def has_many(name, options = {}, &block)
-          characterize(name, Referenced::Many, options, &block).tap do |meta|
-            relate(name, meta)
-            reference(meta)
-            autosave(meta)
-            validates_relation(meta)
-          end
+          meta = characterize(name, Referenced::Many, options, &block)
+          relate(name, meta)
+          ids_getter(name, meta).ids_setter(name, meta)
+          reference(meta)
+          autosave(meta)
+          validates_relation(meta)
+          meta
         end
-        alias :has_many_related :has_many
-        alias :references_many :has_many
 
         # Adds a relational many-to-many association between many of this
         # Document and many of another Document.
@@ -189,15 +192,14 @@ module Mongoid # :nodoc:
         #
         # @since 2.0.0.rc.1
         def has_and_belongs_to_many(name, options = {}, &block)
-          characterize(name, Referenced::ManyToMany, options, &block).tap do |meta|
-            relate(name, meta)
-            reference(meta, Array)
-            autosave(meta)
-            validates_relation(meta)
-            synced(meta)
-          end
+          meta = characterize(name, Referenced::ManyToMany, options, &block)
+          relate(name, meta)
+          reference(meta, Array)
+          autosave(meta)
+          validates_relation(meta)
+          synced(meta)
+          meta
         end
-        alias :references_and_referenced_in_many :has_and_belongs_to_many
 
         # Adds a relational association from the child Document to a Document in
         # another database or collection.
@@ -218,20 +220,15 @@ module Mongoid # :nodoc:
         # @param [ Hash ] options The relation options.
         # @param [ Proc ] block Optional block for defining extensions.
         def has_one(name, options = {}, &block)
-          characterize(name, Referenced::One, options, &block).tap do |meta|
-            relate(name, meta)
-            reference(meta)
-            builder(name, meta).creator(name, meta).autosave(meta)
-            validates_relation(meta)
-          end
+          reference_one_to_one(name, options, Referenced::One, &block)
         end
-        alias :has_one_related :has_one
-        alias :references_one :has_one
 
         private
 
         # Create the metadata for the relation.
         #
+        # @api private
+        #
         # @example Create the metadata.
         #   Person.characterize(:posts, Referenced::Many, {})
         #
@@ -243,15 +240,17 @@ module Mongoid # :nodoc:
         # @return [ Metadata ] The metadata for the relation.
         def characterize(name, relation, options, &block)
           Metadata.new({
-            :relation => relation,
-            :extend => create_extension_module(name, &block),
-            :inverse_class_name => self.name,
-            :name => name
+            relation: relation,
+            extend: create_extension_module(name, &block),
+            inverse_class_name: self.name,
+            name: name
           }.merge(options))
         end
 
         # Generate a named extension module suitable for marshaling
         #
+        # @api private
+        #
         # @example Get the module.
         #   Person.create_extension_module(:posts, &block)
         #
@@ -272,9 +271,27 @@ module Mongoid # :nodoc:
           end
         end
 
+        # Add an embedded relation metadata to the embedded relations.
+        #
+        # @api private
+        #
+        # @example Add the metadata to embedded relations.
+        #   Person.embed("addresses", metadata)
+        #
+        # @param [ String ] name The name of the relation.
+        # @param [ Metadata ] metadata The relation metadata.
+        #
+        # @since 3.0.0
+        def embed(name, metadata)
+          self.embedded_relations =
+            embedded_relations.merge(name.to_s => metadata)
+        end
+
         # Defines a field to be used as a foreign key in the relation and
         # indexes it if defined.
         #
+        # @api private
+        #
         # @example Set up the relational fields and indexes.
         #   Person.reference(metadata)
         #
@@ -285,15 +302,43 @@ module Mongoid # :nodoc:
             key = metadata.foreign_key
             field(
               key,
-              :type => type,
-              :identity => true,
-              :metadata => metadata,
-              :default => metadata.foreign_key_default
+              type: type,
+              identity: true,
+              metadata: metadata,
+              default: metadata.foreign_key_default
             )
-            index(key, :background => true) if metadata.indexed?
+            if metadata.indexed?
+              if metadata.polymorphic?
+                index({ key => 1, metadata.type => 1 }, { background: true })
+              else
+                index({ key => 1 }, { background: true })
+              end
+            end
           end
         end
 
+        # Handle common behaviour for referenced 1-1 relation setup.
+        #
+        # @api private
+        #
+        # @example Add the one to one behaviour.
+        #   Model.reference_one_to_one(:name, meta)
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Metadata ] meta The relation metadata.
+        #
+        # @return [ Class ] The model class.
+        #
+        # @since 3.0.0
+        def reference_one_to_one(name, options, relation, &block)
+          meta = characterize(name, relation, options, &block)
+          relate(name, meta)
+          reference(meta)
+          builder(name, meta).creator(name, meta).autosave(meta)
+          validates_relation(meta)
+          meta
+        end
+
         # Creates a relation for the given name, metadata and relation. It adds
         # the metadata to the relations hash and has the accessors set up.
         #
@@ -304,7 +349,7 @@ module Mongoid # :nodoc:
         # @param [ Metadata ] metadata The metadata for the relation.
         def relate(name, metadata)
           self.relations = relations.merge(name.to_s => metadata)
-          getter(name, metadata).setter(name, metadata)
+          getter(name, metadata).setter(name, metadata).existence_check(name, metadata)
         end
       end
     end

data/lib/mongoid/relations/many.rb

@@ -1,13 +1,13 @@
 # encoding: utf-8
-module Mongoid #:nodoc:
-  module Relations #:nodoc:
+module Mongoid
+  module Relations
 
     # This is the superclass for all many to one and many to many relation
     # proxies.
     class Many < Proxy
 
-      delegate :avg, :max, :min, :sum, :to => :criteria
-      delegate :length, :size, :to => :target
+      delegate :avg, :max, :min, :sum, to: :criteria
+      delegate :length, :size, to: :target
 
       # Is the relation empty?
       #
@@ -21,6 +21,57 @@ module Mongoid #:nodoc:
         size == 0
       end
 
+        # Creates a new document on the references many relation. This will
+        # save the document if the parent has been persisted.
+        #
+        # @example Create and save the new document.
+        #   person.posts.create(:text => "Testing")
+      #
+      # @overload create(attributes = nil, options = {}, type = nil)
+      #   @param [ Hash ] attributes The attributes to create with.
+      #   @param [ Hash ] options The scoped assignment options.
+      #   @param [ Class ] type The optional type of document to create.
+      #
+      # @overload create(attributes = nil, type = nil)
+      #   @param [ Hash ] attributes The attributes to create with.
+      #   @param [ Class ] type The optional type of document to create.
+      #
+      # @return [ Document ] The newly created document.
+      #
+      # @since 2.0.0.beta.1
+      def create(attributes = nil, options = {}, type = nil, &block)
+        doc = build(attributes, options, type, &block)
+        base.persisted? ? doc.save : raise_unsaved(doc)
+        doc
+      end
+
+      # 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.
+      #
+      # @example Create and save the new document.
+      #   person.posts.create!(:text => "Testing")
+      #
+      # @overload create!(attributes = nil, options = {}, type = nil)
+      #   @param [ Hash ] attributes The attributes to create with.
+      #   @param [ Hash ] options The scoped assignment options.
+      #   @param [ Class ] type The optional type of document to create.
+      #
+      # @overload create!(attributes = nil, type = nil)
+      #   @param [ Hash ] attributes The attributes to create with.
+      #   @param [ Class ] type The optional type of document to create.
+      #
+      # @raise [ Errors::Validations ] If validation failed.
+      #
+      # @return [ Document ] The newly created document.
+      #
+      # @since 2.0.0.beta.1
+      def create!(attributes = nil, options = {}, type = nil, &block)
+        doc = build(attributes, options, type, &block)
+        base.persisted? ? doc.save! : raise_unsaved(doc)
+        doc
+      end
+
       # Determine if any documents in this relation exist in the database.
       #
       # @example Are there persisted documents?
@@ -37,11 +88,18 @@ module Mongoid #:nodoc:
       # @example Find or create.
       #   person.posts.find_or_create_by(:title => "Testing")
       #
-      # @param [ Hash ] attrs The attributes to search or create with.
+      # @overload find_or_create_by(attributes = nil, options = {}, type = nil)
+      #   @param [ Hash ] attributes The attributes to search or create with.
+      #   @param [ Hash ] options The scoped assignment options.
+      #   @param [ Class ] type The optional type of document to create.
+      #
+      # @overload find_or_create_by(attributes = nil, type = nil)
+      #   @param [ Hash ] attributes The attributes to search or create with.
+      #   @param [ Class ] type The optional type of document to create.
       #
       # @return [ Document ] An existing document or newly created one.
-      def find_or_create_by(attrs = {}, &block)
-        find_or(:create, attrs, &block)
+      def find_or_create_by(attrs = {}, options = {}, type = nil, &block)
+        find_or(:create, attrs, options, type, &block)
       end
 
       # Find the first +Document+ given the conditions, or instantiates a new document
@@ -50,11 +108,18 @@ module Mongoid #:nodoc:
       # @example Find or initialize.
       #   person.posts.find_or_initialize_by(:title => "Test")
       #
-      # @param [ Hash ] attrs The attributes to search or initialize with.
+      # @overload find_or_initialize_by(attributes = {}, options = {}, type = nil)
+      #   @param [ Hash ] attributes The attributes to search or initialize with.
+      #   @param [ Hash ] options The scoped assignment options.
+      #   @param [ Class ] type The optional subclass to build.
+      #
+      # @overload find_or_initialize_by(attributes = {}, type = nil)
+      #   @param [ Hash ] attributes The attributes to search or initialize with.
+      #   @param [ Class ] type The optional subclass to build.
       #
       # @return [ Document ] An existing document or newly instantiated one.
-      def find_or_initialize_by(attrs = {}, &block)
-        find_or(:build, attrs, &block)
+      def find_or_initialize_by(attrs = {}, options = {}, type = nil, &block)
+        find_or(:build, attrs, options, type, &block)
       end
 
       # This proxy can never be nil.
@@ -136,12 +201,26 @@ module Mongoid #:nodoc:
       # @example Find or create|initialize.
       #   person.addresses.find_or(:create, :street => "Bond")
       #
-      # @param [ Symbol ] method The method name, create or new.
-      # @param [ Hash ] attrs The attributes to build with.
+      # @overload find_or(method, attributes = {}, options = {}, type = nil)
+      #   @param [ Symbol ] method The method name, create or new.
+      #   @param [ Hash ] attributes The attributes to search or build with.
+      #   @param [ Hash ] options The scoped assignment options.
+      #   @param [ Class ] type The optional subclass to build.
+      #
+      # @overload find_or(attributes = {}, type = nil)
+      #   @param [ Symbol ] method The method name, create or new.
+      #   @param [ Hash ] attributes The attributes to search or build with.
+      #   @param [ Class ] type The optional subclass to build.
       #
       # @return [ Document ] A matching document or a new/created one.
-      def find_or(method, attrs = {}, &block)
-        find(:first, :conditions => attrs) || send(method, attrs, &block)
+      def find_or(method, attrs = {}, options = {}, type = nil, &block)
+        if options.is_a? Class
+          options, type = {}, options
+        end
+
+        attrs["_type"] = type.to_s if type
+
+        where(attrs).first || send(method, attrs, options, type, &block)
       end
     end
   end