tenacity 0.1.0

data/lib/tenacity/class_methods.rb

@@ -0,0 +1,226 @@
+module Tenacity
+  # Associations are a set of macro-like class methods for tying objects together through
+  # their ids. They express relationships like "Project has one Project Manager"
+  # or "Project belongs to a Portfolio". Each macro adds a number of methods to the
+  # class which are specialized according to the collection or association symbol and the
+  # options hash. It works much the same way as Ruby's own <tt>attr*</tt>
+  # methods.
+  #
+  #   class Project
+  #     include Tenacity
+  #
+  #     t_belongs_to    :portfolio
+  #     t_has_one       :project_manager
+  #     t_has_many      :milestones
+  #   end
+  #
+  # The project class now has the following methods (and more) to ease the traversal and
+  # manipulation of its relationships:
+  # * <tt>Project#portfolio, Project#portfolio=(portfolio), Project#portfolio.nil?</tt>
+  # * <tt>Project#project_manager, Project#project_manager=(project_manager), Project#project_manager.nil?,</tt>
+  # * <tt>Project#milestones.empty?, Project#milestones.size, Project#milestones, Project#milestones<<(milestone), Project#milestones.delete(milestone)</tt>
+  #
+  # == Cardinality and associations
+  #
+  # Tenacity associations can be used to describe one-to-one and one-to-many
+  # relationships between models. Each model uses an association to describe its role in
+  # the relation. The +t_belongs_to+ association is always used in the model that has
+  # the foreign key.
+  #
+  # === One-to-one
+  #
+  # Use +t_has_one+ in the base, and +t_belongs_to+ in the associated model.
+  #
+  #   class Employee < ActiveRecord::Base
+  #     include Tenacity
+  #     t_has_one :office
+  #   end
+  #
+  #   class Office
+  #     include MongoMapper::Document
+  #     include Tenacity
+  #     t_belongs_to :employee     # foreign key - employee_id
+  #   end
+  #
+  # === One-to-many
+  #
+  # Use +t_has_many+ in the base, and +t_belongs_to+ in the associated model.
+  #
+  #   class Manager < ActiveRecord::Base
+  #     include Tenacity
+  #     t_has_many :employees
+  #   end
+  #
+  #   class Employee
+  #     include MongoMapper::Document
+  #     include Tenacity
+  #     t_belongs_to :manager     # foreign key - manager_id
+  #   end
+  #
+  # == Caching
+  #
+  # All of the methods are built on a simple caching principle that will keep the result
+  # of the last query around unless specifically instructed not to. The cache is even
+  # shared across methods to make it even cheaper to use the macro-added methods without
+  # worrying too much about performance at the first go.
+  #
+  #   project.milestones             # fetches milestones from the database
+  #   project.milestones.size        # uses the milestone cache
+  #   project.milestones.empty?      # uses the milestone cache
+  #   project.milestones(true).size  # fetches milestones from the database
+  #   project.milestones             # uses the milestone cache
+  #
+  module ClassMethods
+
+    # Specifies a one-to-one association with another class. This method should only be used
+    # if the other class contains the foreign key. If the current class contains the foreign key,
+    # then you should use +t_belongs_to+ instead.
+    #
+    # The following methods for retrieval and query of a single associated object will be added:
+    #
+    # [association(force_reload = false)]
+    #   Returns the associated object. +nil+ is returned if none is found.
+    # [association=(associate)]
+    #   Assigns the associate object, extracts the primary key, sets it as the foreign key,
+    #   and saves the associate object.
+    #
+    # (+association+ is replaced with the symbol passed as the first argument, so
+    # <tt>t_has_one :manager</tt> would add among others <tt>manager.nil?</tt>.)
+    #
+    # === Example
+    #
+    # An Account class declares <tt>t_has_one :beneficiary</tt>, which will add:
+    # * <tt>Account#beneficiary</tt> (similar to <tt>Beneficiary.find(:first, :conditions => "account_id = #{id}")</tt>)
+    # * <tt>Account#beneficiary=(beneficiary)</tt> (similar to <tt>beneficiary.account_id = account.id; beneficiary.save</tt>)
+    #
+    def t_has_one(association_id, args={})
+      extend(HasOne::ClassMethods)
+      initialize_has_one_association(association_id)
+
+      define_method(association_id) do |*params|
+        get_associate(association_id, params) do
+          has_one_associate(association_id)
+        end
+      end
+
+      define_method("#{association_id}=") do |associate|
+        set_associate(association_id, associate) do
+          set_has_one_associate(association_id, associate)
+        end
+      end
+    end
+
+    # Specifies a one-to-one association with another class. This method should only be used
+    # if this class contains the foreign key. If the other class contains the foreign key,
+    # then you should use +t_has_one+ instead.
+    #
+    # Methods will be added for retrieval and query for a single associated object, for which
+    # this object holds an id:
+    #
+    # [association(force_reload = false)]
+    #   Returns the associated object. +nil+ is returned if none is found.
+    # [association=(associate)]
+    #   Assigns the associate object, extracts the primary key, and sets it as the foreign key.
+    #
+    # (+association+ is replaced with the symbol passed as the first argument, so
+    # <tt>t_belongs_to :author</tt> would add among others <tt>author.nil?</tt>.)
+    #
+    # === Example
+    #
+    # A Post class declares <tt>t_belongs_to :author</tt>, which will add:
+    # * <tt>Post#author</tt> (similar to <tt>Author.find(author_id)</tt>)
+    # * <tt>Post#author=(author)</tt> (similar to <tt>post.author_id = author.id</tt>)
+    #
+    def t_belongs_to(association_id, args={})
+      extend(BelongsTo::ClassMethods)
+      initialize_belongs_to_association(association_id)
+
+      define_method(association_id) do |*params|
+        get_associate(association_id, params) do
+          belongs_to_associate(association_id)
+        end
+      end
+
+      define_method("#{association_id}=") do |associate|
+        set_associate(association_id, associate) do
+          set_belongs_to_associate(association_id, associate)
+        end
+      end
+    end
+
+    # Specifies a one-to-many association. The following methods for retrieval and query of
+    # collections of associated objects will be added:
+    #
+    # [collection(force_reload = false)]
+    #   Returns an array of all the associated objects.
+    #   An empty array is returned if none are found.
+    # [collection<<(object, ...)]
+    #   Adds one or more objects to the collection by setting their foreign keys to the collection's primary key.
+    #   Note that this operation does not update the association until the parent object is saved.
+    # [collection.delete(object, ...)]
+    #   Removes one or more objects from the collection.
+    # [collection=objects]
+    #   Replaces the collections content by setting it to the list of specified objects.
+    # [collection_singular_ids]
+    #   Returns an array of the associated objects' ids
+    # [collection_singular_ids=ids]
+    #   Replace the collection with the objects identified by the primary keys in +ids+.
+    # [collection.clear]
+    #   Removes every object from the collection.
+    # [collection.empty?]
+    #   Returns +true+ if there are no associated objects.
+    # [collection.size]
+    #   Returns the number of associated objects.
+    #
+    # (*Note*: +collection+ is replaced with the symbol passed as the first argument, so
+    # <tt>t_has_many :clients</tt> would add among others <tt>clients.empty?</tt>.)
+    #
+    # === Example
+    #
+    # Example: A Firm class declares <tt>t_has_many :clients</tt>, which will add:
+    # * <tt>Firm#clients</tt> (similar to <tt>Clients.find :all, :conditions => ["firm_id = ?", id]</tt>)
+    # * <tt>Firm#clients<<</tt>
+    # * <tt>Firm#clients.delete</tt>
+    # * <tt>Firm#clients=</tt>
+    # * <tt>Firm#client_ids</tt>
+    # * <tt>Firm#client_ids=</tt>
+    # * <tt>Firm#clients.clear</tt>
+    # * <tt>Firm#clients.empty?</tt> (similar to <tt>firm.clients.size == 0</tt>)
+    # * <tt>Firm#clients.size</tt> (similar to <tt>Client.count "firm_id = #{id}"</tt>)
+    #
+    def t_has_many(association_id, args={})
+      extend(HasMany::ClassMethods)
+      initialize_has_many_association(association_id)
+
+      define_method(association_id) do |*params|
+        get_associate(association_id, params) do
+          has_many_associates(association_id)
+        end
+      end
+
+      define_method("#{association_id}=") do |associates|
+        set_associate(association_id, associates)
+      end
+
+      define_method("#{ActiveSupport::Inflector.singularize(association_id.to_s)}_ids") do
+        has_many_associate_ids(association_id)
+      end
+
+      define_method("#{ActiveSupport::Inflector.singularize(association_id.to_s)}_ids=") do |associate_ids|
+        set_has_many_associate_ids(association_id, associate_ids)
+      end
+
+      private
+
+      define_method(:_t_save_without_callback) do
+        save_without_callback
+      end
+    end
+
+    def associate_class(association_id)
+      Kernel.const_get(association_id.to_s.singularize.camelcase.to_sym)
+    end
+
+  end
+end
+

