mongoid 2.0.2 → 2.1.0

data/lib/mongoid/finders.rb

@@ -7,21 +7,20 @@ module Mongoid #:nodoc:
 
     # Delegate to the criteria methods that are natural for creating a new
     # criteria.
-    [ :all_in, :any_in, :any_of, :asc, :ascending, :avg, :desc, :descending,
-      :excludes, :limit, :max, :min, :not_in, :only, :order_by,
-      :skip, :sum, :without, :where, :update, :update_all, :near ].each do |name|
-      define_method(name) do |*args|
-        criteria.send(name, *args)
-      end
-    end
+    critera_methods = [ :all_in, :any_in, :any_of, :asc, :ascending, :avg,
+                        :desc, :descending, :excludes, :limit, :max, :min,
+                        :not_in, :only, :order_by, :skip, :sum, :without,
+                        :where, :update, :update_all, :near ]
+    delegate *(critera_methods.dup << {:to => :criteria})
 
-    # Find +Documents+ given the conditions.
+    # Find all documents that match the given conditions.
     #
-    # Options:
+    # @example Find all matching documents given conditions.
+    #   Person.all(:conditions => { :attribute => "value" })
     #
-    # args: A +Hash+ with a conditions key and other options
+    # @param [ Array ] args The conditions with options.
     #
-    # <tt>Person.all(:conditions => { :attribute => "value" })</tt>
+    # @return [ Criteria ] The matching documents.
     def all(*args)
       find(:all, *args)
     end
@@ -29,12 +28,22 @@ module Mongoid #:nodoc:
     # Returns a count of matching records in the database based on the
     # provided arguments.
     #
-    # <tt>Person.count(:conditions => { :attribute => "value" })</tt>
+    # @example Get the count of matching documents.
+    #   Person.count(:conditions => { :attribute => "value" })
+    #
+    # @param [ Array ] args The conditions.
+    #
+    # @return [ Integer ] The number of matching documents.
     def count(*args)
       find(:all, *args).count
     end
 
     # Returns true if count is zero
+    #
+    # @example Are there no saved documents for this model?
+    #   Person.empty?
+    #
+    # @return [ true, false ] If the collection is empty.
     def empty?
       count == 0
     end
@@ -42,7 +51,10 @@ module Mongoid #:nodoc:
     # Returns true if there are on document in database based on the
     # provided arguments.
     #
-    # <tt>Person.exists?(:conditions => { :attribute => "value" })</tt>
+    # @example Do any documents exist for the conditions?
+    #   Person.exists?(:conditions => { :attribute => "value" })
+    #
+    # @param [ Array ] args The conditions.
     def exists?(*args)
        find(:all, *args).limit(1).count == 1
     end
@@ -55,71 +67,83 @@ module Mongoid #:nodoc:
     # it will attempt to find either a single +Document+ or multiples based
     # on the conditions provided and the first parameter.
     #
-    # Example:
+    # @example Find the first matching document.
+    #   Person.find(:first, :conditions => { :attribute => "value" })
     #
-    # <tt>Person.find(:first, :conditions => { :attribute => "value" })</tt>
-    # <tt>Person.find(:all, :conditions => { :attribute => "value" })</tt>
-    # <tt>Person.find(BSON::ObjectId)</tt>
+    # @example Find all matching documents.
+    #   Person.find(:all, :conditions => { :attribute => "value" })
     #
-    # Options:
+    # @example Find a single document by an id.
+    #   Person.find(BSON::ObjectId)
     #
-    # args: An assortment of finder options.
+    # @param [ Array ] args An assortment of finder options.
     #
-    # Returns:
-    #
-    # A document or criteria.
+    # @return [ Document, nil, Criteria ] A document or matching documents.
     def find(*args)
       criteria.find(*args)
     end
 
     # Find the first +Document+ given the conditions, or creates a new document
-    # with the conditions that were supplied
+    # with the conditions that were supplied.
     #
