kristjan-st-elsewhere 0.1.6

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Brian A. Doll
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,64 @@
+=== St. Elsewhere
+
+An ActiveRecord plugin to support relationships across different databases
+
+http://emphaticsolutions.com/images/st.elsewhere.jpg
+
+=== The Scenario
+
+For a variety of reasons, you might find yourself supporting multiple databases in your Rails application.  Maybe you're connecting to a legacy database for a few models.  Perhaps you have divided your Rails application into two parts, one database for your online catalog system and another for transactional data.  Multiple database connections in Rails is {nothing new.}[http://www.google.com/search?hl=en&source=hp&q=multiple+database+connections+rails&aq=f&oq=&aqi=g4]
+
+=== The Problem
+
+While there may be great benefits to connecting to multiple databases in your app, there are also costs.  One example is that <b><tt>has_many :children, :through => parent_children</tt></b> may not work.
+
+If your database connections are available on the same host {you can prefix your ActiveRecord table names with the database name}[http://gist.github.com/239853].
+
+If your database connections are on two different hosts, no JOINs can save you and you'll need to implement your relationships in code.
+
+=== The Solution
+
+St. Elsewhere adds a new class method (<tt>has_many_elsewhere</tt>) to support basic association methods across different database connections for ActiveRecord models.
+
+Example:
+
+http://emphaticsolutions.com/images/has_many_elsewhere.png
+
+  class Hospital < AcitveRecord::Base
+    has_many :hospital_doctors
+    has_many_elsewhere :doctors, :through => :hospital_doctors
+  end
+
+  class HospitalDoctor < ActiveRecord::Base
+    belongs_to :hospital
+    belongs_to :doctor
+  end
+
+  class TransactionalBase < ActiveRecord::Base
+    self.abstract_class = true
+    establish_connection "#{RAILS_ENV}-transactional"
+  end
+
+  class Doctor < TransactionalBase
+    has_many :hospital_doctors
+    has_many :hospitals, :through => :hospital_doctors
+  end
+
+  The following conventional methods are available for Hospital:
+  hospital.doctors, hospital.doctors=, hospital.doctor_ids, hospital.doctor_ids=
+
+=== Inefficiencies
+
+<tt>has_many_elsewhere</tt> is certainly much less efficient than a comparable has_many relationship.  <tt>has_many :through</tt> relationships use SQL JOINs which while efficient, do not work across multiple database connections.  St. Elsewhere implements much of the same resulting API methods in code, using less efficient SQL.
+
+=== Install from gemcutter
+
+  gem install st-elsewhere
+
+=== Roadmap
+
+Currently st-elsewhere is implemented as a basic ruby module that implements some of the basic functionality of has_many :through relationships in ActiveRecord.  A much more robust implementation would be to create an ActiveRecord association proxy, like HasManyThroughAssociation, that emulates the same API and could be integrated into the standard has_many class method.  I will likely be waiting for Rails 3 to be released (and thus the new base ORM implementation) before attempting the association proxy route.
+
+=== Thanks
+
+Thanks to {James Reynolds}[http://drtoast.com/] for the great name and  thanks to {Tanner Donovan}[http://github.com/ttdonovan] for patches and being the first production customer.

data/Rakefile

@@ -0,0 +1,39 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "kristjan-st-elsewhere"
+    gem.summary = %Q{St. Elsewhere supports has_many :through relationships across different databases}
+    gem.description = %Q{This gem provides has_many_elsewhere, an ActiveRecord class method to support many to many relationships in Rails applications, across multiple database connections.}
+    gem.email = ["brian@emphaticsolutions.com", "kristjan@gmail.com"]
+    gem.homepage = "http://github.com/kristjan/st-elsewhere"
+    gem.authors = ["Brian Doll", "Kristján Pétursson"]
+    gem.add_development_dependency "rr", ">= 0"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/*test.rb'
+  test.verbose = true
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "st-elsewhere #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.6

data/changelog.rdoc

@@ -0,0 +1,9 @@
+0.1.5 "Ed Flanders"
+ - This is the first acceptable production release of st-elsewhere.
+ - Implements:
+   - has_many_elsewhere :association, :through => :through_association
+ - Provides:
+   - ARKlass#associations
+   - ARKlass#association_ids
+   - ARKlass#associations=
+   - ARKlass#association_ids=

data/kristjan-st-elsewhere.gemspec

@@ -0,0 +1,53 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{kristjan-st-elsewhere}
+  s.version = "0.1.6"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brian Doll", "Kristj\303\241n P\303\251tursson"]
+  s.date = %q{2010-05-26}
+  s.description = %q{This gem provides has_many_elsewhere, an ActiveRecord class method to support many to many relationships in Rails applications, across multiple database connections.}
+  s.email = ["brian@emphaticsolutions.com", "kristjan@gmail.com"]
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "changelog.rdoc",
+     "kristjan-st-elsewhere.gemspec",
+     "lib/st-elsewhere.rb",
+     "tasks/st-elsewhere_tasks.rake",
+     "test/st-elsewhere_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/kristjan/st-elsewhere}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{St. Elsewhere supports has_many :through relationships across different databases}
+  s.test_files = [
+    "test/st-elsewhere_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rr>, [">= 0"])
+    else
+      s.add_dependency(%q<rr>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rr>, [">= 0"])
+  end
+end
+

data/lib/st-elsewhere.rb

@@ -0,0 +1,132 @@
+module StElsewhere
+
+  # Specifies a one-to-many association across database connections.
+  # This is currently an incomplete implementation and does not yet use all of the options supported by has_many
+  #
+  # The following methods for retrieval and query of collections of associated objects will be added:
+  #
+  # [collection=objects]
+  #   Replaces the collections content by deleting and adding objects as appropriate.
+  # [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.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>has_many :clients</tt> would add among others <tt>clients.empty?</tt>.)
+  #
+  # === Example
+  #
+  # Example: A Firm class declares <tt>has_many_elsewhere :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#client_ids</tt>
+  # * <tt>Firm#client_ids=</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>)
+  #
+  # === Supported options
+  # [:through]
+  #   Specifies a Join Model through which to perform the query. You can only use a <tt>:through</tt> query through a
+  #   <tt>belongs_to</tt> <tt>has_one</tt> or <tt>has_many</tt> association on the join model.
+  # [:class_name]
+  #   Specifies a the class name to use for the association, rather than
+  #   inferring from the association name.
+  #
+  # Option examples:
+  #   has_many_elsewhere :subscribers, :through => :subscriptions
+  #   has_many_elsewhere :subscribers, :through => :subscriptions, :class_name => 'User'
+  def has_many_elsewhere(association_id, options = {}, &extension)
+    association_class = (options[:class_name] || association_id.to_s).classify.constantize
+    through = options[:through]
+    raise ArgumentError.new("You must include :through => association for has_many_elsewhere") if not through
+    collection_accessor_methods_elsewhere(association_id, association_class, through)
+  end
+
+  # Dynamically adds all accessor methods for the has_many_elsewhere association
+  def collection_accessor_methods_elsewhere(association_id, association_class, through)
+    association_singular = association_id.to_s.singularize
+    association_plural   = association_id.to_s
+    through_association_singular = through.to_s.singularize
+    my_class       = self
+    my_foreign_key = self.to_s.foreign_key
+    target_association_class = association_class
+    target_association_foreign_key = association_class.to_s.foreign_key
+
+    # Hospital#doctor_ids
+    define_method("#{association_singular}_ids") do
+      self.send("#{association_plural}").map{|a| a.id}
+    end
+
+    # Hospital#doctors
+    define_method("#{association_plural}") do
+      through_class = through.to_s.singularize.camelize.constantize
+      through_association_ids = self.send("#{through.to_s.singularize}_ids")
+      through_associations = through_class.find(through_association_ids)
+      through_associations.collect{|through_association| through_association.send("#{association_singular}")} || []
+    end
+
+    # Hospital#doctors=
+    define_method("#{association_plural}=") do |new_associations|
+      through_class        = through.to_s.singularize.camelize.constantize
+      current_associations = self.send("#{association_singular}_ids")
+      desired_associations = self.class.associations_to_association_ids(new_associations)
+
+      removed_target_associations = current_associations - desired_associations
+      new_target_associations     = desired_associations - current_associations
+
+      self.send("remove_#{association_singular}_associations", through_class, removed_target_associations)
+      self.send("add_#{association_singular}_associations", through_class, association_id, new_target_associations)
+    end
+
+    # Hospital#doctor_ids=
+    define_method("#{association_singular}_ids=") do |new_association_ids|
+      self.send("#{association_plural}=", new_association_ids)
+    end
+
+    # Hospital#remove_doctor_associations (private)
+    define_method("remove_#{association_singular}_associations") do |through_class, removed_target_associations|
+      association_instances_to_remove =
+        through_class.send("find_all_by_#{my_foreign_key}_and_#{target_association_foreign_key}", self.id, removed_target_associations)
+      through_class.delete(association_instances_to_remove)
+    end
+
+    # Hospital#add_doctor_associations (private)
+    define_method("add_#{association_singular}_associations") do |through_class, association_id, target_association_ids|
+      targets_to_add = target_association_class.find(target_association_ids)
+      targets_to_add.each do |target_association|
+        new_association = through_class.new(my_foreign_key => self.id, target_association_foreign_key => target_association.id)
+        new_association.save
+      end
+    end
+
+    private "remove_#{association_singular}_associations".to_sym, "add_#{association_singular}_associations".to_sym
+
+  end
+
+  def associations_to_association_ids(associations)
+    ids = []
+    if associations && !associations.empty?
+      associations.reject!{|a| a.to_s.empty? }
+      association_class = associations.first.class.to_s
+      ids = case association_class
+            when "String"
+              associations.map{|a| a.to_i }
+            when "Fixnum"
+              associations
+            else
+              associations.map{|a| a.id}
+      end
+    end
+    ids
+  end
+
+  private :collection_accessor_methods_elsewhere
+
+end
+
+ActiveRecord::Base.extend StElsewhere

data/tasks/st-elsewhere_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :foo do
+#   # Task goes here
+# end

data/test/st-elsewhere_test.rb

@@ -0,0 +1,92 @@
+# These tests are insanely incomplete.  Testing a module like this without
+# depending on an encompasing Rails application is quite difficult.  These
+# tests use mocks on the objects under test, which feels almost useless.
+# I may consider publishing an accompanyhing Rails application with a test
+# suite that tests this module in a usable state.
+
+require 'test_helper'
+require 'st-elsewhere'
+
+class Doctor < Struct.new :id, :name
+end
+
+class HospitalDoctor < Struct.new :id, :doctor_id, :hospital_id
+  attr_accessor :doctor, :hospital
+end
+
+class HospitalDean < Struct.new :id, :dean_id, :hospital_id
+  attr_accessor :dean, :hospital
+end
+
+class Hospital < Struct.new :id, :name
+  extend StElsewhere
+  has_many_elsewhere :doctors, :through => :hospital_doctors
+  has_many_elsewhere :deans,   :through => :hospital_deans, :class_name => 'Doctor'
+end
+
+class StElsewhereTest < Test::Unit::TestCase
+
+  def setup
+    @hospital = Hospital.new
+    @hospital.id = 1
+    @hospital.name = "St. Elsewhere"
+
+    @doctor  = Doctor.new
+    @doctor.id = 1
+    @doctor.name = "Dr. Foo"
+
+    @doctor2 = Doctor.new
+    @doctor2.id = 2
+    @doctor2.name = "Dr. Bar"
+
+    @dean = Doctor.new
+    @dean.id = 3
+    @dean.name = "Lida Cuddy"
+
+    @hospital_doctor  = HospitalDoctor.new
+    @hospital_doctor.id = 1
+    @hospital_doctor.doctor_id = @doctor.id
+    @hospital_doctor.hospital_id = @hospital.id
+
+    @hospital_doctor2 = HospitalDoctor.new
+    @hospital_doctor2.id = 2
+    @hospital_doctor2.doctor_id = @doctor2.id
+    @hospital_doctor2.hospital_id = @hospital.id
+
+    @hospital_dean = HospitalDean.new
+    @hospital_dean.id = 1
+    @hospital_dean.dean_id = @dean.id
+    @hospital_dean.hospital_id = @hospital.id
+  end
+
+  def test_basic_obj_setup
+    assert "St. Elsewhere".eql?(@hospital.name)
+    assert @hospital.respond_to? :doctors
+    assert @hospital.respond_to? :doctors=
+    assert @hospital.respond_to? :doctor_ids
+    assert @hospital.respond_to? :doctor_ids=
+  end
+
+  def test_basic_functionality
+    mock(@hospital_doctor).doctor {@doctor}
+    mock(@hospital_doctor2).doctor {@doctor2}
+    mock(HospitalDoctor).find([1,2]) {[@hospital_doctor, @hospital_doctor2]}
+    mock(@hospital).hospital_doctor_ids {[@hospital_doctor.id, @hospital_doctor2.id]}
+
+    assert @hospital.doctors.eql?([@doctor, @doctor2])
+  end
+
+  def test_manual_class_name
+    assert @hospital.respond_to? :deans
+    assert @hospital.respond_to? :deans=
+    assert @hospital.respond_to? :dean_ids
+    assert @hospital.respond_to? :dean_ids=
+
+    mock(@hospital_dean).dean {@dean}
+    mock(HospitalDean).find([1]) {[@hospital_dean]}
+    mock(@hospital).hospital_dean_ids {[@hospital_dean.id]}
+
+    assert @hospital.deans.eql?([@dean])
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'test/unit'
+require 'active_record'
+require 'rr'
+
+class Test::Unit::TestCase
+  include RR::Adapters::TestUnit
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification 
+name: kristjan-st-elsewhere
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 6
+  version: 0.1.6
+platform: ruby
+authors: 
+- Brian Doll
+- "Kristj\xC3\xA1n P\xC3\xA9tursson"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-26 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rr
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: This gem provides has_many_elsewhere, an ActiveRecord class method to support many to many relationships in Rails applications, across multiple database connections.
+email: 
+- brian@emphaticsolutions.com
+- kristjan@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- changelog.rdoc
+- kristjan-st-elsewhere.gemspec
+- lib/st-elsewhere.rb
+- tasks/st-elsewhere_tasks.rake
+- test/st-elsewhere_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/kristjan/st-elsewhere
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: St. Elsewhere supports has_many :through relationships across different databases
+test_files: 
+- test/st-elsewhere_test.rb
+- test/test_helper.rb