data/lib/tenacity/instance_methods.rb

@@ -0,0 +1,31 @@
+module Tenacity
+  module InstanceMethods #:nodoc:
+
+    private
+
+    def get_associate(association_id, params)
+      _t_reload
+      force_reload = params.first unless params.empty?
+      value = instance_variable_get ivar_name(association_id)
+      if value.nil? || force_reload
+        value = yield
+        instance_variable_set ivar_name(association_id), value
+      end
+      value
+    end
+
+    def set_associate(association_id, associate)
+      yield if block_given?
+      instance_variable_set ivar_name(association_id), associate
+    end
+
+    def ivar_name(association_id)
+      "@_t_" + association_id.to_s
+    end
+
+    def associate_class(association_id)
+      self.class.associate_class(association_id)
+    end
+
+  end
+end

data/lib/tenacity/orm_ext/activerecord.rb

@@ -0,0 +1,116 @@
+# Tenacity relationships on ActiveRecord objects require that certain columns
+# exist on the associated table, and that join tables exist for one-to-many
+# relationships.  Take the following class for example:
+#
+#   class Car < ActiveRecord::Base
+#     include Tenacity
+#
+#     t_has_many    :wheels
+#     t_has_one     :dashboard
+#     t_belongs_to  :driver
+#   end
+#
+#
+# == t_belongs_to
+#
+# The +t_belongs_to+ association requires that a property exist in the table
+# to hold the id of the assoicated object.
+#
+#   create_table :cars do |t|
+#     t.string :driver_id
+#   end
+#
+#
+# == t_has_one
+#
+# The +t_has_one+ association requires no special column in the table, since
+# the associated object holds the foreign key.
+#
+#
+# == t_has_many
+#
+# The +t_has_many+ association requires that a join table exist to store the
+# associations.  The name of the join table follows ActiveRecord conventions.
+# The name of the join table in this example would be cars_wheels, since cars
+# comes before wheels when shorted alphabetically.
+#
+#   create_table :cars_wheels do |t|
+#     t.integer :car_id
+#     t.string :wheel_id
+#   end
+#
+begin
+  require 'active_record'
+
+  module ActiveRecord
+    class Base #:nodoc:
+
+      def self._t_find(id)
+        find_by_id(id)
+      end
+
+      def self._t_find_bulk(ids)
+        return [] if ids.nil? || ids.empty?
+        find(:all, :conditions => ["id in (?)", ids])
+      end
+
+      def self._t_find_first_by_associate(property, id)
+        find(:first, :conditions => ["#{property} = ?", id.to_s])
+      end
+
+      def self._t_find_all_by_associate(property, id)
+        find(:all, :conditions => ["#{property} = ?", id.to_s])
+      end
+
+      def self._t_initialize_has_many_association(association_id)
+        after_save { |record| record.class._t_save_associates(record, association_id) }
+      end
+
+      def self._t_initialize_belongs_to_association(association_id)
+        before_save { |record| record.class._t_stringify_belongs_to_value(record, association_id) }
+      end
+
+      def _t_reload
+        reload
+      end
+
+      def _t_clear_associates(association_id)
+        t_join_table_name = self.class._t_join_table_name(association_id)
+        self.connection.execute("delete from #{t_join_table_name} where #{self.class._t_my_id_column} = #{self.id}")
+      end
+
+      def _t_associate_many(association_id, associate_ids)
+        t_join_table_name = self.class._t_join_table_name(association_id)
+        values = associate_ids.map { |associate_id| "(#{self.id}, '#{associate_id}')" }.join(',')
+
+        self.transaction do
+          _t_clear_associates(association_id)
+          self.connection.execute("insert into #{t_join_table_name} (#{self.class._t_my_id_column}, #{self.class._t_associate_id_column(association_id)}) values #{values}")
+        end
+      end
+
+      def _t_get_associate_ids(association_id)
+        t_join_table_name = self.class._t_join_table_name(association_id)
+        rows = self.connection.execute("select #{self.class._t_associate_id_column(association_id)} from #{t_join_table_name} where #{self.class._t_my_id_column} = #{self.id}")
+        ids = []; rows.each { |r| ids << r[0] }; ids
+      end
+
+      private
+
+      def self._t_my_id_column
+        table_name.singularize + '_id'
+      end
+
+      def self._t_associate_id_column(association_id)
+        association_id.to_s.singularize + '_id'
+      end
+
+      def self._t_join_table_name(association_id)
+        association_id.to_s < table_name ? "#{association_id}_#{table_name}" : "#{table_name}_#{association_id}"
+      end
+
+    end
+  end
+rescue LoadError
+  # ActiveRecord not available
+end

