stonegao-mongoid 2.0.0.rc.6

data/lib/mongoid/relations/referenced/many_to_many.rb

@@ -0,0 +1,344 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Referenced #:nodoc:
+
+      # This class defines the behaviour for all relations that are a
+      # many-to-many between documents in different collections.
+      class ManyToMany < Referenced::Many
+
+        # 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.preferences.create(:text => "Testing")
+        #
+        # @param [ Hash ] attributes The attributes to create with.
+        # @param [ Class ] type The optional type of document to create.
+        #
+        # @return [ Document ] The newly created document.
+        def create(attributes = nil, type = nil)
+          build(attributes, type).tap do |doc|
+            doc.save and base.save if base.persisted?
+          end
+        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.preferences.create!(:text => "Testing")
+        #
+        # @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.
+        def create!(attributes = nil, type = nil)
+          build(attributes, type).tap do |doc|
+            doc.save! and base.save! if base.persisted?
+          end
+        end
+
+        # Delete a single document from the relation.
+        #
+        # @example Delete a document.
+        #   person.preferences.delete(preference)
+        #
+        # @param [ Document ] document The document to delete.
+        #
+        # @since 2.0.0.rc.1
+        def delete(document, options = {})
+          target.delete(document).tap do |doc|
+            binding.unbind_one(doc, default_options.merge!(options)) if doc
+          end
+        end
+
+        # Deletes all related documents from the database given the supplied
+        # conditions.
+        #
+        # @example Delete all documents in the relation.
+        #   person.preferences.delete_all
+        #
+        # @example Conditonally delete all documents in the relation.
+        #   person.preferences.delete_all(:conditions => { :title => "Testing" })
+        #
+        # @param [ Hash ] conditions Optional conditions to delete with.
+        #
+        # @return [ Integer ] The number of documents deleted.
+        def delete_all(conditions = nil)
+          selector = (conditions || {})[:conditions] || {}
+          target.delete_if { |doc| doc.matches?(selector) }
+          scoping = { :_id => { "$in" => base.send(metadata.foreign_key) } }
+          metadata.klass.delete_all(:conditions => selector.merge(scoping))
+        end
+
+        # Destroys all related documents from the database given the supplied
+        # conditions.
+        #
+        # @example Destroy all documents in the relation.
+        #   person.preferences.destroy_all
+        #
+        # @example Conditonally destroy all documents in the relation.
+        #   person.preferences.destroy_all(:conditions => { :title => "Testing" })
+        #
+        # @param [ Hash ] conditions Optional conditions to destroy with.
+        #
+        # @return [ Integer ] The number of documents destroyd.
+        def destroy_all(conditions = nil)
+          selector = (conditions || {})[:conditions] || {}
+          target.delete_if { |doc| doc.matches?(selector) }
+          scoping = { :_id => { "$in" => base.send(metadata.foreign_key) } }
+          metadata.klass.destroy_all(:conditions => selector.merge(scoping))
+        end
+
+        # Find the matchind document on the association, either based on id or
+        # conditions.
+        #
+        # @example Find by an id.
+        #   person.preferences.find(BSON::ObjectId.new)
+        #
+        # @example Find by multiple ids.
+        #   person.preferences.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
+        #
+        # @example Conditionally find all matching documents.
+        #   person.preferences.find(:all, :conditions => { :title => "Sir" })
+        #
+        # @example Conditionally find the first document.
+        #   person.preferences.find(:first, :conditions => { :title => "Sir" })
+        #
+        # @example Conditionally find the last document.
+        #   person.preferences.find(:last, :conditions => { :title => "Sir" })
+        #
+        # @param [ Symbol, BSON::ObjectId, Array<BSON::ObjectId> ] arg The
+        #   argument to search with.
+        # @param [ Hash ] options The options to search with.
+        #
+        # @return [ Document, Criteria ] The matching document(s).
+        def find(arg, options = {})
+          klass = metadata.klass
+          return klass.criteria.id_criteria(arg) unless arg.is_a?(Symbol)
+          selector = (options[:conditions] || {}).merge(
+            "_id" => { "$in" => base.send(metadata.foreign_key) }
+          )
+          klass.find(arg, :conditions => selector)
+        end
+
+        # Removes all associations between the base document and the target
+        # documents by deleting the foreign keys and the references, orphaning
+        # the target documents in the process.
+        #
+        # @example Nullify the relation.
+        #   person.preferences.nullify
+        #
+        # @since 2.0.0.rc.1
+        def nullify
+          load! and target.each do |doc|
+            base.send(metadata.foreign_key).delete(doc.id)
+            dereference(doc)
+          end
+          target.clear
+        end
+        alias :nullify_all :nullify
+
+        # Substitutes the supplied target documents for the existing documents
+        # in the relation. If the new target is nil, perform the necessary
+        # deletion.
+        #
+        # @example Replace the relation.
+        #   person.posts.substitute(new_name)
+        #
+        # @param [ Array<Document> ] target The replacement target.
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :binding Are we in build mode?
+        # @option options [ true, false ] :continue Continue binding the
+        #   inverse?
+        #
+        # @return [ Many ] The relation.
+        #
+        # @since 2.0.0.rc.1
+        def substitute(new_target, options = {})
+          tap do |relation|
+            if new_target
+              binding.unbind(options)
+              relation.target = new_target.to_a
+              bind(options)
+            else
+              relation.target = unbind(options)
+            end
+          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 target.
+        #   person.posts.unbind
+        #
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :binding Are we in build mode?
+        # @option options [ true, false ] :continue Continue binding the
+        #   inverse?
+        #
+        # @since 2.0.0.rc.1
+        def unbind(options = {})
+          target.each(&:delete) if base.persisted?
+          binding.unbind(options)
+          []
+        end
+
+        private
+
+        # Instantiate the binding associated with this relation.
+        #
+        # @example Get the binding.
+        #   relation.binding([ address ])
+        #
+        # @param [ Array<Document> ] new_target The new documents to bind with.
+        #
+        # @return [ Binding ] The binding.
+        #
+        # @since 2.0.0.rc.1
+        def binding(new_target = nil)
+          Bindings::Referenced::ManyToMany.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.any_in(metadata.inverse_foreign_key => [ base.id ])
+        end
+
+        # Dereferences the supplied document from the base of the relation.
+        #
+        # @example Dereference the document.
+        #   person.preferences.dereference(preference)
+        #
+        # @param [ Document ] document The document to dereference.
+        def dereference(document)
+          document.send(metadata.inverse_foreign_key).delete(base.id)
+          document.send(metadata.inverse(document)).target.delete(base)
+          document.save
+        end
+
+        class << self
+
+          # Return the builder that is responsible for generating the documents
+          # that will be used by this relation.
+          #
+          # @example Get the builder.
+          #   Referenced::ManyToMany.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 new builder object.
+          #
+          # @since 2.0.0.rc.1
+          def builder(meta, object)
+            Builders::Referenced::ManyToMany.new(meta, object)
+          end
+
+          # Returns true if the relation is an embedded one. In this case
+          # always false.
+          #
+          # @example Is this relation embedded?
+          #   Referenced::ManyToMany.embedded?
+          #
+          # @return [ false ] Always false.
+          #
+          # @since 2.0.0.rc.1
+          def embedded?
+            false
+          end
+
+          # Get the default value for the foreign key.
+          #
+          # @example Get the default.
+          #   Referenced::ManyToMany.foreign_key_default
+          #
+          # @return [ Array ] Always an empty array.
+          #
+          # @since 2.0.0.rc.1
+          def foreign_key_default
+            []
+          end
+
+          # Returns the suffix of the foreign key field, either "_id" or "_ids".
+          #
+          # @example Get the suffix for the foreign key.
+          #   Referenced::ManyToMany.foreign_key_suffix
+          #
+          # @return [ String ] "_ids"
+          #
+          # @since 2.0.0.rc.1
+          def foreign_key_suffix
+            "_ids"
+          end
+
+          # Returns the macro for this relation. Used mostly as a helper in
+          # reflection.
+          #
+          # @example Get the macro.
+          #   Referenced::ManyToMany.macro
+          #
+          # @return [ Symbol ] :references_and_referenced_in_many
+          def macro
+            :references_and_referenced_in_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.
+          #   Referenced::ManyToMany.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 [ NestedBuilder ] A newly instantiated nested builder object.
+          #
+          # @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?
+          #   Referenced::Many.stores_foreign_key?
+          #
+          # @return [ true ] Always true.
+          #
+          # @since 2.0.0.rc.1
+          def stores_foreign_key?
+            true
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,206 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Referenced #:nodoc:
+
+      # This class defines the behaviour for all relations that are a
+      # one-to-one between documents in different collections.
+      class One < 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.
+        #   person.game.bind(:continue => false)
+        #
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :binding 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.save if base.persisted? && !options[:binding]
+        end
+
+        # Instantiate a new references_one relation. Will set the foreign key
+        # and the base on the inverse object.
+        #
+        # @example Create the new relation.
+        #   Referenced::One.new(base, target, metadata)
+        #
+        # @param [ Document ] base The document this relation hangs off of.
+        # @param [ Document ] target The target (child) of the relation.
+        # @param [ Metadata ] metadata The relation's metadata.
+        def initialize(base, target, metadata)
+          init(base, target, metadata) do
+            characterize_one(target)
+          end
+        end
+
+        # Removes the association between the base document and the target
+        # document by deleting the foreign key and the reference, orphaning
+        # the target document in the process.
+        #
+        # @example Nullify the relation.
+        #   person.game.nullify
+        #
+        # @since 2.0.0.rc.1
+        def nullify
+          target.send(metadata.foreign_key_setter, nil)
+          target.send(:remove_instance_variable, "@#{metadata.inverse(target)}")
+          base.send(:remove_instance_variable, "@#{metadata.name}")
+          target.save
+        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.
+        #   person.game.unbind(name, :continue => true)
+        #
+        # @param [ Document ] old_target The previous target of the relation.
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :binding 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)
+          old_target.delete if base.persisted? && !old_target.destroyed?
+        end
+
+        private
+
+        # Instantiate the binding associated with this relation.
+        #
+        # @example Get the binding.
+        #   relation.binding([ address ])
+        #
+        # @param [ Document ] new_target The new target of the relation.
+        #
+        # @return [ Binding ] The binding object.
+        def binding(new_target = nil)
+          Bindings::Referenced::One.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.
+          #   Referenced::One.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 new builder object.
+          #
+          # @since 2.0.0.rc.1
+          def builder(meta, object)
+            Builders::Referenced::One.new(meta, object)
+          end
+
+          # Returns true if the relation is an embedded one. In this case
+          # always false.
+          #
+          # @example Is this relation embedded?
+          #   Referenced::One.embedded?
+          #
+          # @return [ false ] Always false.
+          #
+          # @since 2.0.0.rc.1
+          def embedded?
+            false
+          end
+
+          # Get the default value for the foreign key.
+          #
+          # @example Get the default.
+          #   Referenced::One.foreign_key_default
+          #
+          # @return [ nil ] Always nil.
+          #
+          # @since 2.0.0.rc.1
+          def foreign_key_default
+            nil
+          end
+
+          # Returns the suffix of the foreign key field, either "_id" or "_ids".
+          #
+          # @example Get the suffix for the foreign key.
+          #   Referenced::One.foreign_key_suffix
+          #
+          # @return [ String ] "_id"
+          #
+          # @since 2.0.0.rc.1
+          def foreign_key_suffix
+            "_id"
+          end
+
+          # Returns the macro for this relation. Used mostly as a helper in
+          # reflection.
+          #
+          # @example Get the macro.
+          #   Referenced::One.macro
+          #
+          # @return [ Symbol ] :references_one.
+          def macro
+            :references_one
+          end
+
+          # Return the nested builder that is responsible for generating the documents
+          # that will be used by this relation.
+          #
+          # @example Get the nested builder.
+          #   Referenced::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 [ NestedBuilder ] 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?
+          #   Referenced::One.stores_foreign_key?
+          #
+          # @return [ false ] Always false.
+          #
+          # @since 2.0.0.rc.1
+          def stores_foreign_key?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/reflections.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+
+    # The reflections module provides convenience methods that can retrieve
+    # useful information about associations.
+    module Reflections
+      extend ActiveSupport::Concern
+
+      included do
+
+        delegate \
+          :reflect_on_association,
+          :reflect_on_all_associations, :to => "self.class"
+      end
+
+      module ClassMethods #:nodoc
+
+        # Returns the relation metadata for the supplied name.
+        #
+        # @example Find relation metadata by name.
+        #   Person.reflect_on_association(:addresses)
+        #
+        # @param [ String, Symbol ] name The name of the relation to find.
+        #
+        # @return [ Metadata ] The matching relation metadata.
+        def reflect_on_association(name)
+          relations[name.to_s]
+        end
+
+        # Returns all relation metadata for the supplied macros.
+        #
+        # @example Find multiple relation metadata by macro.
+        #   Person.reflect_on_all_associations(:embeds_many)
+        #
+        # @param [ Array<String, Symbol> ] *macros The relation macros.
+        #
+        # @return [ Array<Metadata> ] The matching relation metadata.
+        def reflect_on_all_associations(*macros)
+          relations.values.select { |meta| macros.include?(meta.macro) }
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations.rb

