dbview_cti 0.0.1

data/.gitignore

@@ -0,0 +1,9 @@
+.bundle/
+log/*.log
+pkg/
+spec/dummy*/db/*.sqlite3
+spec/dummy*/log/*.log
+spec/dummy*/tmp/
+spec/dummy*/.sass-cache
+.project
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,31 @@
+source "http://rubygems.org"
+
+# Declare your gem's dependencies in view_based_cti.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec
+
+# jquery-rails is used by the dummy application
+gem "jquery-rails"
+
+# Declare any dependencies that are still in development here instead of in
+# your gemspec. These might include edge Rails or gems from your path or
+# Git. Remember to move these dependencies to your gemspec before releasing
+# your gem to rubygems.org.
+
+# To use debugger
+# gem 'debugger'
+
+# taken from http://schneems.com/post/50991826838/testing-against-multiple-rails-versions
+rails_version = ENV["RAILS_VERSION"] || "default"
+
+rails = case rails_version
+when "master"
+  { :github => "rails/rails"}
+when "default"
+  ">= 3.2.13"
+else
+  "~> #{rails_version}"
+end
+
+gem "rails", rails

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+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.md

@@ -0,0 +1,219 @@
+# dbview_cti
+
+This gem implements [Class Table Inheritance](http://martinfowler.com/eaaCatalog/classTableInheritance.html) (CTI) 
+for Rails, as an alternative to Single Table Inheritance (STI). The implementation is based on database views.
+
+Currently, only PostgreSQL (version >= 9.1) is supported. The gem works for both Rails 3.2 and Rails 4 apps.
+
+## Installation
+
+Add the following to your Gemfile:
+
+```ruby
+gem 'dbview_cti'
+```
+
+## Example
+
+Suppose we would like to have the following class hierarchy: a Vehicle superclass, its subclass MotorVehicle, and Car and MotorCycle wich are subclasses of MotorVehicle:
+ 
+```ruby
+class Vehicle < ActiveRecord::Base
+end
+
+class MotorVehicle < Vehicle
+end
+
+class Car < MotorVehicle
+end
+
+class MotorCycle < MotorVehicle
+end
+```
+
+With Class Table Inheritance, we use a separate database table for each class. Each table only stores the attributes that are specific to that class.
+dbview_cti uses database views to combine attributes from several tables in the hierarchy in an almost transparent way, so the resulting objects behave like
+normal ActiveRecord models (with a few exceptions).
+
+In order to do this dbview_cti has to know all descendants of a class, so we modify our class definitions:
+
+```ruby
+class Vehicle < ActiveRecord::Base
+  cti_base_class
+end
+
+class MotorVehicle < Vehicle
+  cti_derived_class
+end
+
+class Car < MotorVehicle
+  cti_derived_class
+end
+
+class MotorCycle < MotorVehicle
+  cti_derived_class
+end
+```
+
+In the base class in the hierarchy (Vehicle in this case), we add a call to `cti_base_class`, in all derived classes we add `cti_derived_class`. 
+It is important to add these before running any migrations for the models, otherwise the database views won't be generated correctly (it is always possible to have them
+regenerated, see further).
+
+Now it's time to create the database tables (and views) using Rails migrations. The table for the base class is created using a standard migration, e.g.   
+
+```ruby
+class CreateVehicles < ActiveRecord::Migration
+  def change
+    create_table :vehicles do |t|
+      t.string  :name
+      t.integer :mass
+
+      t.timestamps
+    end
+  end
+end
+```
+
+For the derived classes, we use `cti_create_view(class_name)`, a method that dbview_cti adds to migrations: 
+
+```ruby
+class CreateMotorVehicles < ActiveRecord::Migration
+  def change
+    create_table :motor_vehicles do |t|
+      t.references :vehicle
+      t.string  :fuel
+      t.integer :number_of_wheels
+
+      t.timestamps
+    end
+    
+    cti_create_view('MotorVehicle')
+  end
+end
+```
+
+There are two things to note in this migration:
+
+1. The table references the table used for the parent class (vehicles in this case)
+2. We call `cti_create_view(class_name)` to create the necessary database view and triggers, and to tell ActiveRecord to use the database view instead of the motor_vehicles table.
+
+The migrations for Car and MotorCycle are very similar (i.e. they reference the parent table and call cti_create_view):
+
+```ruby
+class CreateCars < ActiveRecord::Migration
+  def change
+    create_table :cars do |t|
+      t.references :motor_vehicle
+      t.boolean :stick_shift
+      t.boolean :convertible
+
+      t.timestamps
+    end
+    
+    cti_create_view('Car')
+  end
+end
+
+class CreateMotorCycles < ActiveRecord::Migration
+  def change
+    create_table :motor_cycles do |t|
+      t.references :motor_vehicle
+      t.boolean :offroad
+
+      t.timestamps
+    end
+    
+    cti_create_view('MotorCycle')
+  end
+end
+```
+
+After running `rake db:migrate` we can now use our new models, e.g. in the rails console:
+
+    1.9.3-p448 :001 > c = Car.new
+     => #<Car id: nil, name: nil, mass: nil, fuel: nil, number_of_wheels: nil, stick_shift: nil, convertible: nil, created_at: nil, updated_at: nil> 
+    1.9.3-p448 :003 > c.name = 'Audi'
+     => "Audi" 
+    1.9.3-p448 :004 > c.stick_shift = true
+     => true 
+    1.9.3-p448 :005 > c.save!
+     => true 
+
+Note that Car has all attributes of the vehicles, motor_vehicles and cars tables combined. When saving, the attributes are stored in their corresponding tables.
+
+## API
+
+### Models
+
+dbview_cti adds two class methods to ActiveRecord::Base:
+
+* `cti_base_class`, which should be included in the class definition of the base class of the hierarchy.
+* `cti_derived_class`, which should be included in the class definition of every other class in the hierarchy.
+
+When either `cti_base_class` or `cti_derived_class` are used in the definition of a model, the model is equipped with the following instance methods:
+
+* `convert_to(class_name)`. Use this to convert an object to another class. Both `convert_to('MotorVehicle')` and `convert_to(:motor_vehicle)` are ok. Example: 
+
+        1.9.3-p448 :003 > c = Car.create(:name => 'Audi')
+         => #<Car id: 2, name: "Audi", mass: nil, fuel: nil, number_of_wheels: nil, stick_shift: nil, convertible: nil, created_at: "2013-08-20 01:17:07", updated_at: "2013-08-20 01:17:07"> 
+        1.9.3-p448 :004 > v = c.convert_to(:vehicle)
+         => #<Vehicle id: 3, name: "Audi", mass: nil, created_at: "2013-08-20 01:17:07", updated_at: "2013-08-20 01:17:07"> 
+        1.9.3-p448 :005 > v.convert_to(:car)  # convert back to Car
+         => #<Car id: 2, name: "Audi", mass: nil, fuel: nil, number_of_wheels: nil, stick_shift: nil, convertible: nil, created_at: "2013-08-20 01:17:07", updated_at: "2013-08-20 01:17:07"> 
+        1.9.3-p448 :009 > v.convert_to(:motor_cycle)  # since v is a car we cannot convert it to a MotorCycle
+         => nil 
+
+* `specialize` converts an object to its 'true' (i.e. most specialized or most derived) class. Example:
+
+        1.9.3-p448 :010 > c = Car.create(:name => 'Volvo')
+         => #<Car id: 4, name: "Volvo", mass: nil, fuel: nil, number_of_wheels: nil, stick_shift: nil, convertible: nil, created_at: "2013-08-20 01:27:26", updated_at: "2013-08-20 01:27:26"> 
+        1.9.3-p448 :011 > mv = MotorVehicle.create(:name => 'Trike')
+         => #<MotorVehicle id: 5, name: "Trike", mass: nil, fuel: nil, number_of_wheels: nil, created_at: "2013-08-20 01:28:06", updated_at: "2013-08-20 01:28:06"> 
+        1.9.3-p448 :012 > c.convert_to(:vehicle).specialize
+         => #<Car id: 4, name: "Volvo", mass: nil, fuel: nil, number_of_wheels: nil, stick_shift: nil, convertible: nil, created_at: "2013-08-20 01:27:26", updated_at: "2013-08-20 01:27:26"> 
+        1.9.3-p448 :013 > mv.convert_to(:vehicle).specialize
+         => #<MotorVehicle id: 5, name: "Trike", mass: nil, fuel: nil, number_of_wheels: nil, created_at: "2013-08-20 01:28:06", updated_at: "2013-08-20 01:28:06"> 
+
+* `type` returns the 'true' (i.e. most specialized) class of an object (the class that the object is converted to when calling `specialize`).
+
+### Migrations
+
+dbview_cti adds two methods to migrations:
+
+* `cti_create_view(class_name)`
+* `cti_drop_view(class_name)`
+
+See the example migrations above about how to use `cti_create_view`. `cti_drop_view` can be used to drop a view created by `cti_create_view`
+(e.g. in the `down` method of a migration.)
+
+It is also possible to recreate the database views (and triggers). This is necessary when you want to change one of the tables in the hierarchy, 
+since then the views of all subclasses have to be recreated. dbview_cti provides the `cti_recreate_views_after_change_to(class_name)` method 
+(to be used with a block) to do this:
+
+```ruby
+class AddReliabilityToMotorVehicles < ActiveRecord::Migration
+  def up
+    cti_recreate_views_after_change_to('MotorVehicle') do
+      add_column(:motor_vehicles, :reliability, :integer)
+    end
+  end
+  
+  def down
+    cti_recreate_views_after_change_to('MotorVehicle') do
+      remove_column(:motor_vehicles, :reliability)
+    end
+  end
+end
+```
+
+The `change` syntax is not (yet?) supported for recreating database views.
+
+## Notes
+
+* Using dbview_cti doesn't interfere with foreign key constraints. In fact, I recommend adding foreign key constraints
+between the tables in a CTI hierarchy (e.g. using [foreigner](https://github.com/matthuhiggins/foreigner)).
+* Take care when using database id's. Since the data for a Car object is spread over several tables, 
+the id of a Car instance will generally be different than the id of the MotorVehicle instance you get when you 
+convert the Car instance to a MotorVehicle.
+* The gem intercepts calls to destroy to make sure all rows in all tables are removed. This is not the case for 
+delete_all, however, so avoid using delete_all for classes in the CTI hierarchy.

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ViewBasedCti'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+

data/dbview_cti.gemspec

@@ -0,0 +1,24 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+# Maintain your gem's version:
+require "db_view_cti/version"
+
+# Describe your gem and declare its dependencies:
+Gem::Specification.new do |s|
+  s.name        = "dbview_cti"
+  s.version     = DBViewCTI::VERSION
+  s.authors     = ["Michaël Van Damme"]
+  s.email       = ["michael.vandamme@vub.ac.be"]
+  s.homepage    = "https://github.com/mvdamme/dbview_cti"
+  s.summary     = "Class Table Inheritance (CTI) for Rails."
+  s.description = "This gem implements Class Table Inheritance (CTI) for Rails using database views."
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  s.add_dependency "rails", ">= 3.2.0"
+
+  s.add_development_dependency "rspec-rails"
+  s.add_development_dependency "activerecord-postgresql-adapter"
+  s.add_development_dependency "foreigner"
+end

data/lib/db_view_cti/connection_adapters/schema_statements.rb

@@ -0,0 +1,44 @@
+module DBViewCTI
+  module ConnectionAdapters
+    module SchemaStatements
+
+      def cti_create_view(class_name, options = {})
+        generator = DBViewCTI::SQLGeneration::Migration::Factory.generator(class_name)
+        cti_execute_sql(generator.create_view_sql)
+        cti_execute_sql(generator.create_trigger_sql)
+      end
+
+      def cti_drop_view(class_name, options = {})
+        generator = DBViewCTI::SQLGeneration::Migration::Factory.generator(class_name)
+        cti_execute_sql(generator.drop_trigger_sql)
+        cti_execute_sql(generator.drop_view_sql)
+      end
+      
+      # use with block in up/down methods
+      def cti_recreate_views_after_change_to(class_name, options = {})
+        klass = class_name.constantize
+        classes = [ class_name ] + klass.cti_all_descendants
+        # drop all views in reverse order
+        classes.reverse.each do |kklass|
+          cti_drop_view(kklass, options)
+        end
+        yield # perform table changes in block (e.g. add column)
+        # recreate views in forward order
+        classes.each do |kklass|
+          cti_create_view(kklass, options)
+        end
+      end
+      
+      # Needed since sqlite only executes the first statement in a string containing multiple
+      # statements
+      def cti_execute_sql(sql)
+        return execute(sql) if sql.is_a?(String)
+        sql.map do |query|
+          execute(query)
+        end
+      end
+
+    end
+  end
+end
+

data/lib/db_view_cti/loader.rb

@@ -0,0 +1,19 @@
+module DBViewCTI
+
+  def self.load
+    ActiveRecord::ConnectionAdapters::AbstractAdapter.module_eval do
+      include DBViewCTI::ConnectionAdapters::SchemaStatements
+    end
+
+    if defined?(ActiveRecord::Migration::CommandRecorder)
+      ActiveRecord::Migration::CommandRecorder.class_eval do
+        include DBViewCTI::Migration::CommandRecorder
+      end
+    end
+
+    ActiveRecord::Base.class_eval do
+      include DBViewCTI::Model::Extensions
+    end
+  end
+
+end

data/lib/db_view_cti/migration/command_recorder.rb

@@ -0,0 +1,19 @@
+module DBViewCTI
+  module Migration
+    module CommandRecorder
+
+      def cti_create_view(*args)
+        record(:cti_create_view, args)
+      end
+
+      def cti_drop_view(*args)
+        record(:cti_drop_view, args)
+      end
+
+      def invert_cti_create_view(args)
+        [:cti_drop_view, args]
+      end
+
+    end
+  end
+end

data/lib/db_view_cti/model/cti.rb

@@ -0,0 +1,129 @@
+module DBViewCTI
+  module Model
+    module CTI
+      extend ActiveSupport::Concern
+      
+      def specialize
+        class_name, id = type(true)
+        return self if class_name == self.class.name
+        class_name.constantize.find(id)
+      end
+      
+      # Return the 'true' (i.e. most specialized) classname of this object
+      # When return_id is true, the 'specialized' database id is also returned
+      def type(return_id = false)
+        query, levels = self.class.cti_outer_join_sql(id)
+        result = self.class.connection.execute(query).first
+        # replace returned ids with the levels corresponding to their classes
+        result_levels = result.inject({}) do |hash, (k,v)|
+          hash[k] = levels[k] unless v.nil?
+          hash
+        end
+        # find class with maximum level value
+        foreign_key = result_levels.max_by { |k,v| v }.first
+        class_name = DBViewCTI::Names.table_to_class_name(foreign_key[0..-4])
+        if return_id
+          id_ = result[foreign_key].to_i
+          [class_name, id_]
+        else
+          class_name
+        end
+      end
+      
+      def convert_to(type)
+        type_string = type.to_s
+        type_string = type_string.camelize if type.is_a?(Symbol)
+        return self if type_string == self.class.name
+        query = self.class.cti_inner_join_sql(id, type_string)
+        # query is nil when we try to cenvert to an descendant class (instead of an ascendant),
+        # or when we try to convert to a class outside of the hierarchy
+        if query.nil?
+          specialized = specialize
+          return nil if specialized == self
+          return specialized.convert_to(type_string)
+        end
+        result = self.class.connection.execute(query).first
+        id = result[ DBViewCTI::Names.foreign_key(type.to_s) ]
+        return nil if id.nil?
+        type_string.constantize.find(id.to_i)
+      end
+      
+      # change destroy and delete methods to operate on most specialized obect
+      included do
+        alias_method_chain :destroy, :specialize
+        alias_method_chain :delete, :specialize
+        # destroy! seems te be defined in Rails 4
+        alias_method_chain :destroy!, :specialize if self.method_defined?(:destroy!) 
+      end
+      
+      def destroy_with_specialize
+        specialize.destroy_without_specialize
+      end
+      
+      def destroy_with_specialize!
+        specialize.destroy_without_specialize!
+      end
+      
+      def delete_with_specialize
+        specialize.delete_without_specialize
+      end
+      
+      module ClassMethods
+        
+        def cti_base_class?
+          !!@cti_base_class
+        end
+  
+        def cti_derived_class?
+          !!@cti_derived_class
+        end
+        
+        attr_accessor :cti_descendants, :cti_ascendants
+        
+        # registers a derived class and its descendants in the current class
+        # class_name: name of derived class (the one calling cti_register_descendants on this class)
+        # descendants: the descendants of the derived class
+        def cti_register_descendants(class_name, descendants = {})
+          @cti_descendants ||= {}
+          @cti_descendants[class_name] = descendants
+          if cti_derived_class?
+            # call up the chain. This will also cause the register_ascendants callbacks
+            self.superclass.cti_register_descendants(self.name, @cti_descendants)
+          end
+          # call back to calling class
+          @cti_ascendants ||= []
+          class_name.constantize.cti_register_ascendants(@cti_ascendants + [ self.name ])
+        end
+        
+        # registers the ascendants of the current class. Called on this class by the parent class.
+        # ascendants: array of ascendants. The first element is the highest level class, derived
+        # classes follow, the last element is the parent of this class.
+        def cti_register_ascendants(ascendants)
+          @cti_ascendants = ascendants
+        end
+        
+        # returns a list of all descendants
+        def cti_all_descendants
+          result = []
+          block = Proc.new do |klass, descendants|
+            result << klass
+            descendants.each(&block)
+          end
+          @cti_descendants ||= {}
+          @cti_descendants.each(&block)
+          result
+        end      
+        
+        include DBViewCTI::SQLGeneration::Model
+        
+        # this method is only used in testing. It returns the number of rows present in the real database
+        # table, not the number of rows present in the view (as returned by count)
+        def cti_table_count
+          result = connection.execute("SELECT COUNT(*) FROM #{DBViewCTI::Names.table_name(self)};")
+          result[0]['count'].to_i
+        end
+        
+      end
+    end
+  end
+end

data/lib/db_view_cti/model/extensions.rb

@@ -0,0 +1,25 @@
+module DBViewCTI
+  module Model
+    module Extensions
+      extend ActiveSupport::Concern
+      
+      module ClassMethods
+        
+        def cti_base_class
+          self.class_eval { include(DBViewCTI::Model::CTI) }
+          @cti_base_class = true
+        end
+  
+        def cti_derived_class
+          # there is no need to include DBViewCTI::Model::CTI in derived classes
+          # (as we do in cti_base_class), since it is included in the base class
+          # and we inherit from that  
+          @cti_derived_class = true
+          self.table_name = DBViewCTI::Names.view_name(self)
+          self.superclass.cti_register_descendants(self.name)
+        end
+  
+      end
+    end
+  end
+end

data/lib/db_view_cti/names.rb

@@ -0,0 +1,33 @@
+module DBViewCTI
+  module Names
+      
+    def self.view_name(klass)
+      self.table_name(klass) + '_view'
+    end
+
+    def self.table_name(klass)
+      ActiveSupport::Inflector.tableize( self.class_name(klass) )
+    end
+    
+    def self.foreign_key(klass)
+      ActiveSupport::Inflector.foreign_key( self.class_name(klass) )
+    end
+    
+    def self.class_name(klass)
+      klass.is_a?(String) ? klass : klass.name
+    end
+
+    def self.trigger_name(klass)
+      self.table_name(klass) + '_trig'
+    end
+
+    def self.trigger_function_name(klass)
+      self.table_name(klass) + '_trgfunc'
+    end
+
+    def self.table_to_class_name(table_name)
+      ActiveSupport::Inflector.classify( table_name )
+    end
+
+  end
+end

data/lib/db_view_cti/railtie.rb

@@ -0,0 +1,11 @@
+module DBViewCTI
+
+  class Railtie < Rails::Railtie
+    initializer 'dbview_cti.load' do
+      ActiveSupport.on_load :active_record do
+        DBViewCTI.load
+      end
+    end
+  end
+
+end