data/lib/tenacity/orm_ext/couchrest/couchrest_extended_document.rb

@@ -0,0 +1,45 @@
+# Tenacity relationships on CouchRest objects require no special keys
+# defined on the object.  Tenacity will define the keys that it needs
+# to support the relationships.  Take the following class for example:
+#
+#   class Car < CouchRest::ExtendedDocument
+#     include Tenacity
+#
+#     t_has_many    :wheels
+#     t_has_one     :dashboard
+#     t_belongs_to  :driver
+#   end
+#
+# == t_belongs_to
+#
+# The +t_belongs_to+ association will define a property named after the association.
+# The example above will create a property named <tt>:driver_id</tt>
+#
+#
+# == t_has_one
+#
+# The +t_has_one+ association will not define any new properties on the object, since
+# the associated object holds the foreign key.  If the CouchRest::ExtendedDocument class
+# is the target of a t_has_one association from another class, then a property
+# named after the association will be created on the CouchRest::ExtendedDocument object to
+# hold the foreign key to the other object.
+#
+#
+# == t_has_many
+#
+# The +t_has_many+ association will define a property named after the association.
+# The example above will create a property named <tt>:wheels_ids</tt>
+#
+
+begin
+  require 'couchrest'
+
+  module CouchRest
+    class ExtendedDocument #:nodoc:
+      include CouchRest::TenacityInstanceMethods
+      extend CouchRest::TenacityClassMethods
+    end
+  end
+rescue LoadError
+  # CouchRest::ExtendedDocument not available
+end

