st-elsewhere 0.1.0

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,50 @@
+=== 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> does not work.
+
+You'll encounter one of two errors, depending on your setup:
+* If the schemas are different, you'll see something like: <tt>ActiveRecord::StatementInvalid: Mysql::Error: Table 'appname_transactional.parent_children' doesn't exist</tt>
+* If the schemas are the same but data only exists in one schema or the other, you'll just get empty relationships.
+
+=== 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:
+
+  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.

data/Rakefile

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "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"
+    gem.homepage = "http://github.com/briandoll/st-elsewhere"
+    gem.authors = ["Brian Doll"]
+    # gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  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.0

data/init.rb

@@ -0,0 +1,2 @@
+require 'st-elsewhere'
+ActiveRecord::Base.extend StElsewhere

data/lib/st-elsewhere.rb

@@ -0,0 +1,107 @@
+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<<(object, ...)]
+  #   TODO: Adds one or more objects to the collection by setting their foreign keys to the collection's primary key.
+  # [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.
+  #
+  # Option examples:
+  #   has_many_elsewhere :subscribers, :through => :subscriptions
+  def has_many_elsewhere(association_id, options = {}, &extension)
+    association_class = 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
+    
+    # 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("#{through_association_singular}_ids")
+      removed_associations = current_associations - new_associations
+      new_associations     = new_associations - current_associations
+      
+      self.send("remove_#{association_singular}_associations", association_class, removed_associations)
+      self.send("add_#{association_singular}_associations", through_class, association_id, new_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 |association_class, associations|
+      associations.each do |association|
+        association_class.delete(association)
+      end
+    end
+
+    # Hospital#add_doctor_associations (private)
+    define_method("add_#{association_singular}_associations") do |through_class, association_id, associations|
+      myself = "#{self.class.to_s.downcase}_id"
+      my_buddy = "#{association_singular}_id"
+      associations.each do |association|
+        my_buddy_id = Fixnum.eql?(association.class) ? association : association.id
+        new_association = through_class.new(myself => self.id, my_buddy => my_buddy_id)
+        new_association.save
+      end
+    end
+
+    private "remove_#{association_singular}_associations".to_sym, "add_#{association_singular}_associations".to_sym
+
+  end
+
+  private :collection_accessor_methods_elsewhere
+
+end

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,8 @@
+require 'test_helper'
+
+class StElsewhereTest < ActiveSupport::TestCase
+  # Replace this with your real tests.
+  test "the truth" do
+    assert true
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'active_support'
+require 'active_support/test_case'

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+name: st-elsewhere
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Brian Doll
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-14 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+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
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- init.rb
+- 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/briandoll/st-elsewhere
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+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