mongoid_heroku_stable 4.0.0

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

@@ -0,0 +1,223 @@
+# encoding: utf-8
+module Mongoid
+  module Relations
+    module Embedded
+
+      # This class defines the behaviour needed for embedded one to one
+      # relations.
+      class One < Relations::One
+
+        # Instantiate a new embeds_one relation.
+        #
+        # @example Create the new proxy.
+        #   One.new(person, name, metadata)
+        #
+        # @param [ Document ] base The document this relation hangs off of.
+        # @param [ Document ] target The child document in the relation.
+        # @param [ Metadata ] metadata The relation's metadata
+        def initialize(base, target, metadata)
+          init(base, target, metadata) do
+            characterize_one(target)
+            bind_one
+            characterize_one(target)
+            target.save if persistable?
+          end
+        end
+
+        # Substitutes the supplied target documents for the existing document
+        # in the relation.
+        #
+        # @example Substitute the new document.
+        #   person.name.substitute(new_name)
+        #
+        # @param [ Document ] other A document to replace the target.
+        #
+        # @return [ Document, nil ] The relation or nil.
+        #
+        # @since 2.0.0.rc.1
+        def substitute(replacement)
+          if replacement != self
+            if _assigning?
+              base.add_atomic_unset(target) unless replacement
+            else
+              target.destroy if persistable?
+            end
+            unbind_one
+            return nil unless replacement
+            replacement = Factory.build(klass, replacement) if replacement.is_a?(::Hash)
+            self.target = replacement
+            bind_one
+            characterize_one(target)
+            target.save if persistable? && !_assigning?
+          end
+          self
+        end
+
+        private
+
+        # Instantiate the binding associated with this relation.
+        #
+        # @example Get the binding.
+        #   relation.binding([ address ])
+        #
+        # @param [ Document ] new_target The new document to bind with.
+        #
+        # @return [ Binding ] The relation's binding.
+        #
+        # @since 2.0.0.rc.1
+        def binding
+          Bindings::Embedded::One.new(base, target, metadata)
+        end
+
+        # Are we able to persist this relation?
+        #
+        # @example Can we persist the relation?
+        #   relation.persistable?
+        #
+        # @return [ true, false ] If the relation is persistable.
+        #
+        # @since 2.1.0
+        def persistable?
+          base.persisted? && !_binding? && !_building? && !_assigning?
+        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::One.builder(meta, object, person)
+          #
+          # @param [ Document ] base The base document.
+          # @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(base, meta, object)
+            Builders::Embedded::One.new(base, meta, object)
+          end
+
+          # Returns true if the relation is an embedded one. In this case
+          # always true.
+          #
+          # @example Is this relation embedded?
+          #   Embedded::One.embedded?
+          #
+          # @return [ true ] true.
+          #
+          # @since 2.0.0.rc.1
+          def embedded?
+            true
+          end
+
+          # Returns the suffix of the foreign key field, either "_id" or "_ids".
+          #
+          # @example Get the suffix for the foreign key.
+          #   Referenced::Many.foreign_key_suffix
+          #
+          # @return [ nil ] nil.
+          #
+          # @since 3.0.0
+          def foreign_key_suffix
+            nil
+          end
+
+          # Returns the macro for this relation. Used mostly as a helper in
+          # reflection.
+          #
+          # @example Get the macro.
+          #   Mongoid::Relations::Embedded::One.macro
+          #
+          # @return [ Symbol ] :embeds_one.
+          #
+          # @since 2.0.0.rc.1
+          def macro
+            :embeds_one
+          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
+
+          # Get the path calculator for the supplied document.
+          #
+          # @example Get the path calculator.
+          #   Proxy.path(document)
+          #
+          # @param [ Document ] document The document to calculate on.
+          #
+          # @return [ Mongoid::Atomic::Paths::Embedded::One ]
+          #   The embedded one atomic path calculator.
+          #
+          # @since 2.1.0
+          def path(document)
+            Mongoid::Atomic::Paths::Embedded::One.new(document)
+          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::One.stores_foreign_key?
+          #
+          # @return [ false ] false.
+          #
+          # @since 2.0.0.rc.1
+          def stores_foreign_key?
+            false
+          end
+
+          # Get the valid options allowed with this relation.
+          #
+          # @example Get the valid options.
+          #   Relation.valid_options
+          #
+          # @return [ Array<Symbol> ] The valid options.
+          #
+          # @since 2.1.0
+          def valid_options
+            [ :autobuild, :as, :cascade_callbacks, :cyclic, :store_as ]
+          end
+
+          # Get the default validation setting for the relation. Determines if
+          # by default a validates associated will occur.
+          #
+          # @example Get the validation default.
+          #   Proxy.validation_default
+          #
+          # @return [ true, false ] The validation default.
+          #
+          # @since 2.1.9
+          def validation_default
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/macros.rb