@@ -0,0 +1,105 @@
+# encoding: utf-8
+require "mongoid/relations/accessors"
+require "mongoid/relations/auto_save"
+require "mongoid/relations/cascading"
+require "mongoid/relations/constraint"
+require "mongoid/relations/cyclic"
+require "mongoid/relations/proxy"
+require "mongoid/relations/bindings"
+require "mongoid/relations/builders"
+require "mongoid/relations/many"
+require "mongoid/relations/one"
+require "mongoid/relations/polymorphic"
+require "mongoid/relations/embedded/in"
+require "mongoid/relations/embedded/many"
+require "mongoid/relations/embedded/one"
+require "mongoid/relations/referenced/in"
+require "mongoid/relations/referenced/many"
+require "mongoid/relations/referenced/many_to_many"
+require "mongoid/relations/referenced/one"
+require "mongoid/relations/reflections"
+require "mongoid/relations/metadata"
+require "mongoid/relations/macros"
+
+module Mongoid # :nodoc:
+
+  # All classes and modules under the relations namespace handle the
+  # functionality that has to do with embedded and referenced (relational)
+  # associations.
+  module Relations
+    extend ActiveSupport::Concern
+    include Accessors
+    include AutoSave
+    include Cascading
+    include Cyclic
+    include Builders
+    include Macros
+    include Polymorphic
+    include Reflections
+
+    included do
+      attr_accessor :metadata
+    end
+
+    # Determine if the document itself is embedded in another document via the
+    # proper channels. (If it has a parent document.)
+    #
+    # @example Is the document embedded?
+    #   address.embedded?
+    #
+    # @return [ true, false ] True if the document has a parent document.
+    #
+    # @since 2.0.0.rc.1
+    def embedded?
+      _parent.present?
+    end
+
+    # Determine if the document is part of an embeds_many relation.
+    #
+    # @example Is the document in an embeds many?
+    #   address.embedded_many?
+    #
+    # @return [ true, false ] True if in an embeds many.
+    #
+    # @since 2.0.0.rc.1
+    def embedded_many?
+      metadata && metadata.macro == :embeds_many
+    end
+
+    # Determine if the document is part of an embeds_one relation.
+    #
+    # @example Is the document in an embeds one?
+    #   address.embedded_one?
+    #
+    # @return [ true, false ] True if in an embeds one.
+    #
+    # @since 2.0.0.rc.1
+    def embedded_one?
+      metadata && metadata.macro == :embeds_one
+    end
+
+    # Determine if the document is part of an references_many relation.
+    #
+    # @example Is the document in a references many?
+    #   post.referenced_many?
+    #
+    # @return [ true, false ] True if in a references many.
+    #
+    # @since 2.0.0.rc.1
+    def referenced_many?
+      metadata && metadata.macro == :references_many
+    end
+
+    # Determine if the document is part of an references_one relation.
+    #
+    # @example Is the document in a references one?
+    #   address.referenced_one?
+    #
+    # @return [ true, false ] True if in a references one.
+    #
+    # @since 2.0.0.rc.1
+    def referenced_one?
+      metadata && metadata.macro == :references_one
+    end
+  end
+end