-    # Options:
+    # @example Find or create the document.
+    #   Person.find_or_create_by(:attribute => "value")
     #
-    # args: A +Hash+ of attributes
+    # @param [ Hash ] attrs The attributes to check.
     #
-    # <tt>Person.find_or_create_by(:attribute => "value")</tt>
+    # @return [ Document ] A matching or newly created document.
     def find_or_create_by(attrs = {}, &block)
       find_or(:create, attrs, &block)
     end
 
-    # Find the first +Document+ given the conditions, or instantiates a new document
-    # with the conditions that were supplied
+    # Find the first +Document+ given the conditions, or initializes a new document
+    # with the conditions that were supplied.
     #
-    # Options:
+    # @example Find or initialize the document.
+    #   Person.find_or_initialize_by(:attribute => "value")
     #
-    # args: A +Hash+ of attributes
+    # @param [ Hash ] attrs The attributes to check.
     #
-    # <tt>Person.find_or_initialize_by(:attribute => "value")</tt>
+    # @return [ Document ] A matching or newly initialized document.
     def find_or_initialize_by(attrs = {}, &block)
       find_or(:new, attrs, &block)
     end
 
     # Find the first +Document+ given the conditions.
     #
-    # Options:
+    # @example Find the first document.
+    #   Person.first(:conditions => { :attribute => "value" })
     #
-    # args: A +Hash+ with a conditions key and other options
+    # @param [ Array ] args The conditions with options.
     #
-    # <tt>Person.first(:conditions => { :attribute => "value" })</tt>
+    # @return [ Document ] The first matching document.
     def first(*args)
       find(:first, *args)
     end
 
     # Find the last +Document+ given the conditions.
     #
-    # Options:
+    # @example Find the last document.
+    #   Person.last(:conditions => { :attribute => "value" })
     #
-    # args: A +Hash+ with a conditions key and other options
+    # @param [ Array ] args The conditions with options.
     #
-    # <tt>Person.last(:conditions => { :attribute => "value" })</tt>
+    # @return [ Document ] The last matching document.
     def last(*args)
       find(:last, *args)
     end
 
     protected
+
     # Find the first object or create/initialize it.
+    #
+    # @example Find or perform an action.
+    #   Person.find_or(:create, :name => "Dev")
+    #
+    # @param [ Symbol ] method The method to invoke.
+    # @param [ Hash ] attrs The attributes to query or set.
+    #
+    # @return [ Document ] The first or new document.
     def find_or(method, attrs = {}, &block)
       first(:conditions => attrs) || send(method, attrs, &block)
     end

data/lib/mongoid/hierarchy.rb

@@ -2,6 +2,7 @@
 module Mongoid #:nodoc
   module Hierarchy #:nodoc
     extend ActiveSupport::Concern
+
     included do
       attr_accessor :_parent
     end
@@ -33,16 +34,18 @@ module Mongoid #:nodoc
       #
       # @return [ Array<Document> ] All child documents in the hierarchy.
       def _children
-        relations.inject([]) do |children, (name, metadata)|
-          children.tap do |kids|
-            if metadata.embedded? && name != "versions"
-              child = send(name)
-              child.to_a.each do |doc|
-                kids.push(doc).concat(doc._children)
-              end unless child.blank?
+        @_children ||=
+          [].tap do |children|
+            relations.each_pair do |name, metadata|
+              if metadata.embedded?
+                child = send(name)
+                child.to_a.each do |doc|
+                  children.push(doc)
+                  children.concat(doc._children) unless metadata.versioned?
+                end if child
+              end
             end
           end
-        end
       end
 
       # Determines if the document is a subclass of another document.
@@ -68,6 +71,38 @@ module Mongoid #:nodoc
         self._parent = document
       end
 