@@ -0,0 +1,356 @@
+# encoding: utf-8
+module Mongoid
+  module Relations
+
+    # This module contains the core macros for defining relations between
+    # documents. They can be either embedded or referenced (relational).
+    module Macros
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :embedded, instance_reader: false
+        class_attribute :embedded_relations
+        class_attribute :relations
+        self.embedded = false
+        self.embedded_relations = {}
+        self.relations = {}
+      end
+
+      # This is convenience for librarys still on the old API.
+      #
+      # @example Get the associations.
+      #   person.associations
+      #
+      # @return [ Hash ] The relations.
+      #
+      # @since 2.3.1
+      def associations
+        self.relations
+      end
+
+      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
+        # document. If a child does not define this relation calling
+        # persistence methods on the child object will cause a save to fail.
+        #
+        # @example Define the relation.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     embeds_many :addresses
+        #   end
+        #
+        #   class Address
+        #     include Mongoid::Document
+        #     embedded_in :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def embedded_in(name, options = {}, &block)
+          meta = characterize(name, Embedded::In, options, &block)
+          self.embedded = true
+          relate(name, meta)
+          builder(name, meta).creator(name, meta)
+          add_counter_cache_callbacks(meta) if meta.counter_cached?
+          meta
+        end
+
+        # Adds the relation from a parent document to its children. The name
+        # of the relation needs to be a pluralized form of the child class
+        # name.
+        #
+        # @example Define the relation.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     embeds_many :addresses
+        #   end
+        #
+        #   class Address
+        #     include Mongoid::Document
+        #     embedded_in :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def embeds_many(name, options = {}, &block)
+          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
+        # of the relation needs to be a singular form of the child class
+        # name.
+        #
+        # @example Define the relation.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     embeds_one :name
+        #   end
+        #
+        #   class Name
+        #     include Mongoid::Document
+        #     embedded_in :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def embeds_one(name, options = {}, &block)
+          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
+        # another database or collection.
+        #
+        # @example Define the relation.
+        #
+        #   class Game
+        #     include Mongoid::Document
+        #     belongs_to :person
+        #   end
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     has_one :game
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def belongs_to(name, options = {}, &block)
+          meta = reference_one_to_one(name, options, Referenced::In, &block)
+          aliased_fields[name.to_s] = meta.foreign_key
+          touchable(meta)
+          add_counter_cache_callbacks(meta) if meta.counter_cached?
+          meta
+        end
+
+        # Adds a relational association from a parent Document to many
+        # Documents in another database or collection.
+        #
+        # @example Define the relation.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     has_many :posts
+        #   end
+        #
+        #   class Game
+        #     include Mongoid::Document
+        #     belongs_to :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def has_many(name, options = {}, &block)
+          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
+
+        # Adds a relational many-to-many association between many of this
+        # Document and many of another Document.
+        #
+        # @example Define the relation.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     has_and_belongs_to_many :preferences
+        #   end
+        #
+        #   class Preference
+        #     include Mongoid::Document
+        #     has_and_belongs_to_many :people
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        #
+        # @since 2.0.0.rc.1
+        def has_and_belongs_to_many(name, options = {}, &block)
+          meta = characterize(name, Referenced::ManyToMany, options, &block)
+          relate(name, meta)
+          reference(meta, Array)
+          autosave(meta)
+          validates_relation(meta)
+          synced(meta)
+          meta
+        end
+
+        # Adds a relational association from the child Document to a Document in
+        # another database or collection.
+        #
+        # @example Define the relation.
+        #
+        #   class Game
+        #     include Mongoid::Document
+        #     belongs_to :person
+        #   end
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     has_one :game
+        #   end
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def has_one(name, options = {}, &block)
+          reference_one_to_one(name, options, Referenced::One, &block)
+        end
+
+        private
+
+        # Create the metadata for the relation.
+        #
+        # @api private
+        #
+        # @example Create the metadata.
+        #   Person.characterize(:posts, Referenced::Many, {})
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Object ] relation The type of relation.
+        # @param [ Hash ] options The relation options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        #
+        # @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
+          }.merge(options))
+        end
+
+        # Generate a named extension module suitable for marshaling
+        #
+        # @api private
+        #
+        # @example Get the module.
+        #   Person.create_extension_module(:posts, &block)
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @param [ Proc ] block Optional block for defining extensions.
+        #
+        # @return [ Module, nil ] The extension or nil.
+        #
+        # @since 2.1.0
+        def create_extension_module(name, &block)
+          if block
+            extension_module_name =
+              "#{self.to_s.demodulize}#{name.to_s.camelize}RelationExtension"
+            silence_warnings do
+              self.const_set(extension_module_name, Module.new(&block))
+            end
+            "#{self}::#{extension_module_name}".constantize
+          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)
+          aliased_fields[name.to_s] = metadata.store_as if metadata.store_as
+        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)
+        #
+        # @param [ Metadata ] metadata The metadata for the relation.
+        def reference(metadata, type = Object)
+          polymorph(metadata).cascade(metadata)
+          if metadata.relation.stores_foreign_key?
+            key = metadata.foreign_key
+            field(
+              key,
+              type: type,
+              identity: true,
+              metadata: metadata,
+              default: metadata.foreign_key_default
+            )
+            if metadata.indexed?
+              if metadata.polymorphic?
+                index({ key => 1, metadata.inverse_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.
+        #
+        # @example Set up the relation and accessors.
+        #   Person.relate(:addresses, Metadata)
+        #
+        # @param [ Symbol ] name The name of the relation.
+        # @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).existence_check(name, metadata)
+        end
+      end
+    end
+  end
+end