georgepalmer-couch_foo 0.7.1

data/lib/couch_foo/calculations.rb

@@ -0,0 +1,117 @@
+module CouchFoo
+  module Calculations #:nodoc:
+    CALCULATIONS_OPTIONS = [:conditions, :order, :distinct, :limit, :count, :offset, :include]
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Count operates using two different approaches.
+      #
+      # * Count all: By not passing any parameters to count, it will return a count of all the rows for the model.
+      # * Count using options will find the row count matched by the options used.
+      #
+      # The second approach, count using options, accepts an option hash as the only parameter. The options are:
+      #
+      # * <tt>:conditions</tt>: A conditions hash like { :user_name => username }. See conditions in the intro.
+      # * <tt>:include</tt>: Named associations that should be loaded at the same time.  See eager loading 
+      #   under Associations.
+      # * <tt>:order</tt>: An element to order on, eg :order => :user_name
+      # * <tt>:distinct</tt>: Set this to true to remove repeating elements
+      #
+      # Examples for counting all:
+      #   Person.count         # returns the total count of all people
+      #
+      # Examples for count with options:
+      #   Person.count(:conditions => {age = 26})
+      #
+      # Note: <tt>Person.count(:all)</tt> will not work because it will use <tt>:all</tt> as the condition.  Use Person.count instead.
+      def count(options = {})
+        calculate(:count, nil, options)
+      end
+
+      # Calculates the average value on a given property.  The value is returned as a float.  See +calculate+ for examples with options.
+      #
+      #   Person.average('age')
+      def average(attribute_name, options = {})
+        calculate(:avg, attribute_name, options)
+      end
+
+      # Calculates the minimum value on a given property.  The value is returned with the same data type of the property.  See +calculate+ for examples with options.
+      #
+      #   Person.minimum('age')
+      def minimum(attribute_name, options = {})
+        calculate(:min, attribute_name, options)
+      end
+
+      # Calculates the maximum value on a given property.  The value is returned with the same data type of the property.  See +calculate+ for examples with options.
+      #
+      #   Person.maximum('age')
+      def maximum(attribute_name, options = {})
+        calculate(:max, attribute_name, options)
+      end
+
+      # Calculates the sum of values on a given property.  The value is returned with the same data type of the property.  See +calculate+ for examples with options.
+      #
+      #   Person.sum('age')
+      def sum(attribute_name, options = {})
+        calculate(:sum, attribute_name, options)
+      end
+
+      # This calculates aggregate values in the given property.  Methods for count, sum, average, minimum, 
+      # and maximum have been added as shortcuts.
+      # Options such as <tt>:conditions</tt>, <tt>:order</tt>, <tt>:count</tt> and <tt>:distinct</tt> 
+      # can be passed to customize the query.
+      #
+      # Options:
+      # * <tt>:conditions</tt>: A conditions hash like { :user_name => username }. See conditions in the intro.
+      # * <tt>:include</tt>: Named associations that should be loaded at the same time.  See eager loading 
+      #   under Associations.
+      # * <tt>:order</tt>: An element to order on, eg :order => :user_name
+      # * <tt>:distinct</tt>: Set this to true to remove repeating elements
+      #
+      # Examples:
+      #   Person.calculate(:count, :all) # The same as Person.count
+      #   Person.average(:age) # Find the average of people
+      #   Person.minimum(:age, :conditions => {:last_name => 'Drake'}) # Finds the minimum age for everyone with a last name other than 'Drake'
+      #   Person.sum("2 * age")
+      def calculate(operation, attribute_name, options = {})
+        validate_calculation_options(operation, options)
+        catch :invalid_query do
+          return execute_simple_calculation(operation, attribute_name, options)
+        end
+        0
+      end
+
+      protected
+        def execute_simple_calculation(operation, attribute_name, options) #:nodoc:
+          if operation == :count
+            value = count_view(options)
+          else
+            raise "NotImplementedYet"
+            #TODO test sum on associationproxy when done
+          end
+          type_cast_calculated_value(value, attribute_name, operation)
+        end
+
+      private
+        def validate_calculation_options(operation, options = {})
+          options.assert_valid_keys(CALCULATIONS_OPTIONS)
+        end
+
+        def type_cast_calculated_value(value, attribute_name, operation = nil)
+          operation = operation.to_s.downcase
+          case operation
+            when 'count' then value.to_i
+            when 'sum'   then type_cast_using_property(value || '0', attribute_name)
+            when 'avg'   then value && value.to_d
+            else type_cast_using_property(value, attribute_name)
+          end
+        end
+        
+        def type_cast_using_property(value, attribute_name)
+          attribute_name ? convert_to_type(value, type_for_property(attribute_name.to_sym)) : value
+        end
+    end
+  end
+end