+      # Remove a child document from this parent. If an embeds one then set to
+      # nil, otherwise remove from the embeds many.
+      #
+      # This is called from the +RemoveEmbedded+ persistence command.
+      #
+      # @example Remove the child.
+      #   document.remove_child(child)
+      #
+      # @param [ Document ] child The child (embedded) document to remove.
+      #
+      # @since 2.0.0.beta.1
+      def remove_child(child)
+        name = child.metadata.name
+        child.embedded_one? ? remove_ivar(name) : send(name).delete(child)
+      end
+
+      # After children are persisted we can call this to move all their changes
+      # and flag them as persisted in one call.
+      #
+      # @example Reset the children.
+      #   document.reset_persisted_children
+      #
+      # @return [ Array<Document> ] The children.
+      #
+      # @since 2.1.0
+      def reset_persisted_children
+        _children.each do |child|
+          child.move_changes
+          child.new_record = false
+        end
+      end
+
       # Return the root document in the object graph. If the current document
       # is the root object in the graph it will return self.
       #

data/lib/mongoid/identity_map.rb

@@ -0,0 +1,106 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+
+  # Defines behaviour for the identity map in Mongoid.
+  class IdentityMap < Hash
+
+    # Get a document from the identity map by its id.
+    #
+    # @example Get the document from the map.
+    #   map.get(Person, id)
+    #
+    # @param [ Class ] klass The class of the document.
+    # @param [ Object ] id The document id.
+    #
+    # @return [ Document ] The matching document.
+    #
+    # @since 2.1.0
+    def get(klass, id)
+      return nil unless Mongoid.identity_map_enabled?
+      documents_for(klass)[id]
+    end
+
+    # Get a single document that matches the provided criteria.
+    #
+    # @example Get the document for the criteria.
+    #   map.match(Person.where(:_id => id))
+    #
+    # @param [ Criteria ] criteria The criteria to match.
+    #
+    # @return [ Document ] The first matching document.
+    #
+    # @since 2.1.0
+    def match(criteria)
+      return nil unless Mongoid.identity_map_enabled?
+      documents_for(criteria.klass).values.detect do |doc|
+        doc.matches?(criteria.selector)
+      end
+    end
+
+    # Remove the document from the identity map.
+    #
+    # @example Remove the document.
+    #   map.removed(person)
+    #
+    # @param [ Document ] document The document to remove.
+    #
+    # @return [ Document, nil ] The removed document.
+    #
+    # @since 2.1.0
+    def remove(document)
+      return nil unless Mongoid.identity_map_enabled? && document && document.id
+      documents_for(document.class).delete(document.id)
+    end
+
+    # Puts a document in the identity map, accessed by it's id.
+    #
+    # @example Put the document in the map.
+    #   identity_map.set(document)
+    #
+    # @param [ Document ] document The document to place in the map.
+    #
+    # @return [ Document ] The provided document.
+    #
+    # @since 2.1.0
+    def set(document)
+      return nil unless Mongoid.identity_map_enabled? && document && document.id
+      documents_for(document.class)[document.id] = document
+    end
+
+    private
+
+    # Get the documents in the identity map for a specific class.
+    #
+    # @example Get the documents for the class.
+    #   map.documents_for(Person)
+    #
+    # @param [ Class ] klass The class to retrieve.
+    #
+    # @return [ Hash ] The documents.
+    #
+    # @since 2.1.0
+    def documents_for(klass)
+      self[klass] ||= {}
+    end
+
+    class << self
+
+      # For ease of access we provide the same API to the identity map on the
+      # class level, which in turn just gets the identity map that is on the
+      # current thread.
+      #
+      # @example Get a document from the current identity map by id.
+      #   IdentityMap.get(id)
+      #
+      # @example Set a document in the current identity map.
+      #   IdentityMap.set(document)
+      #
+      # @since 2.1.0
+      delegate *(
+        Hash.public_instance_methods(false) +
+        IdentityMap.public_instance_methods(false) <<
+        { :to => :"Mongoid::Threaded.identity_map" }
+      )
+    end
+  end
+end

data/lib/mongoid/indexes.rb

