humanoid 1.2.7

data/lib/humanoid/callbacks.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Callbacks
+    def self.included(base)
+      base.class_eval do
+        include ActiveSupport::Callbacks
+
+        # Define all the callbacks that are accepted by the document.
+        define_callbacks \
+          :before_create,
+          :after_create,
+          :before_destroy,
+          :after_destroy,
+          :before_save,
+          :after_save,
+          :before_update,
+          :after_update,
+          :before_validation,
+          :after_validation
+      end
+    end
+  end
+end

data/lib/humanoid/collection.rb

@@ -0,0 +1,118 @@
+# encoding: utf-8
+require "humanoid/collections/operations"
+require "humanoid/collections/cyclic_iterator"
+require "humanoid/collections/mimic"
+require "humanoid/collections/master"
+require "humanoid/collections/slaves"
+
+module Humanoid #:nodoc
+  class Collection
+    include Collections::Mimic
+    attr_reader :counter, :name
+
+    # All write operations should delegate to the master connection. These
+    # operations mimic the methods on a Mongo:Collection.
+    #
+    # Example:
+    #
+    # <tt>collection.save({ :name => "Al" })</tt>
+    proxy(:master, Collections::Operations::PROXIED)
+
+    # Determines where to send the next read query. If the slaves are not
+    # defined then send to master. If the read counter is under the configured
+    # maximum then return the master. In any other case return the slaves.
+    #
+    # Example:
+    #
+    # <tt>collection.directed</tt>
+    #
+    # Return:
+    #
+    # Either a +Master+ or +Slaves+ collection.
+    def directed(options = {})
+      enslave = options.delete(:enslave) || @klass.enslaved?
+      enslave ? master_or_slaves : master
+    end
+
+    # Find documents from the database given a selector and options.
+    #
+    # Options:
+    #
+    # selector: A +Hash+ selector that is the query.
+    # options: The options to pass to the db.
+    #
+    # Example:
+    #
+    # <tt>collection.find({ :test => "value" })</tt>
+    def find(selector = {}, options = {})
+      cursor = Humanoid::Cursor.new(@klass, self, directed(options).find(selector, options))
+      if block_given?
+        yield cursor; cursor.close
+      else
+        cursor
+      end
+    end
+
+    # Find the first document from the database given a selector and options.
+    #
+    # Options:
+    #
+    # selector: A +Hash+ selector that is the query.
+    # options: The options to pass to the db.
+    #
+    # Example:
+    #
+    # <tt>collection.find_one({ :test => "value" })</tt>
+    def find_one(selector = {}, options = {})
+      directed(options).find_one(selector, options)
+    end
+
+    # Initialize a new Humanoid::Collection, setting up the master, slave, and
+    # name attributes. Masters will be used for writes, slaves for reads.
+    #
+    # Example:
+    #
+    # <tt>Humanoid::Collection.new(masters, slaves, "test")</tt>
+    def initialize(klass, name)
+      @klass, @name = klass, name
+    end
+
+    # Perform a map/reduce on the documents.
+    #
+    # Options:
+    #
+    # map: The map javascript funcdtion.
+    # reduce: The reduce javascript function.
+    def map_reduce(map, reduce, options = {})
+      directed(options).map_reduce(map, reduce, options)
+    end
+
+    alias :mapreduce :map_reduce
+
+    # Return the object responsible for writes to the database. This will
+    # always return a collection associated with the Master DB.
+    #
+    # Example:
+    #
+    # <tt>collection.writer</tt>
+    def master
+      @master ||= Collections::Master.new(Humanoid.master, @name)
+    end
+
+    # Return the object responsible for reading documents from the database.
+    # This is usually the slave databases, but in their absence the master will
+    # handle the task.
+    #
+    # Example:
+    #
+    # <tt>collection.reader</tt>
+    def slaves
+      @slaves ||= Collections::Slaves.new(Humanoid.slaves, @name)
+    end
+
+    protected
+    def master_or_slaves
+      slaves.empty? ? master : slaves
+    end
+  end
+end

data/lib/humanoid/collections/cyclic_iterator.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Collections #:nodoc:
+    class CyclicIterator
+
+      attr_reader :counter
+
+      # Performs iteration over an array, if the array gets to the end then loop
+      # back to the first.
+      #
+      # Example:
+      #
+      # <tt>CyclicIterator.new([ first, second ])</tt>
+      def initialize(array)
+        @array, @counter = array, -1
+      end
+
+      # Get the next element in the array. If the element is the last in the
+      # array then return the first.
+      #
+      # Example:
+      #
+      # <tt>iterator.next</tt>
+      #
+      # Returns:
+      #
+      # The next element in the array.
+      def next
+        (@counter == @array.size - 1) ? @counter = 0 : @counter = @counter + 1
+        @array[@counter]
+      end
+    end
+  end
+end

