mongoid 2.4.9 → 3.0.0.rc

data/lib/mongoid/relations/metadata.rb

@@ -1,12 +1,12 @@
 # encoding: utf-8
-module Mongoid # :nodoc:
-  module Relations #:nodoc:
+module Mongoid
+  module Relations
 
     # The "Grand Poobah" of information about any relation is this class. It
     # contains everything you could ever possible want to know.
     class Metadata < Hash
 
-      delegate :foreign_key_default, :stores_foreign_key?, :to => :relation
+      delegate :foreign_key_default, :stores_foreign_key?, to: :relation
 
       # Returns the as option of the relation.
       #
@@ -32,6 +32,19 @@ module Mongoid # :nodoc:
         !!as
       end
 
+      # Is the relation autobuilding if accessed via the getter and the
+      # document is new.
+      #
+      # @example Is the relation autobuilding?
+      #   metadata.autobuilding?
+      #
+      # @return [ true, false ] If the relation autobuilds.
+      #
+      # @since 3.0.0
+      def autobuilding?
+        !!self[:autobuild]
+      end
+
       # Returns the autosave option of the relation.
       #
       # @example Get the autosave option.
@@ -82,11 +95,7 @@ module Mongoid # :nodoc:
       # @since 2.0.0.rc.1
       def cascade_strategy
         if dependent?