data/lib/tenacity/orm_ext/couchrest/couchrest_model.rb

@@ -0,0 +1,46 @@
+# Tenacity relationships on CouchRest objects require no special keys
+# defined on the object.  Tenacity will define the keys that it needs
+# to support the relationships.  Take the following class for example:
+#
+#   class Car < CouchRest::Model::Base
+#     include Tenacity
+#
+#     t_has_many    :wheels
+#     t_has_one     :dashboard
+#     t_belongs_to  :driver
+#   end
+#
+# == t_belongs_to
+#
+# The +t_belongs_to+ association will define a property named after the association.
+# The example above will create a property named <tt>:driver_id</tt>
+#
+#
+# == t_has_one
+#
+# The +t_has_one+ association will not define any new properties on the object, since
+# the associated object holds the foreign key.  If the CouchRest::Model class
+# is the target of a t_has_one association from another class, then a property
+# named after the association will be created on the CouchRest::Model object to
+# hold the foreign key to the other object.
+#
+#
+# == t_has_many
+#
+# The +t_has_many+ association will define a property named after the association.
+# The example above will create a property named <tt>:wheels_ids</tt>
+#
+begin
+  require 'couchrest'
+
+  module CouchRest
+    module Model
+      class Base
+        include CouchRest::TenacityInstanceMethods
+        extend CouchRest::TenacityClassMethods
+      end
+    end
+  end
+rescue LoadError
+  # CouchRest::Model not available
+end