data/lib/humanoid/collections/master.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Collections #:nodoc:
+    class Master
+      include Mimic
+
+      attr_reader :collection
+
+      # All read and write operations should delegate to the master connection.
+      # These operations mimic the methods on a Mongo:Collection.
+      #
+      # Example:
+      #
+      # <tt>collection.save({ :name => "Al" })</tt>
+      proxy(:collection, Operations::ALL)
+
+      # Create the new database writer. Will create a collection from the
+      # master database.
+      #
+      # Example:
+      #
+      # <tt>Master.new(master, "humanoid_people")</tt>
+      def initialize(master, name)
+        @collection = master.collection(name)
+      end
+    end
+  end
+end

data/lib/humanoid/collections/mimic.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Collections #:nodoc:
+    module Mimic #:nodoc:
+      def self.included(base)
+        base.class_eval do
+          include InstanceMethods
+          extend ClassMethods
+        end
+      end
+
+      module InstanceMethods #:nodoc:
+        # Retry the supplied operation until the reconnect time has expired,
+        # defined in the humanoid Config module.
+        #
+        # Example:
+        #
+        # <tt>master.attempt(operation)</tt>
+        def attempt(operation, start)
+          begin
+            elapsed = (Time.now - start)
+            operation.call
+          rescue Mongo::ConnectionFailure => error
+            (elapsed < Humanoid.reconnect_time) ? retry : (raise error)
+          end
+        end
+      end
+
+      module ClassMethods #:nodoc:
+        # Proxy all the supplied operations to the internal collection or target.
+        #
+        # Example:
+        #
+        # <tt>proxy Operations::ALL, :collection</tt>
+        def proxy(target, operations)
+          operations.each do |name|
+            define_method(name) do |*args|
+              operation = lambda { send(target).send(name, *args) }
+              attempt(operation, Time.now)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/humanoid/collections/operations.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Collections #:nodoc:
+    module Operations #:nodoc:
+      # Constant definining all the read operations available for a
+      # Mongo:Collection. This is used in delegation.
+      READ = [
+        :[],
+        :db,
+        :count,
+        :distinct,
+        :find,
+        :find_one,
+        :group,
+        :index_information,
+        :map_reduce,
+        :mapreduce,
+        :options
+      ]
+
+      # Constant definining all the write operations available for a
+      # Mongo:Collection. This is used in delegation.
+      WRITE = [
+        :<<,
+        :create_index,
+        :drop,
+        :drop_index,
+        :drop_indexes,
+        :insert,
+        :remove,
+        :rename,
+        :save,
+        :update
+      ]
+
+      # Convenience constant for getting back all collection operations.
+      ALL = (READ + WRITE)
+      PROXIED = ALL - [ :find, :find_one, :map_reduce, :mapreduce ]
+    end
+  end
+end

data/lib/humanoid/collections/slaves.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Collections #:nodoc:
+    class Slaves
+      include Mimic
+
+      attr_reader :iterator
+
+      # All read operations should delegate to the slave connections.
+      # These operations mimic the methods on a Mongo:Collection.
+      #
+      # Example:
+      #
+      # <tt>collection.save({ :name => "Al" })</tt>
+      proxy(:collection, Operations::READ)
+
+      # Is the collection of slaves empty or not?
+      #
+      # Return:
+      #
+      # True is the iterator is not set, false if not.
+      def empty?
+        @iterator.nil?
+      end
+
+      # Create the new database reader. Will create a collection from the
+      # slave databases and cycle through them on each read.
+      #
+      # Example:
+      #
+      # <tt>Reader.new(slaves, "humanoid_people")</tt>
+      def initialize(slaves, name)
+        unless slaves.blank?
+          @iterator = CyclicIterator.new(slaves.collect { |db| db.collection(name) })
+        end
+      end
+
+      protected
+      def collection
+        @iterator.next
+      end
+    end
+  end
+end

data/lib/humanoid/commands.rb