data/lib/couch_foo/callbacks.rb

@@ -0,0 +1,311 @@
+require 'observer'
+
+module CouchFoo
+  # Callbacks are hooks into the lifecycle of a Couch Foo object that allow you to trigger logic
+  # before or after an alteration of the object state. This can be used to make sure that associated 
+  # and dependent objects are deleted when destroy is called (by overwriting +before_destroy+) or to 
+  # massage attributes before they're validated (by overwriting +before_validation+). As an example 
+  # of the callbacks initiated, consider the <tt>Base#save</tt> call:
+  #
+  # * (-) <tt>save</tt>
+  # * (-) <tt>valid</tt>
+  # * (1) <tt>before_validation</tt>
+  # * (2) <tt>before_validation_on_create</tt>
+  # * (-) <tt>validate</tt>
+  # * (-) <tt>validate_on_create</tt>
+  # * (3) <tt>after_validation</tt>
+  # * (4) <tt>after_validation_on_create</tt>
+  # * (5) <tt>before_save</tt>
+  # * (6) <tt>before_create</tt>
+  # * (-) <tt>create</tt>
+  # * (7) <tt>after_create</tt>
+  # * (8) <tt>after_save</tt>
+  #
+  # That's a total of eight callbacks, which gives you immense power to react and prepare for each state in the
+  # Couch Foo lifecycle.
+  #
+  # Examples:
+  #   class CreditCard < CouchFoo::Base
+  #     # Strip everything but digits, so the user can specify "555 234 34" or
+  #     # "5552-3434" or both will mean "55523434"
+  #     def before_validation_on_create
+  #       self.number = number.gsub(/[^0-9]/, "") if attribute_present?("number")
+  #     end
+  #   end
+  #
+  #   class Subscription < CouchFoo::Base
+  #     before_create :record_signup
+  #
+  #     private
+  #       def record_signup
+  #         self.signed_up_on = Date.today
+  #       end
+  #   end
+  #
+  #   class Firm < CouchFoo::Base
+  #     # Destroys the associated clients and people when the firm is destroyed
+  #     before_destroy { |record| Person.destroy_all "firm_id = #{record.id}"   }
+  #     before_destroy { |record| Client.destroy_all "client_of = #{record.id}" }
+  #   end
+  #
+  # == Inheritable callback queues
+  #
+  # Besides the overwriteable callback methods, it's also possible to register callbacks through the use 
+  # of the callback macros.  Their main advantage is that the macros add behavior into a callback queue 
+  # that is kept intact down through an inheritance hierarchy. Example:
+  #
+  #   class Topic < CouchFoo::Base
+  #     before_destroy :destroy_author
+  #   end
+  #
+  #   class Reply < Topic
+  #     before_destroy :destroy_readers
+  #   end
+  #
+  # Now, when <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> 
+  # is run, both +destroy_author+ and +destroy_readers+ are called. Contrast this to the situation where
+  # we've implemented the save behavior through overwriteable methods:
+  #
+  #   class Topic < CouchFoo::Base
+  #     def before_destroy() destroy_author end
+  #   end
+  #
+  #   class Reply < Topic
+  #     def before_destroy() destroy_readers end
+  #   end
+  #
+  # In that case, <tt>Reply#destroy</tt> would only run +destroy_readers+ and _not_ +destroy_author+. 
+  # So, use the callback macros when you want to ensure that a certain callback is called for the 
+  # entire hierarchy, and use the regular overwriteable methods when you want to leave it up to each 
+  # descendent to decide whether they want to call +super+ and trigger the inherited callbacks.
+  #
+  # *IMPORTANT:* In order for inheritance to work for the callback queues, you must specify the callbacks
+  # before specifying the associations. Otherwise, you might trigger the loading of a child before the 
+  # parent has registered the callbacks and they won't be inherited.
+  #
+  # == Types of callbacks
+  #
+  # There are four types of callbacks accepted by the callback macros: Method references (symbol), 
+  # callback objects, inline methods (using a proc), and inline eval methods (using a string). Method 
+  # references and callback objects are the recommended approaches, inline methods using a proc are 
+  # sometimes appropriate (such as for creating mix-ins), and inline eval methods are deprecated.
+  #
+  # The method reference callbacks work by specifying a protected or private method available in the 
+  # object, like this:
+  #
+  #   class Topic < CouchFoo::Base
+  #     before_destroy :delete_parents
+  #
+  #     private
+  #       def delete_parents
+  #         self.class.delete_all "parent_id = #{id}"
+  #       end
+  #   end
+  #
+  # The callback objects have methods named after the callback called with the record as the only
+  # parameter, such as:
+  #
+  #   class BankAccount < CouchFoo::Base
+  #     before_save      EncryptionWrapper.new("credit_card_number")
+  #     after_save       EncryptionWrapper.new("credit_card_number")
+  #     after_initialize EncryptionWrapper.new("credit_card_number")
+  #   end
+  #
+  #   class EncryptionWrapper
+  #     def initialize(attribute)
+  #       @attribute = attribute
+  #     end
+  #
+  #     def before_save(record)
+  #       record.credit_card_number = encrypt(record.credit_card_number)
+  #     end
+  #
+  #     def after_save(record)
+  #       record.credit_card_number = decrypt(record.credit_card_number)
+  #     end
+  #
+  #     alias_method :after_find, :after_save
+  #
+  #     private
+  #       def encrypt(value)
+  #         # Secrecy is committed
+  #       end
+  #
+  #       def decrypt(value)
+  #         # Secrecy is unveiled
+  #       end
+  #   end
+  #
+  # So you specify the object you want messaged on a given callback. When that callback is triggered, 
+  # the object has a method by the name of the callback messaged.
+  #
+  # The callback macros usually accept a symbol for the method they're supposed to run, but you can 
+  # also pass a "method string", which will then be evaluated within the binding of the callback. Example:
+  #
+  #   class Topic < CouchFoo::Base
+  #     before_destroy 'self.class.delete_all ":parent_id => #{id}"'
+  #   end
+  #
+  # Notice that single quotes (') are used so the <tt>#{id}</tt> part isn't evaluated until the callback 
+  # is triggered. Also note that these inline callbacks can be stacked just like the regular ones:
+  #
+  #   class Topic < CouchFoo::Base
+  #     before_destroy 'self.class.delete_all ":parent_id => #{id}"',
+  #                    'puts "Evaluated after parents are destroyed"'
+  #   end
+  #
+  # == The +after_find+ and +after_initialize+ exceptions
+  #
+  # Because +after_find+ and +after_initialize+ are called for each object found and instantiated by 
+  # a finder, such as <tt>Base.find(:all)</tt>, we've had to implement a simple performance constraint 
+  # (50% more speed on a simple test case). Unlike all the other callbacks, +after_find+ and
+  # +after_initialize+ will only be run if an explicit implementation is defined (<tt>def after_find</tt>). 
+  # In that case, all of the callback types will be called.
+  #
+  # == <tt>before_validation*</tt> returning statements
+  #
+  # If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will
+  # be aborted and <tt>Base#save</tt> will return +false+. If Base#save! is called it will raise a 
+  # RecordNotSaved exception.  Nothing will be appended to the errors object.
+  #
+  # == Canceling callbacks
+  #
+  # If a <tt>before_*</tt> callback returns +false+, all the later callbacks and the associated action 
+  # are cancelled. If an <tt>after_*</tt> callback returns +false+, all the later callbacks are cancelled. 
+  # Callbacks are generally run in the order they are defined, with the exception of callbacks defined as 
+  # methods on the model, which are called last.
+  module Callbacks
+    CALLBACKS = %w(
+      after_find after_initialize before_save after_save before_create after_create before_update after_update 
+      before_validation after_validation before_validation_on_create after_validation_on_create 
+      before_validation_on_update after_validation_on_update before_destroy after_destroy
+    )
+
+    def self.included(base) #:nodoc:
+      base.extend Observable
+
+      [:create_or_update, :valid?, :create, :update, :destroy].each do |method|
+        base.send :alias_method_chain, method, :callbacks
+      end
+
+      base.send :include, ActiveSupport::Callbacks
+      base.define_callbacks *CALLBACKS
+    end
+
+    # Is called _before_ <tt>Base.save</tt> (regardless of whether it's a +create+ or +update+ save).
+    def before_save() end
+
+    # Is called _after_ <tt>Base.save</tt> (regardless of whether it's a +create+ or +update+ save).
+    #
+    #  class Contact < CouchFoo::Base
+    #    after_save { logger.info( 'New contact saved!' ) }
+    #  end
+    def after_save()  end
+    def create_or_update_with_callbacks() #:nodoc:
+      return false if callback(:before_save) == false
+      result = create_or_update_without_callbacks()
+      callback(:after_save)
+      result
+    end
+    private :create_or_update_with_callbacks
+
+    # Is called _before_ <tt>Base.save</tt> on new objects that haven't been saved yet (no record exists).
+    def before_create() end
+
+    # Is called _after_ <tt>Base.save</tt> on new objects that haven't been saved yet (no record exists).
+    def after_create() end
+    def create_with_callbacks() #:nodoc:
+      return false if callback(:before_create) == false
+      result = create_without_callbacks()
+      callback(:after_create)
+      result
+    end
+    private :create_with_callbacks
+
+    # Is called _before_ <tt>Base.save</tt> on existing objects that have a record.
+    def before_update() end
+
+    # Is called _after_ <tt>Base.save</tt> on existing objects that have a record.
+    def after_update() end
+
+    def update_with_callbacks(*args) #:nodoc:
+      return false if callback(:before_update) == false
+      result = update_without_callbacks(*args)
+      callback(:after_update)
+      result
+    end
+    private :update_with_callbacks
+
+    # Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call).
+    def before_validation() end
+
+    # Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call).
+    def after_validation() end
+
+    # Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on new objects
+    # that haven't been saved yet (no record exists).
+    def before_validation_on_create() end
+
+    # Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on new objects
+    # that haven't been saved yet (no record exists).
+    def after_validation_on_create()  end
+
+    # Is called _before_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on
+    # existing objects that have a record.
+    def before_validation_on_update() end
+
+    # Is called _after_ <tt>Validations.validate</tt> (which is part of the <tt>Base.save</tt> call) on
+    # existing objects that have a record.
+    def after_validation_on_update()  end
+
+    def valid_with_callbacks? #:nodoc:
+      return false if callback(:before_validation) == false
+      if new_record? then result = callback(:before_validation_on_create) else result = callback(:before_validation_on_update) end
+      return false if result == false
+
+      result = valid_without_callbacks?
+
+      callback(:after_validation)
+      if new_record? then callback(:after_validation_on_create) else callback(:after_validation_on_update) end
+
+      return result
+    end
+
+    # Is called _before_ <tt>Base.destroy</tt>.
+    #
+    # Note: If you need to _destroy_ or _nullify_ associated records first,
+    # use the <tt>:dependent</tt> option on your associations.
+    def before_destroy() end
+
+    # Is called _after_ <tt>Base.destroy</tt> (and all the attributes have been frozen).
+    #
+    #  class Contact < CouchFoo::Base
+    #    after_destroy { |record| logger.info( "Contact #{record.id} was destroyed." ) }
+    #  end
+    def after_destroy()  end
+    def destroy_with_callbacks #:nodoc:
+      return false if callback(:before_destroy) == false
+      result = destroy_without_callbacks
+      callback(:after_destroy)
+      result
+    end
+
+    private
+      def callback(method)
+        notify(method)
+
+        result = run_callbacks(method) { |result, object| result == false }
+
+        if result != false && respond_to_without_attributes?(method)
+          result = send(method)
+        end
+
+        return result
+      end
+
+      def notify(method) #:nodoc:
+        self.class.changed
+        self.class.notify_observers(method, self)
+      end
+  end
+end