data/lib/tenacity/orm_ext/couchrest/tenacity_class_methods.rb

@@ -0,0 +1,52 @@
+module CouchRest
+  module TenacityClassMethods
+    def _t_find(id)
+      get(id)
+    end
+
+    def _t_find_bulk(ids)
+      return [] if ids.nil? || ids.empty?
+
+      docs = []
+      result = database.get_bulk ids
+      result['rows'].each do |row|
+        docs << (row['doc'].nil? ? nil : create_from_database(row['doc']))
+      end
+      docs.reject { |doc| doc.nil? }
+    end
+
+    def _t_find_first_by_associate(property, id)
+      self.send("by_#{property}", :key => id.to_s).first
+    end
+
+    def _t_find_all_by_associate(property, id)
+      self.send("by_#{property}", :key => id.to_s)
+    end
+
+    def _t_initialize_has_many_association(association_id)
+      unless self.respond_to?(has_many_property_name(association_id))
+        property has_many_property_name(association_id), :type => [String]
+        view_by has_many_property_name(association_id)
+        after_save { |record| record.class._t_save_associates(record, association_id) if record.class.respond_to?(:_t_save_associates) }
+      end
+    end
+
+    def _t_initialize_belongs_to_association(association_id)
+      property_name = "#{association_id}_id"
+      unless self.respond_to?(property_name)
+        property property_name, :type => String
+        view_by property_name
+        before_save { |record| _t_stringify_belongs_to_value(record, association_id) if self.respond_to?(:_t_stringify_belongs_to_value) }
+      end
+    end
+
+    def _t_initialize_has_one_association(association_id)
+      property_name = "#{association_id}_id"
+      unless self.respond_to?(property_name)
+        property property_name, :type => String
+        view_by property_name
+        before_save { |record| _t_stringify_has_one_value(record, association_id) if self.respond_to?(:_t_stringify_has_one_value) }
+      end
+    end
+  end
+end

data/lib/tenacity/orm_ext/couchrest/tenacity_instance_methods.rb

@@ -0,0 +1,21 @@
+module CouchRest
+  module TenacityInstanceMethods
+    def _t_reload
+      new_doc = database.get(self.id)
+      self.clear
+      new_doc.each { |k,v| self[k] = new_doc[k] }
+    end
+
+    def _t_associate_many(association_id, associate_ids)
+      self.send(has_many_property_name(association_id) + '=', associate_ids.map { |associate_id| associate_id.to_s })
+    end
+
+    def _t_get_associate_ids(association_id)
+      self.send(has_many_property_name(association_id)) || []
+    end
+
+    def _t_clear_associates(association_id)
+      self.send(has_many_property_name(association_id) + '=', [])
+    end
+  end
+end

data/lib/tenacity/orm_ext/mongo_mapper.rb

