active_importer 0.0.3 → 0.1.0

data/README.md

@@ -71,7 +71,66 @@ of the spreadsheet.
 
 ### Callbacks
 
-TODO: Document callbacks
+An importer class can define blocks of code acting as callbacks, to be notified
+of certain events that occur while importing the data.
+
+```ruby
+class EmployeeImporter < ActiveImporter::Base
+  imports Employee
+
+  attr_reader :row_count
+
+  column 'First name', :first_name
+  column 'Last name', :last_name
+  column 'Department', :department do |department_name|
+    Department.find_by(name: department_name)
+  end
+
+  on :import_started do
+    @row_count = 0
+  end
+
+  on :row_processed do
+    @row_count += 1
+  end
+
+  on :import_finished do
+    send_notification("Data imported successfully!")
+  end
+
+  on :import_failed do |exception|
+    send_notification("Fatal error while importing data: #{exception.message}")
+  end
+
+  private
+
+  def send_notification(message)
+    # ...
+  end
+end
+```
+
+The supported events are:
+
+- **import_failed:** Fired once **before** the beginning of the data
+  processing, if the input data cannot be processed for some reason.  If this
+  event is fired by an importer, none of its other events are ever fired.
+- **import_started:** Fired once at the beginning of the data processing,
+  before the first row is processed.
+- **row_processed:** Fired once for each row that has been processed,
+  regardless of whether it resulted in success or error.
+- **row_success:** Fired once for each row that was imported successfully into
+  the data model.
+- **row_error:** Fired once for each row that was **not** imported successfully
+  into the data model.
+- **import_finished:** Fired once **after** all rows have been processed.
+
+More than one block of code can be provided for each of these events, and they
+will all be invoked in the same order in which they were declared.  All blocks
+are executed in the context of the importer instance, so they have access to
+all the importer attributes and instance variables.  Error-related events
+(`:import_failed` and `:row_error`) pass to the blocks the instance of the
+exception that provoked the error condition.
 
 ## Contributing
 

data/lib/active_importer/base.rb

@@ -38,6 +38,36 @@ module ActiveImporter
       new(file, options).import
     end
 
+    #
+    # Callbacks
+    #
+
+    EVENTS = [
+      :row_success,
+      :row_error,
+      :row_processed,
+      :import_started,
+      :import_finished,
+      :import_failed,
+    ]
+
+    def self.event_handlers
+      @event_handlers ||= EVENTS.inject({}) { |hash, event| hash.merge({event => []}) }
+    end
+
+    def self.on(event, &block)
+      raise "Unknown ActiveImporter event '#{event}'" unless EVENTS.include?(event)
+      event_handlers[event] << block
+    end
+
+    def fire_event(event, param = nil)
+      self.class.event_handlers[event].each do |block|
+        self.instance_exec(param, &block)
+      end
+    end
+
+    private :fire_event
+
     #
     # Implementation
     #
@@ -60,7 +90,7 @@ module ActiveImporter
       @book = @header = nil
       @row_count = 0
       @row_index = 1
-      import_failed(e.message)
+      fire_event :import_failed, e
     end
 
     def fetch_model
@@ -69,12 +99,13 @@ module ActiveImporter
 
     def import
       return if @book.nil?
+      fire_event :import_started
       @data_row_indices.each do |index|
         @row_index = index
         @row = row_to_hash @book.row(index)
         import_row
       end
-      import_finished
+      fire_event :import_finished
     end
 
     def row_processed_count
@@ -92,18 +123,6 @@ module ActiveImporter
     def hook
     end
 
-    def row_success
-    end
-
-    def row_error(error_message)
-    end
-
-    def import_failed(error_message)
-    end
-
-    def import_finished
-    end
-
     private
 
     def columns
@@ -134,11 +153,13 @@ module ActiveImporter
         model.save!
       rescue => e
         @row_errors << { row_index: row_index, error_message: e.message }
-        row_error(e.message)
+        fire_event :row_error, e
         return false
       end
-      row_success
+      fire_event :row_success
       true
+    ensure
+      fire_event :row_processed
     end
 
     def build_model

data/lib/active_importer/version.rb

@@ -1,3 +1,3 @@
 module ActiveImporter
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

data/spec/active_importer/base_spec.rb

@@ -27,8 +27,9 @@ describe ActiveImporter::Base do
     EmployeeImporter.import('/dummy/file')
   end
 
-  it 'notifies when the import process has finished' do
+  it 'notifies when the import process starts and finishes' do
     expect(EmployeeImporter).to receive(:new).once.and_return(importer)
+    expect(importer).to receive(:import_started).once
     expect(importer).to receive(:import_finished).once
     EmployeeImporter.import('/dummy/file')
   end
@@ -59,6 +60,12 @@ describe ActiveImporter::Base do
       expect(EmployeeImporter).to receive(:new).once.and_return(importer)
       expect { EmployeeImporter.import('/dummy/file') }.to change(importer.row_errors, :count).by(2)
     end
+
+    it 'still notifies all rows as processed' do
+      expect(EmployeeImporter).to receive(:new).once.and_return(importer)
+      expect(importer).to receive(:row_processed).exactly(4).times
+      EmployeeImporter.import('/dummy/file')
+    end
   end
 
   context 'when the import fails' do

data/spec/stubs/employee.rb

@@ -22,4 +22,9 @@ class EmployeeImporter < ActiveImporter::Base
   def find_department(name)
     name.length # Quick dummy way to get an integer out of a string
   end
+
+  ActiveImporter::Base::EVENTS.each do |event_name|
+    define_method(event_name) {}
+    on(event_name) { send event_name }
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_importer
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -112,7 +112,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3421867451760096133
+      hash: -645039623466056614
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -121,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3421867451760096133
+      hash: -645039623466056614
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23