@@ -2,6 +2,7 @@
 module Mongoid #:nodoc
   module Indexes #:nodoc
     extend ActiveSupport::Concern
+
     included do
       cattr_accessor :index_options
       self.index_options = {}
@@ -10,16 +11,22 @@ module Mongoid #:nodoc
     module ClassMethods #:nodoc
 
       # Send the actual index creation comments to the MongoDB driver
+      #
+      # @example Create the indexes for the class.
+      #   Person.create_indexes
       def create_indexes
         return unless index_options
         current_collection = self._collection || set_collection
-        index_options.each do |name, options|
+        index_options.each_pair do |name, options|
           current_collection.create_index(name, options)
         end
       end
 
       # Add the default indexes to the root document if they do not already
       # exist. Currently this is only _type.
+      #
+      # @example Add Mongoid internal indexes.
+      #   Person.add_indexes
       def add_indexes
         if hereditary? && !index_options[:_type]
           self.index_options[:_type] = {:unique => false, :background => true}
@@ -29,6 +36,15 @@ module Mongoid #:nodoc
 
       # Adds an index on the field specified. Options can be :unique => true or
       # :unique => false. It will default to the latter.
+      #
+      # @example Create a basic index.
+      #   class Person
+      #     include Mongoid::Document
+      #     field :name, :type => String
+      #     index :name, :background => true
+      #
+      # @param [ Symbol ] name The name of the field.
+      # @param [ Hash ] options The index options.
       def index(name, options = { :unique => false })
         self.index_options[name] = options
         create_indexes if Mongoid.autocreate_indexes

data/lib/mongoid/javascript.rb

@@ -7,9 +7,8 @@ module Mongoid #:nodoc:
     # Load the javascript functions and define a class method for each one,
     # that memoizes the value.
     #
-    # Example:
-    #
-    # <tt>Mongoid::Javascript.aggregate</tt>
+    # @example Get the function.
+    #   Mongoid::Javascript.aggregate
     YAML.load(File.read(FUNCTIONS)).each_pair do |key, function|
       (class << self; self; end).class_eval <<-EOT
         def #{key}

data/lib/mongoid/keys.rb

@@ -7,8 +7,11 @@ module Mongoid #:nodoc:
     extend ActiveSupport::Concern
 
     included do
-      cattr_accessor :primary_key, :object_ids
+      cattr_accessor :primary_key, :using_object_ids
+      self.using_object_ids = true
       delegate :primary_key, :using_object_ids?, :to => "self.class"
+
+      attr_reader :identifier
     end
 
     private
@@ -51,10 +54,9 @@ module Mongoid #:nodoc:
     #
     # @since 2.0.0
     def swap_composite_keys(&block)
-      old_id, new_id = id.dup, identify
-      @attributes["_id"] = old_id
+      @identifier, new_id = id.dup, identify
       block.call
-      @attributes["_id"] = new_id
+      @identifier = nil
     end
 
     module ClassMethods #:nodoc:
@@ -76,8 +78,9 @@ module Mongoid #:nodoc:
       #
       # @since 2.0.0.beta.1
       def identity(options = {})
-        fields["_id"].type = options[:type]
-        @object_ids = id_is_object
+        type = options[:type]
+        replace_field("_id", type)
+        self.using_object_ids = (type == BSON::ObjectId)
       end
 
       # Defines the field that will be used for the id of this +Document+. This
@@ -110,21 +113,7 @@ module Mongoid #:nodoc:
       #
       # @since 1.0.0
       def using_object_ids?
-        @object_ids ||= id_is_object
-      end
-
-      private
-
-      # Is the id field type an object id?
-      #
-      # @example Is type an object id.
-      #   Class.id_is_object
-      #
-      # @return [ true, false ] Is the id an object id.
-      #
-      # @since 2.0.0
-      def id_is_object
-        fields["_id"].type == BSON::ObjectId
+        using_object_ids
       end
     end
   end