@@ -0,0 +1,182 @@
+# encoding: utf-8
+require "humanoid/commands/create"
+require "humanoid/commands/deletion"
+require "humanoid/commands/delete"
+require "humanoid/commands/delete_all"
+require "humanoid/commands/destroy"
+require "humanoid/commands/destroy_all"
+require "humanoid/commands/save"
+
+module Humanoid #:nodoc:
+
+  # This module is included in the +Document+ to provide all the persistence
+  # methods required on the +Document+ object and class.
+  module Commands
+    def self.included(base)
+      base.class_eval do
+        include InstanceMethods
+        extend ClassMethods
+      end
+    end
+
+    module InstanceMethods
+
+      # Delete the +Document+ from the database. This method is an optimized
+      # delete that does not force any callbacks.
+      #
+      # Example:
+      #
+      # <tt>document.delete</tt>
+      #
+      # Returns: true unless an error occurs.
+      def delete
+        Delete.execute(self)
+      end
+
+      # Destroy the +Document+. This will delete the document from the database
+      # and run the before and after destroy callbacks.
+      #
+      # Example:
+      #
+      # <tt>document.destroy</tt>
+      #
+      # Returns: true unless an error occurs.
+      def destroy
+        Destroy.execute(self)
+      end
+
+      # Save the +Document+. If the document is new, then the before and after
+      # create callbacks will get executed as well as the save callbacks.
+      # Otherwise only the save callbacks will run.
+      #
+      # Options:
+      #
+      # validate: Run validations or not. Defaults to true.
+      #
+      # Example:
+      #
+      # <tt>document.save # save with validations</tt>
+      # <tt>document.save(false) # save without validations</tt>
+      #
+      # Returns: true if validation passes, false if not.
+      def save(validate = true)
+        new = new_record?
+        run_callbacks(:before_create) if new
+        begin
+          saved = Save.execute(self, validate)
+        rescue Mongo::OperationFailure => e
+          errors.add(:humanoid, e.message)
+        end
+        run_callbacks(:after_create) if new && saved
+        saved
+      end
+
+      # Save the +Document+, dangerously. Before and after save callbacks will
+      # get run. If validation fails an error will get raised.
+      #
+      # Example:
+      #
+      # <tt>document.save!</tt>
+      #
+      # Returns: true if validation passes
+      def save!
+        return save(true) || (raise Errors::Validations.new(self.errors))
+      end
+
+      # Update the document attributes and persist the document to the
+      # database. Will delegate to save with all callbacks.
+      #
+      # Example:
+      #
+      # <tt>document.update_attributes(:title => "Test")</tt>
+      def update_attributes(attrs = {})
+        set_attributes(attrs); save
+      end
+
+      # Update the document attributes and persist the document to the
+      # database. Will delegate to save!
+      #
+      # Example:
+      #
+      # <tt>document.update_attributes!(:title => "Test")</tt>
+      def update_attributes!(attrs = {})
+        set_attributes(attrs); save!
+      end
+
+      protected
+      def set_attributes(attrs = {})
+        run_callbacks(:before_update)
+        write_attributes(attrs)
+        run_callbacks(:after_update)
+      end
+
+    end
+
+    module ClassMethods
+
+      # Create a new +Document+. This will instantiate a new document and save
+      # it in a single call. Will always return the document whether save
+      # passed or not.
+      #
+      # Example:
+      #
+      # <tt>Person.create(:title => "Mr")</tt>
+      #
+      # Returns: the +Document+.
+      def create(attributes = {})
+        document = new(attributes)
+        begin
+          Create.execute(document)
+        rescue Mongo::OperationFailure => e
+          document.errors.add(:humanoid, e.message)
+        end
+        document
+      end
+
+      # Create a new +Document+. This will instantiate a new document and save
+      # it in a single call. Will always return the document whether save
+      # passed or not. Will raise an error if validation fails.
+      #
+      # Example:
+      #
+      # <tt>Person.create!(:title => "Mr")</tt>
+      #
+      # Returns: the +Document+.
+      def create!(attributes = {})
+        document = Create.execute(new(attributes), true)
+        raise Errors::Validations.new(document.errors) unless document.errors.empty?
+        document
+      end
+
+      # Delete all documents given the supplied conditions. If no conditions
+      # are passed, the entire collection will be dropped for performance
+      # benefits. Does not fire any callbacks.
+      #
+      # Example:
+      #
+      # <tt>Person.delete_all(:conditions => { :title => "Sir" })</tt>
+      # <tt>Person.delete_all</tt>
+      #
+      # Returns: true or raises an error.
+      def delete_all(conditions = {})
+        DeleteAll.execute(self, conditions)
+      end
+
+      # Delete all documents given the supplied conditions. If no conditions
+      # are passed, the entire collection will be dropped for performance
+      # benefits. Fires the destroy callbacks if conditions were passed.
+      #
+      # Example:
+      #
+      # <tt>Person.destroy_all(:conditions => { :title => "Sir" })</tt>
+      # <tt>Person.destroy_all</tt>
+      #
+      # Returns: true or raises an error.
+      def destroy_all(conditions = {})
+        DestroyAll.execute(self, conditions)
+      end
+
+    end
+
+  end
+end