acts_as_archival 0.4.0

data/.gitignore

@@ -0,0 +1,10 @@
+*~
+*.log
+.bundle
+bin
+vendor/bundle
+test/aaa_test_app/vendor/bundle
+*.bkp
+*.gem
+Gemfile.lock
+pkg/*

data/.rvmrc

@@ -0,0 +1 @@
+rvm ruby-1.9.3-p125@aaa --create

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+#0.4.0
+* BUGFIX: when `archive`/`unarchive` fail, they now return false instead of nil
+* Rails 3.2 compatibility -- **Rails 3.0 incompatible due to ARec differences**
+* Gemified!
+* Major test re-organization

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,44 @@
+PATH
+  remote: .
+  specs:
+    acts_as_archival (0.4.0)
+      activerecord
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (3.2.2)
+      activesupport (= 3.2.2)
+      builder (~> 3.0.0)
+    activerecord (3.2.2)
+      activemodel (= 3.2.2)
+      activesupport (= 3.2.2)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.2)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    assertions-eb (1.7.3)
+    builder (3.0.0)
+    database_cleaner (0.7.1)
+    highline (1.6.11)
+    i18n (0.6.0)
+    multi_json (1.1.0)
+    mysql2 (0.3.11)
+    rake (0.9.2.2)
+    rr (1.0.4)
+    tzinfo (0.3.31)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport
+  acts_as_archival!
+  assertions-eb
+  database_cleaner
+  highline
+  mysql2
+  rake
+  rr

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009-2012 Expected Behavior
+
+MIT License
+
+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,112 @@
+# ActsAsArchival
+
+Plugin for atomically archiving model records in activerecord models.
+
+We had the problem that acts_as_paranoid and similar plugins/gems
+always work on a record by record basis and made it very difficult to
+restore records atomically (or archive them, for that matter).
+
+Because the archive and unarchive methods are in transactions, and
+every archival record involved gets the same archive number upon
+archiving, you can easily restore or remove an entire set of records
+without having to worry about partial deletion or restoration.
+
+Additionally, other plugins generally screw with how
+`destroy`/`delete` work.  We don't because we actually want to be able
+to destroy records.
+
+## Install
+
+Rails 3:
+
+`rails plugin install http://github.com/expectedbehavior/acts_as_archival.git`
+
+Rails 2:
+
+`script/plugin install http://github.com/expectedbehavior/acts_as_archival.git -r rails2`
+
+Any models you want to be archival should have the columns
+`archive_number`(String) and `archived_at` (DateTime).
+
+i.e. `script/generate migration AddAAAToPost archive_number:string archived_at:datetime`
+
+Any dependent-destroy objects connected to an AAA model will be
+archived with its parent.
+
+## Example
+
+``` ruby
+class Hole < ActiveRecord::Base
+  acts_as_archival
+  has_many :moles, :dependent => :destroy
+end
+
+class Mole < ActiveRecord::Base
+  acts_as_archival
+end
+```
+
+``` ruby
+>> Hole.archived.size               # => 0
+>> Hole.is_archival?                # => true
+>> h = Hole.create
+>> Hole.unarchived.size             # => 1
+>> h.is_archival?                   # => true
+>> h.archived?                      # => false
+>> h.muskrats.create
+>> h.archive                        # archive hole and muskrat
+>> h.archive_number                 # => 8c9f03f9d....
+>> h.muskrats.first.archive_number  # => 8c9f03f9d....
+>> h.archived?                      # => 8c9f03f9d....
+>> Hole.archived.size               # => 1
+>> Hole.unarchived.size             # => 0
+>> h.unarchive
+>> Hole.archived.size               # => 0
+>> Hole.unarchived.size             # => 1
+```
+
+## Caveats
+
+1. This will only work on associations that are dependent destroy. It
+should be trival to change that or make it optional.
+1. It will only work for Rails 2.2 and up, because we are using
+`named_scope`/`scope`. You can check out permanent records for a way
+to conditionally add the functionality to older Rails installations.
+1. This will only work (well) on databases with transactions (mysql,
+postgres, etc.).
+
+## Testing
+
+Because this plugin makes use of transactions we're testing it on
+MySQL instead of the more convenient sqlite. Running the tests should
+be as easy as:
+
+```  bash
+bundle
+test/script/db_setup    # makes the databases with the correct permissions (for mySQL)
+rake
+```
+
+## Help Wanted
+
+It would be cool if someone could check if this thing works on
+postgres and if not, submit a patch / let us know about it!
+
+## Thanks
+
+ActsAsParanoid and PermanentRecords were both inspirations for this  
+http://github.com/technoweenie/acts_as_paranoid  
+http://github.com/fastestforward/permanent_records  
+
+## Contributors
+
+* Joel Meador
+* Michael Kuehl
+* Matthew Gordon
+* Vojtech Salbaba
+* David Jones
+* Dave Woodward
+
+Thanks, guys!
+
+*Copyright (c) 2009-2012 Expected Behavior, LLC, released under the MIT license*

data/Rakefile

@@ -0,0 +1,13 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+desc "Default: run unit tests."
+task :default => :test
+
+desc "Test the acts_as_archival plugin."
+Rake::TestTask.new(:test) do |t|
+  t.libs    << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+end

data/acts_as_archival.gemspec

@@ -0,0 +1,47 @@
+# -*- encoding: utf-8 -*-
+$LOAD_PATH.push File.expand_path("../lib", __FILE__)
+require "acts_as_archival/version"
+
+Gem::Specification.new do |gem|
+  gem.name        = "acts_as_archival"
+  gem.summary     = %q{Atomic archiving/unarchiving for ActiveRecord-based apps}
+  gem.version     = ActsAsArchival::VERSION
+  gem.authors     = ["Joel Meador",
+                     "Michael Kuehl",
+                     "Matthew Gordon",
+                     "Vojtech Salbaba",
+                     "David Jones",
+                     "Dave Woodward"]
+  gem.email       = ["joel@expectedbehavior.com",
+                     "michael@expectedbehavior.com",
+                     "matt@expectedbehavior.com"]
+  gem.homepage    = "http://expectedbehavior.com"
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "activerecord"
+
+  gem.add_development_dependency "activesupport"
+  gem.add_development_dependency "assertions-eb"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "mysql2"
+  gem.add_development_dependency "highline"
+  gem.add_development_dependency "rr"
+  gem.add_development_dependency "database_cleaner"
+
+  gem.description = <<-END
+We had the problem that acts_as_paranoid and similar plugins/gems always work on
+a record by record basis and made it very difficult to restore records
+atomically (or archive them, for that matter).
+
+Because the archive and unarchive methods are in transactions, and every
+archival record involved gets the same archive number upon archiving, you can
+easily restore or remove an entire set of records without having to worry about
+partial deletion or restoration.
+
+Additionally, other plugins generally screw with how destroy/delete work.  We
+don't because we actually want to be able to destroy records.
+END
+end

data/init.rb

@@ -0,0 +1,3 @@
+# Include hook code here
+ActiveRecord::Base.send :include, ExpectedBehavior::ActsAsArchivalActiveRecordMethods
+ActiveRecord::Base.send :include, ExpectedBehavior::ActsAsArchival

data/lib/acts_as_archival.rb

@@ -0,0 +1,7 @@
+require "acts_as_archival/version"
+
+require "expected_behavior/acts_as_archival"
+require "expected_behavior/acts_as_archival_active_record_methods"
+
+ActiveRecord::Base.send :include, ExpectedBehavior::ActsAsArchival
+ActiveRecord::Base.send :include, ExpectedBehavior::ActsAsArchivalActiveRecordMethods

data/lib/acts_as_archival/version.rb

@@ -0,0 +1,3 @@
+module ActsAsArchival
+  VERSION = "0.4.0"
+end

data/lib/expected_behavior/acts_as_archival.rb

@@ -0,0 +1,141 @@
+module ExpectedBehavior
+  module ActsAsArchival
+    require 'digest/md5'
+
+    ARCHIVED_CONDITIONS = lambda { |zelf| %Q{#{zelf.to_s.tableize}.archived_at IS NOT NULL AND #{zelf.to_s.tableize}.archive_number IS NOT NULL} }
+    UNARCHIVED_CONDITIONS = { :archived_at => nil, :archive_number => nil }
+
+    MissingArchivalColumnError = Class.new(ActiveRecord::ActiveRecordError) unless defined?(MissingArchivalColumnError) == 'constant' && MissingArchivalColumnError.class == Class
+    CouldNotArchiveError = Class.new(ActiveRecord::ActiveRecordError) unless defined?(CouldNotArchiveError) == 'constant' && CouldNotArchiveError.class == Class
+    CouldNotUnarchiveError = Class.new(ActiveRecord::ActiveRecordError) unless defined?(CouldNotUnarchiveError) == 'constant' && CouldNotUnarchiveError.class == Class
+
+    def self.included(base)
+      base.extend ActMethods
+    end
+
+    module ActMethods
+      def acts_as_archival(options = { })
+        unless included_modules.include? InstanceMethods
+          include InstanceMethods
+
+          before_validation :raise_if_not_archival
+          validate :readonly_when_archived if options[:readonly_when_archived]
+
+          scope :archived, :conditions => ARCHIVED_CONDITIONS.call(self)
+          scope :unarchived, :conditions => UNARCHIVED_CONDITIONS
+          scope :archived_from_archive_number, lambda { |head_archive_number| {:conditions => ['archived_at IS NOT NULL AND archive_number = ?', head_archive_number] } }
+
+          callbacks = ['archive','unarchive']
+          define_callbacks *[callbacks, {:terminator => 'result == false'}].flatten
+          callbacks.each do |callback|
+            eval <<-end_callbacks
+              def before_#{callback}(*args, &blk)
+                set_callback(:#{callback}, :before, *args, &blk)
+              end
+              def after_#{callback}(*args, &blk)
+                set_callback(:#{callback}, :after, *args, &blk)
+              end
+            end_callbacks
+          end
+        end
+      end
+
+    end
+
+    module InstanceMethods
+
+      def readonly_when_archived
+        if self.archived? && self.changed? && !self.archived_at_changed? && !self.archive_number_changed?
+          self.errors.add(:base, "Cannot modifify an archived record.")
+        end
+      end
+
+      def raise_if_not_archival
+        missing_columns = []
+        missing_columns << "archive_number" unless self.respond_to?(:archive_number)
+        missing_columns << "archived_at" unless self.respond_to?(:archived_at)
+        raise MissingArchivalColumnError.new("Add '#{missing_columns.join "', '"}' column(s) to '#{self.class.name}' to make it archival") unless missing_columns.blank?
+      end
+
+      def archived?
+        self.archived_at? && self.archive_number
+      end
+
+      def archive(head_archive_number=nil)
+        self.class.transaction do
+          begin
+            run_callbacks :archive, :before
+            unless self.archived?
+              head_archive_number ||= Digest::MD5.hexdigest("#{self.class.name}#{self.id}")
+              self.archive_associations(head_archive_number)
+              self.archived_at = DateTime.now
+              self.archive_number = head_archive_number
+              self.save!
+            end
+            run_callbacks :archive, :after
+            return true
+          rescue
+            raise ActiveRecord::Rollback
+          end
+        end
+        false
+      end
+
+      def unarchive(head_archive_number=nil)
+        self.class.transaction do
+          begin
+            run_callbacks :unarchive, :before
+            if self.archived?
+              head_archive_number ||= self.archive_number
+              self.archived_at = nil
+              self.archive_number = nil
+              self.save!
+              self.unarchive_associations(head_archive_number)
+            end
+            run_callbacks :unarchive, :after
+            return true
+          rescue
+            raise ActiveRecord::Rollback
+          end
+        end
+        false
+      end
+
+      def archive_associations(head_archive_number)
+        act_only_on_dependent_destroy_associations = Proc.new {|association| association.options[:dependent] == :destroy}
+        act_on_all_archival_associations(head_archive_number, :archive => true, :association_options => act_only_on_dependent_destroy_associations)
+      end
+
+      def unarchive_associations(head_archive_number)
+        act_on_all_archival_associations(head_archive_number, :unarchive => true)
+      end
+
+      def act_on_all_archival_associations(head_archive_number, options={})
+        return if options.length == 0
+        options[:association_options] ||= Proc.new { true }
+        self.class.reflect_on_all_associations.each do |association|
+          if association.macro.to_s =~ /^has/ && association.klass.is_archival? && options[:association_options].call(association) && association.options[:through].nil?
+            act_on_a_related_archival(association.klass, association.foreign_key, id, head_archive_number, options)
+          end
+        end
+      end
+
+      def act_on_a_related_archival(klass, key_name, id, head_archive_number, options={})
+        return if options.length == 0 || (!options[:archive] && !options[:unarchive])
+        if options[:archive]
+          klass.unarchived.find(:all, :conditions => ["#{key_name} = ?", id]).each do |related_record|
+            unless related_record.archive(head_archive_number)
+              raise ActiveRecord::Rollback
+            end
+          end
+        else
+          klass.archived.find(:all, :conditions => ["#{key_name} = ? AND archive_number = ?", id, head_archive_number]).each do |related_record|
+            unless related_record.unarchive(head_archive_number)
+              raise ActiveRecord::Rollback
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/expected_behavior/acts_as_archival_active_record_methods.rb

@@ -0,0 +1,20 @@
+module ExpectedBehavior
+  module ActsAsArchivalActiveRecordMethods
+    def self.included(base)
+      base.extend ARClassMethods
+      base.send :include, ARInstanceMethods
+    end
+
+    module ARClassMethods
+      def is_archival?
+        self.included_modules.include?(ExpectedBehavior::ActsAsArchival::InstanceMethods)
+      end
+    end
+
+    module ARInstanceMethods
+      def is_archival?
+        self.class.is_archival?
+      end
+    end
+  end
+end