@@ -0,0 +1,107 @@
+# Tenacity relationships on MongoMapper objects require no special keys
+# defined on the object.  Tenacity will define the keys that it needs
+# to support the relationships.  Take the following class for example:
+#
+#   class Car < ActiveRecord::Base
+#     include MongoMapper::Document
+#     include Tenacity
+#
+#     t_has_many    :wheels
+#     t_has_one     :dashboard
+#     t_belongs_to  :driver
+#   end
+#
+# == t_belongs_to
+#
+# The +t_belongs_to+ association will define a key named after the association.
+# The example above will create a key named <tt>:driver_id</tt>
+#
+#
+# == t_has_one
+#
+# The +t_has_one+ association will not define any new keys on the object, since
+# the associated object holds the foreign key.  If the MongoMapper class
+# is the target of a t_has_one association from another class, then a property
+# named after the association will be created on the MongoMapper object to
+# hold the foreign key to the other object.
+#
+#
+# == t_has_many
+#
+# The +t_has_many+ association will define a key named after the association.
+# The example above will create a key named <tt>:wheels_ids</tt>
+#
+module TenacityMongoMapperPlugin
+  module ClassMethods #:nodoc:
+    def _t_find(id)
+      find(id)
+    end
+
+    def _t_find_bulk(ids=[])
+      find(ids)
+    end
+
+    def _t_find_first_by_associate(property, id)
+      first(property => id.to_s)
+    end
+
+    def _t_find_all_by_associate(property, id)
+      all(property => id.to_s)
+    end
+
+    def _t_initialize_has_many_association(association_id)
+      unless self.respond_to?(has_many_property_name(association_id))
+        key has_many_property_name(association_id), Array
+      end
+      after_save { |record| _t_save_associates(record, association_id) }
+    end
+
+    def _t_initialize_belongs_to_association(association_id)
+      unless self.respond_to?("#{association_id}_id")
+        key "#{association_id}_id", String
+      end
+      before_save { |record| _t_stringify_belongs_to_value(record, association_id) }
+    end
+
+    def _t_initialize_has_one_association(association_id)
+      unless self.respond_to?("#{association_id}_id")
+        key "#{association_id}_id", String
+      end
+      before_save { |record| _t_stringify_has_one_value(record, association_id) }
+    end
+  end
+
+  module InstanceMethods #:nodoc:
+    def _t_reload
+      reload
+    rescue MongoMapper::DocumentNotFound
+      nil
+    end
+
+    def _t_associate_many(association_id, associate_ids)
+      self.send(has_many_property_name(association_id) + '=', associate_ids.map { |associate_id| associate_id.to_s })
+    end
+
+    def _t_get_associate_ids(association_id)
+      self.send(has_many_property_name(association_id))
+    end
+
+    def _t_clear_associates(association_id)
+      self.send(has_many_property_name(association_id) + '=', [])
+    end
+  end
+end
+
+module TenacityPluginAddition #:nodoc:
+  def self.included(model)
+    model.plugin TenacityMongoMapperPlugin
+  end
+end
+
+begin
+  require 'mongo_mapper'
+  MongoMapper::Document.append_inclusions(TenacityPluginAddition)
+rescue
+  # MongoMapper not available
+end
+

data/lib/tenacity/version.rb

@@ -0,0 +1,3 @@
+module Tenacity
+  VERSION = "0.1.0"
+end

data/lib/tenacity.rb

@@ -0,0 +1,27 @@
+require File.join('active_support', 'inflector')
+
+require File.join(File.dirname(__FILE__), 'tenacity', 'class_methods')
+require File.join(File.dirname(__FILE__), 'tenacity', 'instance_methods')
+require File.join(File.dirname(__FILE__), 'tenacity', 'associations', 'belongs_to')
+require File.join(File.dirname(__FILE__), 'tenacity', 'associations', 'has_many')
+require File.join(File.dirname(__FILE__), 'tenacity', 'associations', 'has_one')
+require File.join(File.dirname(__FILE__), 'tenacity', 'orm_ext', 'activerecord')
+require File.join(File.dirname(__FILE__), 'tenacity', 'orm_ext', 'couchrest', 'tenacity_class_methods')
+require File.join(File.dirname(__FILE__), 'tenacity', 'orm_ext', 'couchrest', 'tenacity_instance_methods')
+require File.join(File.dirname(__FILE__), 'tenacity', 'orm_ext', 'couchrest', 'couchrest_extended_document')
+require File.join(File.dirname(__FILE__), 'tenacity', 'orm_ext', 'couchrest', 'couchrest_model')
+require File.join(File.dirname(__FILE__), 'tenacity', 'orm_ext', 'mongo_mapper')
+
+module Tenacity #:nodoc:
+  include InstanceMethods
+
+  include BelongsTo
+  include HasMany
+  include HasOne
+
+  def self.included(model)
+    raise "Tenacity does not support the ORM used by #{model}" unless model.respond_to?(:_t_find)
+    model.extend(ClassMethods)
+  end
+end
+