-          strategy =
-            %{Mongoid::Relations::Cascading::#{dependent.to_s.classify}}
-          strategy.constantize
-        else
-          return nil
+          "Mongoid::Relations::Cascading::#{dependent.to_s.classify}".constantize
         end
       end
 
@@ -135,11 +144,12 @@ module Mongoid # :nodoc:
       #   metadata.criteria([ id_one, id_two ])
       #
       # @param [ Object ] object The foreign key used for the query.
+      # @param [ Class ] type The base class.
       #
       # @return [ Criteria ] The criteria.
       #
       # @since 2.1.0
-      def criteria(object, type = nil)
+      def criteria(object, type)
         query = relation.criteria(self, object, type)
         order ? query.order_by(order) : query
       end
@@ -348,19 +358,40 @@ module Mongoid # :nodoc:
       #
       # @since 2.0.0.rc.1
       def inspect
-        "#<Mongoid::Relations::Metadata\n" <<
-        "  class_name:           #{class_name},\n" <<
-        "  cyclic:               #{cyclic || "No"},\n" <<
-        "  dependent:            #{dependent || "None"},\n" <<
-        "  inverse_of:           #{inverse_of || "N/A"},\n" <<
-        "  key:                  #{key},\n" <<
-        "  macro:                #{macro},\n" <<
-        "  name:                 #{name},\n" <<
-        "  order:                #{order.inspect || "No"},\n" <<
-        "  polymorphic:          #{polymorphic? || "No"},\n" <<
-        "  relation:             #{relation},\n" <<
-        "  setter:               #{setter},\n" <<
-        "  versioned:            #{versioned? || "No"}>\n"
+        ::I18n.translate(
+          "mongoid.inspection.metadata",
+          {
+            autobuild: autobuilding?,
+            class_name: class_name,
+            cyclic: cyclic.inspect,
+            dependent: dependent.inspect,
+            inverse_of: inverse_of.inspect,
+            key: key,
+            locale: :en,
+            macro: macro,
+            name: name,
+            order: order.inspect,
+            polymorphic: polymorphic?,
+            relation: relation,
+            setter: setter,
+            versioned: versioned?
+          }
+        )
+      end
+
+      # Get the name of the inverse relations if they exists. If this is a
+      # polymorphic relation then just return the :as option that was defined.
+      #
+      # @example Get the names of the inverses.
+      #   metadata.inverses
+      #
+      # @param [ Document ] other The document to aid in the discovery.
+      #
+      # @return [ Array<Symbol> ] The inverse name.
+      def inverses(other = nil)
+        return [self[:inverse_of]] if has_key?(:inverse_of)
+        return self[:as] ? [self[:as]] : lookup_inverses(other) if polymorphic?
+        @inverse ||= [(cyclic? ? cyclic_inverse : inverse_relation)]
       end
 
       # Get the name of the inverse relation if it exists. If this is a
@@ -375,9 +406,8 @@ module Mongoid # :nodoc:
       #
       # @since 2.0.0.rc.1
       def inverse(other = nil)
-        return self[:inverse_of] if has_key?(:inverse_of)
-        return self[:as] || lookup_inverse(other) if polymorphic?
-        @inverse ||= (cyclic? ? cyclic_inverse : inverse_relation)
+        invs = inverses(other)
+        invs.first if invs.count == 1
       end
 
       # Returns the inverse_class_name option of the relation.
@@ -479,7 +509,8 @@ module Mongoid # :nodoc:
       #
       # @since 2.0.0.rc.1
       def inverse_setter(other = nil)
-        "#{inverse(other)}="
+        inv = inverse(other)
+        inv ? "#{inv}=" : nil
       end
 
       # Returns the name of the field in which to store the name of the class
@@ -492,8 +523,7 @@ module Mongoid # :nodoc:
       #
       # @since 2.0.0.rc.1
       def inverse_type
-        @inverse_type ||=
-          relation.stores_foreign_key? && polymorphic? ? "#{name}_type" : nil
+        @inverse_type ||= determine_inverse_for(:type)
       end
 
       # Gets the setter for the field that sets the type of document on a
@@ -509,6 +539,31 @@ module Mongoid # :nodoc:
         @inverse_type_setter ||= inverse_type ? "#{inverse_type}=" : nil
       end
 
+      # Returns the name of the field in which to store the name of the inverse
+      # field for the polymorphic relation.
+      #
+      # @example Get the name of the field.
+      #   metadata.inverse_of_field
+      #
+      # @return [ String ] The name of the field for storing the name of the
+      #   inverse field.
+      #
+      # @since 2.4.5
+      def inverse_of_field
+        @inverse_of_field ||= determine_inverse_for(:field)
+      end
+
+      # Gets the setter for the field that stores the name of the inverse field
+      # on a polymorphic relation.
+      #
+      # @example Get the inverse type setter.
+      #   metadata.inverse_of_field_setter
+      #
+      # @return [ String ] The name of the setter.
+      def inverse_of_field_setter
+        @inverse_of_field_setter ||= inverse_of_field ? "#{inverse_of_field}=" : nil
+      end
+
       # This returns the key that is to be used to grab the attributes for the
       # relation or the foreign key or id that a referenced relation will use
       # to query for the object.
@@ -689,6 +744,17 @@ module Mongoid # :nodoc:
         @type_setter ||= type ? "#{type}=" : nil
       end
 
+
+      # Key where embedded document is save.
+      # By default is the name of relation
+      #
+      # @return [ String ] the name of key where save
+      #
+      # @since 3.0.0
+      def store_as
+        @store_as ||= (self[:store_as].try(:to_s) || name.to_s)
+      end
+
       # Are we validating this relation automatically?
       #
       # @example Is automatic validation on?
@@ -754,6 +820,18 @@ module Mongoid # :nodoc:
         !!order
       end
 
+      # Is this relation touchable?
+      #
+      # @example Is the relation touchable?
+      #   metadata.touchable?
+      #
+      # @return [ true, false ] If the relation can be touched.
+      #
+      # @since 3.0.0
+      def touchable?
+        !!self[:touch]
+      end
+
       private
 
       # Returns the class name for the relation.
@@ -761,11 +839,67 @@ module Mongoid # :nodoc:
       # @example Get the class name.
       #   metadata.classify
       #
-      # @return [ String ] If embedded_in, the camelized, else classified.
+      # @return [ String ] The classified name.
       #
       # @since 2.0.0.rc.1
       def classify
-        macro == :embedded_in ? name.to_s.camelize : name.to_s.classify
+        @classify ||= "#{find_module}::#{name.to_s.classify}"
+      end
+
+      # Get the name for the inverse field.
+      #
+      # @api private
+      #
+      # @example Get the inverse field name.
+      #   metadata.determine_inverse_for(:type)
+      #
+      # @param [ Symbol ] field The inverse field name.
+      #
+      # @return [ String ] The name of the field.
+      #
+      # @since 3.0.0
+      def determine_inverse_for(field)
+        relation.stores_foreign_key? && polymorphic? ? "#{name}_#{field}" : nil
+      end
+
+      # Find the module the class with the specific name is in.
+      # This is done by starting at the inverse_class_name's
+      # module and stepping down to see where it is defined.
+      #
+      # @api private
+      #
+      # @example Find the module.
+      #   metadata.find_module
+      #
+      # @return [ String ] The module.
+      #
+      # @since 3.0.0
+      def find_module
+        if inverse_class_name.present?
+          parts = inverse_class_name.split('::')
+          modules = parts.size.times.map { |i| parts.first(i).join('::') }.reverse
+          find_from_parts(modules)
+        end
+      end
+
+      # Find the modules from a reversed list.
+      #
+      # @api private
+      #
+      # @example Find the module from the parts.
+      #   metadata.find_from_parts([ "Namespace", "Module" ])
+      #
+      # @param [ Array<String> ] The modules.
+      #
+      # @return [ String ] The matching module.
+      #
+      # @since 3.0.0
+      def find_from_parts(modules)
+        modules.find do |mod|
+          ActiveSupport::Inflector.constantize(mod).constants.include?(
+            name.to_s.classify.to_sym
+          )
+        end
       end
 
       # Get the name of the inverse relation in a cyclic relation.
@@ -820,11 +954,7 @@ module Mongoid # :nodoc:
         return self[:foreign_key].to_s if self[:foreign_key]
         suffix = relation.foreign_key_suffix
         if relation.stores_foreign_key?
-          if relation.macro == :references_and_referenced_in_many
-            "#{name.to_s.singularize}#{suffix}"
-          else
-            "#{name}#{suffix}"
-          end
+          relation.foreign_key(name)
         else
           if polymorphic?
             "#{self[:as]}#{suffix}"
@@ -861,15 +991,55 @@ module Mongoid # :nodoc:
       #
       # @since 2.0.0.rc.1
       def determine_inverse_relation
-        default = klass.relations[inverse_klass.name.underscore]
+        default = foreign_key_match || klass.relations[inverse_klass.name.underscore]
         return default.name if default
-        klass.relations.each_pair do |key, meta|
-          next if meta.versioned? || meta.name == name
-          if meta.class_name == inverse_class_name
-            return key.to_sym
+        candidates = inverse_relation_candidates
+
+        if candidates.size > 1
+          raise Errors::AmbiguousRelationship.new(
+            klass,
+            inverse_klass,
+            name,
+            candidates
+          )
+        end
+        candidates.first
+      end
+
+      # Return metadata where the foreign key matches the foreign key on this
+      # relation.
+      #
+      # @api private
+      #
+      # @example Return a foreign key match.
+      #   meta.foreign_key_match
+      #
+      # @return [ Metadata ] A match, if any.
+      #
+      # @since 2.4.11
+      def foreign_key_match
+        if fk = self[:foreign_key]
+          klass.relations.values.detect do |meta|
+            fk == meta.foreign_key if meta.stores_foreign_key?
           end
         end
-        return nil
+      end
+
+      # Get the candidates for inverse relations.
+      #
+      # @api private
+      #
+      # @example Get the candidates.
+      #   metadata.inverse_relation_candidates
+      #
+      # @return [ Array<Symbol> ] The candidates.
+      #
+      # @since 3.0.0
+      def inverse_relation_candidates
+        klass.relations.select do |_, meta|
+          next if meta.versioned? || meta.name == name
+          meta.class_name == inverse_class_name
+        end.keys.map(&:to_sym)
       end
 
       # Determine the key for the relation in the attributes.
@@ -881,7 +1051,7 @@ module Mongoid # :nodoc:
       #
       # @since 2.0.0.rc.1
       def determine_key
-        return name.to_s if relation.embedded?
+        return store_as.to_s if relation.embedded?
         relation.stores_foreign_key? ? foreign_key : "_id"
       end
 
@@ -909,6 +1079,23 @@ module Mongoid # :nodoc:
         @inverse_name ||= inverse_klass.name.underscore
       end
 
+      # For polymorphic children, we need to figure out the inverse from the
+      # actual instance on the other side, since we cannot know the exact class
+      # name to infer it from at load time.
+      #
+      # @example Find the inverses.
+      #   metadata.lookup_inverses(other)
+      #
+      # @param [ Document ] : The inverse document.
+      #
+      # @return [ Array<String> ] The inverse names.
+      def lookup_inverses(other)
+        if other
+          matching_metas = other.class.relations.find_all { |key, meta| meta.as == name }
+          matching_metas.map { |meta| meta[1].name }
+        end
+      end
+
       # For polymorphic children, we need to figure out the inverse from the
       # actual instance on the other side, since we cannot know the exact class
       # name to infer it from at load time.
@@ -922,9 +1109,8 @@ module Mongoid # :nodoc:
       #
       # @since 2.0.0.rc.1
       def lookup_inverse(other)
-        return nil unless other
-        other.class.relations.each_pair do |key, meta|
-          return meta.name if meta.as == name
+        if invs = lookup_inverses(other) && invs.count == 1
+          invs.first
         end
       end
     end

data/lib/mongoid/relations/nested_builder.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
-module Mongoid # :nodoc:
-  module Relations #:nodoc:
+module Mongoid
+  module Relations
 
     # This is the superclass for builders that are in charge of handling
     # creation, deletion, and updates of documents through that ever so lovely
@@ -57,8 +57,6 @@ module Mongoid # :nodoc:
 
       # Convert an id to its appropriate type.
       #
-      # @todo Durran: Move this into a common reusable place.
-      #
       # @example Convert the id.
       #   builder.convert_id(Person, "4d371b444835d98b8b000010")
       #
@@ -69,7 +67,7 @@ module Mongoid # :nodoc:
       #
       # @since 2.0.0.rc.6
       def convert_id(klass, id)
-        BSON::ObjectId.convert(klass, id)
+        klass.using_object_ids? ? BSON::ObjectId.mongoize(id) : id
       end
     end
   end

data/lib/mongoid/relations/one.rb

@@ -1,11 +1,23 @@
 # encoding: utf-8
-module Mongoid # :nodoc:
-  module Relations #:nodoc:
+module Mongoid
+  module Relations
 
     # This is the superclass for one to one relations and defines the common
     # behaviour or those proxies.
     class One < Proxy
 
+      # Clear this relation - same as calling #delete on the document.
+      #
+      # @example Clear the relation.
+      #   relation.clear
+      #
+      # @return [ true, false ] If the delete suceeded.
+      #
+      # @since 3.0.0
+      def clear
+        target.delete
+      end
+
       # Get all the documents in the relation that are loaded into memory.
       #
       # @example Get the in memory documents.

data/lib/mongoid/relations/options.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
-module Mongoid # :nodoc:
-  module Relations #:nodoc:
+module Mongoid
+  module Relations
 
     # This module contains the validating logic for options passed to relation
     # macros.

data/lib/mongoid/relations/polymorphic.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
-module Mongoid # :nodoc:
-  module Relations #:nodoc:
+module Mongoid
+  module Relations
 
     # This module contains the behaviour for handling polymorphic relational
     # associations.
@@ -11,7 +11,7 @@ module Mongoid # :nodoc:
         class_attribute :polymorphic
       end
 
-      module ClassMethods #:nodoc:
+      module ClassMethods
 
         # Attempts to set up the information needed to handle a polymorphic
         # relation, if the metadata checks out.
@@ -25,14 +25,14 @@ module Mongoid # :nodoc:
         #
         # @since 2.0.0.rc.1
         def polymorph(metadata)
-          tap do |klass|
-            if metadata.polymorphic?
-              klass.polymorphic = true
-              if metadata.relation.stores_foreign_key?
-                field(metadata.inverse_type, :type => String)
-              end
+          if metadata.polymorphic?
+            self.polymorphic = true
+            if metadata.relation.stores_foreign_key?
+              field(metadata.inverse_type, type: String)
+              field(metadata.inverse_of_field, type: Symbol)
             end
           end
+          self
         end
       end
     end

data/lib/mongoid/relations/proxy.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
-module Mongoid # :nodoc:
-  module Relations #:nodoc:
+module Mongoid
+  module Relations
 
     # This class is the superclass for all relation proxy objects, and contains
     # common behaviour for all of them.
@@ -18,9 +18,9 @@ module Mongoid # :nodoc:
       attr_accessor :base, :loaded, :metadata, :target
 
       # Backwards compatibility with Mongoid beta releases.
-      delegate :klass, :to => :metadata
-      delegate :bind_one, :unbind_one, :to => :binding
-      delegate :collection_name, :to => :base
+      delegate :klass, :foreign_key, :inverse_foreign_key, to: :metadata
+      delegate :bind_one, :unbind_one, to: :binding
+      delegate :collection_name, to: :base
 
       # Convenience for setting the target and the metadata properties since
       # all proxies will need to do this.
@@ -52,6 +52,35 @@ module Mongoid # :nodoc:
         target
       end
 
+      # Tell the next persistance operation to store in a specific collection,
+      # database or session.
+      #
+      # @example Save the current document to a different collection.
+      #   model.with(collection: "secondary").save
+      #
+      # @example Save the current document to a different database.
+      #   model.with(database: "secondary").save
+      #
+      # @example Save the current document to a different session.
+      #   model.with(session: "replica_set").save
+      #
+      # @example Save with a combination of options.
+      #   model.with(session: "sharded", database: "secondary").save
+      #
+      # @param [ Hash ] options The storage options.
+      #
+      # @option options [ String, Symbol ] :collection The collection name.
+      # @option options [ String, Symbol ] :database The database name.
+      # @option options [ String, Symbol ] :session The session name.
+      #
+      # @return [ Document ] The current document.
+      #
+      # @since 3.0.0
+      def with(options)
+        Threaded.set_persistence_options(klass, options)
+        self
+      end
+
       protected
 
       # Get the collection from the root of the hierarchy.
@@ -67,22 +96,6 @@ module Mongoid # :nodoc:
         root.collection unless root.embedded?
       end
 
-      # Return a new document for the type of class we want to instantiate.
-      # If the type is provided use that, otherwise the klass from the
-      # metadata.
-      #
-      # @example Get an instantiated document.
-      #   proxy.instantiated(Person)
-      #
-      # @param [ Class ] type The type of class to instantiate.
-      #
-      # @return [ Document ] The freshly created document.
-      #
-      # @since 2.0.0.rc.1
-      def instantiated(type = nil)
-        type ? type.new : metadata.klass.new
-      end
-
       # Takes the supplied document and sets the metadata on it.
       #
       # @example Set the metadata.
@@ -132,16 +145,32 @@ module Mongoid # :nodoc:
         raise Errors::UnsavedDocument.new(base, doc)
       end
 
-      # Get the class of the root document in the hierarchy.
-      #
-      # @example Get the root's class.
-      #   proxy.root_class
-      #
-      # @return [ Class ] The root class.
-      #
-      # @since 2.1.8
-      def root_class
-        @root_class ||= base._root.class
+      class << self
+
+        # Get the criteria that is used to eager load a relation of this
+        # type.
+        #
+        # @example Get the eager load criteria.
+        #   Proxy.eager_load(metadata, criteria)
+        #
+        # @param [ Metadata ] metadata The relation metadata.
+        # @param [ Array<Object> ] ids The ids of the base docs.
+        #
+        # @return [ Criteria ] The criteria to eager load the relation.
+        #
+        # @since 2.2.0
+        def eager_load_ids(metadata, ids)
+          cleared = false
+          klass, foreign_key = metadata.klass, metadata.foreign_key
+          klass.any_in(foreign_key => ids).each do |doc|
+            selector = { foreign_key => doc.send(foreign_key) }
+            unless cleared
+              IdentityMap.clear_many(klass, selector)
+              cleared = true
+            end
+            yield(doc, foreign_key => doc.send(foreign_key))
+          end
+        end
       end
     end
   end