data/lib/couch_foo/database.rb

@@ -0,0 +1,157 @@
+require 'couchrest'
+
+# This class wrappers CouchRest but may ultimately replace it as only parts of the library are used
+module CouchFoo  
+  LATEST_COUCHDB_VERSION = 0.9
+  
+  class DatabaseWrapper
+    
+    attr_accessor :database, :database_version, :bulk_save_default
+    
+    def initialize(database_url, bulk_save_default, version, *args)
+      self.database = CouchRest.database(database_url)
+      self.bulk_save_default = bulk_save_default
+      self.database_version = version
+    end
+    
+    def save(doc, bulk_save = bulk_save?)
+      begin
+        response = database.save(doc, bulk_save)
+        check_response_ok(response)
+      rescue Exception => e
+        handle_exception(e)
+      end
+    end
+    
+    def delete(doc)
+      begin
+        response = database.delete(doc)
+        check_response_ok(response)
+      rescue Exception => e
+        handle_exception(e)
+      end
+    end
+    
+    def commit
+      begin
+        response = database.bulk_save
+        check_response_ok(response)
+      rescue Exception => e
+        handle_exception(e)
+      end
+    end
+
+    def get(doc)
+      begin
+        database.get(doc)
+      rescue Exception => e
+        handle_exception(e)
+      end
+    end
+    
+    def view(doc, params)
+      begin
+        database.view(doc, params)
+      rescue Exception => e
+        handle_exception(e)
+      end
+    end
+    
+    def slow_view(doc, params)
+      begin
+        database.slow_view(doc, params)
+      rescue Exception => e
+        handle_exception(e)
+      end
+    end
+    
+    # At the moment this is limited by the CouchREST bulk save limit of 50 transactions
+    def transaction(&block)
+      yield
+      commit
+    end
+    
+    def bulk_save?
+      bulk_save_default
+    end
+    
+    def version
+      database_version
+    end
+    
+    private
+    # Checks the response is ok, raises generic exception if not
+    def check_response_ok(response)
+      if response["ok"]
+        response
+      else
+        logger.error("Unexpected response from database - #{response['ok']}")
+        raise CouchFooError, "Couldn't understand database response:#{response}"
+      end
+    end
+    
+    # Raises appropriate exceptions based on error from server
+    def handle_exception(exception)
+      if exception.is_a?(RestClient::ResourceNotFound)
+        raise DocumentNotFound, "Couldn't find document"
+      elsif exception.is_a?(RestClient::RequestFailed) && exception.code == "409"
+        raise DocumentConflict, "Document has been updated whilst object loaded"
+      else
+        # We let the rest fall through as normally CouchDB setup error
+        raise exception
+      end
+    end
+  end
+  
+  module Database
+    def self.included(base)
+      base.extend ClassMethods
+      base.cattr_accessor :bulk_save_default, :instance_writer => false
+      base.class_eval "@@bulk_save_default = false"
+    end
+    
+    module ClassMethods
+      # Get the current database
+      def database
+        if @active_database.nil?
+          if self == CouchFoo::Base
+            raise Exception, "No databases setup"
+          else
+            superclass.database
+          end
+        else
+          @active_database
+        end
+      end
+
+      # Set the database to be used with this model.  This honours inheritence so sub-classes can use
+      # different databases from their parents.  As such if you only use one database for your
+      # application then only one call is required to CouchFoo::Base for initial setup.
+      #
+      # For ultra-scalability and using a different database for each user, perform the set_database
+      # call on the CouchFoo::Base object on a before_filter using the session information to
+      # determine the database to connect to.  For example:
+      #
+      # class ApplicationController < ActionController::Base
+      #   before_filter :set_user_database
+      #
+      #   def set_user_database
+      #     CouchFoo::Base.set_database("http://localhost:5984/user#{session[:user]}")
+      #   end
+      # end
+      #
+      # As the need grows to move user databases onto different servers (sharding) then you can
+      # either:<ul>
+      # <li>create a lookup file/database that maps user_id to database location</li>
+      # <li>locate the database servers behind apache (or equivalent) using rewrite rules.  The server
+      #     knows which users live on which physical machine and rewrites accordingly.  Thus only one 
+      #     database url is required at the application level)</li>
+      # </ul>
+      #
+      # NOTE: This will work best on domains where there is little overlap between users data (eg basecamp)
+      def set_database(url, version = LATEST_COUCHDB_VERSION, bulk_save = bulk_save_default)
+        @active_database = DatabaseWrapper.new(url, bulk_save, version)
+      end
+    end # ClassMethods
+  end
+end