harmonize 0.0.1 → 0.0.2

data/README.md

@@ -9,17 +9,18 @@ hahr-muh-nahyz -
 
 harmonize is a rails 3 engine that allows one to harmonize entire scopes of an ActiveRecord model with arbitrary external data sources.
 
-harmonize works by allowing one to setup feeds from external data called "sources". harmonize applies the "source" feeds to sets of ActiveRecord instances called "targets". These sets of "source" and "target" data are then handed of to a "strategy" to determine how to use the source to modify the target. When applying a "strategy" harmonize creates a Harmonize::Log which has_many Harmonize::Modifications. These records are then used to report information about the harmonize process.
+harmonize works by allowing one to setup feeds from external data called "sources". harmonize applies the "source" feeds to sets of ActiveRecord instances called "targets". These sets of "source" and "target" data are then handed of to a "strategy" to determine how to use the source to modify the target. When applying a "strategy" harmonize creates a Harmonize::Log which has\_many Harmonize::Modifications. These records are then used to report information about the harmonize process.
 
 ## Simple Example
 
-Lets pretend we work for a company that has a large list of stores. This list of stores in maintained in a database we don't have access to directly. The database administrator wrote a script to export the data in CSV format and upload it to our application. In our application we have a Store model but we always want it to be in harmony with the latest CSV file uploaded by the administrator. Every store has a unique name and an address, and the upstream database uses the name as the primary_key.
+Lets pretend we work for a company that has a large list of stores. This list of stores in maintained in a database we don't have access to directly. The database administrator wrote a script to export the data in CSV format and upload it to our application. In our application we have a Store model but we always want it to be in harmony with the latest CSV file uploaded by the administrator. Every store has a unique name and an address, and the upstream database uses the attribute :name as the primary\_key.
 
     class Store < ActiveRecord::Base
       validates :name, :address, :presence => true
 
       # Setup a harmonizer
       harmonize do |config|
+        # use :name from the source data as the lookup key for target records
         config.key = :name
       end
 
@@ -31,7 +32,7 @@ Lets pretend we work for a company that has a large list of stores. This list of
       end
     end
 
-With our Store model wired up as above, we will get a new class method on our model called "harmonize_default!". When we call harmonize_default! harmonize will use the default strategy to harmonize the source records with the target records. In order to understand what actions are taken to bring the targets into harmony, we need to understand Harmonize::Strategies, but that is getting us ahead of ourselves. First lets look at how we configure harmonize.
+With our Store model wired up as above, we will get a new class method on our model called "harmonize\_default!". When we call harmonize\_default! harmonize will use the default strategy to harmonize the source records with the target records. In order to understand what actions are taken to bring the targets into harmony, we need to understand Harmonize::Strategies, but that is getting us ahead of ourselves. First lets look at how we configure harmonize.
 
 ## Harmonize::Configuration
 
@@ -41,54 +42,72 @@ Each call to harmonize creates a Harmonize::Configuration instance that defines
       harmonize do |config|
         config.harmonizer_name    = :custom_name
         config.key                = :the_key
-        config.source             = lambda do
-          get_latest_source_data_feed!
-        end
-        config.target             = lambda do
-          where(:active => true)
-        end
+        config.source             = :get_latest_source_data_feed!
+        config.target             = :some_scope_name
         config.strategy           = YourCustomStrategy
         config.strategy_arguments = { :options => 'needed', :to => 'initialize', :your => 'custom strategy' }
       end
     end
 
-### Harmonizer::Configuration.harmonizer_name
+### Harmonizer::Configuration.harmonizer\_name
 
-harmonize uses the configured harmonize_name as the name of the harmonizer being configured. Each harmonize_name may only be used once. This allows the harmonize method to be called more than once per model.
+harmonize uses the configured harmonize\_name as the name of the harmonizer being configured. Each harmonize\_name may only be used once. This allows the harmonize method to be called more than once per model. This option is used to name special methods used by harmonize. The harmonization method is named with the following convention: "harmonize\_#{harmonizer\_name}!".
 
-The default harmonizer_name is :default
-This option is used to name special methods used by harmonize. The harmonization method is named with the following convention: "harmonize\_#{harmonizer\_name}!".
+The default setting is:
+
+    :default
+
+This setting can be any symbol.
 
 ### Harmonizer::Configuration.key
 
-harmonize uses the configured key to determine what attribute to use to find existing target records.
+harmonize uses the configured key to determine what attribute in the source data feed to use to find existing target records.
+
+The default setting is:
+
+    :id
 
-The default key is :id
+This setting can be any attribute that will be found in source records.
 
 ### Harmonizer::Configuration.source
 
-harmonize uses the configured source to gather the latest set of source records. This can be set to a lambda or any other callable object. The only requirement is that it returns a collection of hash like objects.
+harmonize uses the configured source to gather the latest set of source records. This can be set to a lambda or any other callable object. The only requirement is that it returns a collection of hash like objects. By default this setting calls a method name with the following convention: "harmonize\_source\_#{harmonizer\_name}".
 
-The default source is a lambda
-This lambda calls the default source method who's name is determined by the harmonizer_name. The convention is: "harmonizer\_source\_#{harmonizer_name}".
+The default setting is:
+
+    harmonize_source_default
+
+This setting can be any class method defined in the model that returns properly structured data.
 
 ### Harmonizer::Configuration.target
 
-harmonize uses the configured target to gather the latest set of target records. This can be set to a lambda or any other callable object. The only requirement is that it returns an ActiveRecord::Relation
+harmonize uses the configured target to gather the latest set of target records. This can be set to a lambda or any other callable object. The only requirement is that it returns an ActiveRecord::Relation. Hint, all (named) scopes return ActiveRecord::Relation instances.
+
+The default setting is:
 
-The default target is a lambda. This lambda returns an ActiveRecord::Relation via the ActiveRecord::Base#scoped method. Hint...all (named) scopes return ActiveRecord::Relation instances.
+    scoped
+
+This setting can be any class method defined in the model that returns an ActiveRecord::Relation.
 
 ### Harmonizer::Configuration.strategy
 
-harmonize uses the configured strategy to determine which Harmonize::Strategies::Strategy subclass to use when harmonizing. harmonize uses this setting as well as the strategy_arguments setting to create an instance of the Strategy subclass.
+harmonize uses the configured strategy to determine which Harmonize::Strategies::Strategy subclass to use when harmonizing. harmonize uses this setting as well as the strategy\_arguments setting to create an instance of the Strategy subclass.
+
+The default setting is:
 
-The default strategy is Harmonize::Strategies::BasicCrudStrategy
+    Harmonize::Strategies::BasicCrudStrategy
+
+This setting can be any class that returns complies with the Strategy api.
 
 ### Harmonizer::Configuration.target
 
-harmonize uses the configured strategy_arguments to determine which arguments to use when initializing the set Harmonize::Strategies::Strategy subclass.
+harmonize uses the configured strategy\_arguments to determine which arguments to use when initializing the set Harmonize::Strategies::Strategy subclass.
+
+The default settings is:
 
-The default strategy is {}.
+    {}
+
+This setting can be a hash of initialize options for the defined Strategy.
 
 ## Harmonize::Strategies
 
@@ -107,7 +126,7 @@ The default harmonize strategy is Harmonize::Strategies::BasicCrudStrategy. This
 
 Currently this is the only strategy provided by harmonize, but more will be added when I need them or you send them to me as a pull request.
 
-## Installation
+## Installation and Usage
 
 Add harmonize to the gem file for your rails application:
 
@@ -127,13 +146,19 @@ Configure your model to use harmonize and implement your source:
       end
     end
 
+Bring your data into harmony
+
+    MyModel.harmonize!(:default)
+    # or the custom method named after your harmonizer
+    MyModel.harmonize_default!
+
 Use, report bugs, fix them, and send pull requests!
 
 ## Plans
 
 ## TODO
 
-*  Maybe move key from Configuration to a strategy_argument as it is not a configuration option really, but a way to change stratgey behaviour.
+*  Maybe move key from Configuration to a strategy\_argument as it is not a configuration option really, but a way to change stratgey behaviour.
 
 ## Contributors
 

data/lib/harmonize/base.rb

@@ -21,7 +21,7 @@ module Harmonize
       end
 
       def harmonize!(harmonizer_name)
-        raise UnknownHarmonizerName.new(harmonizer_name) unless harmonizers.has_key?(harmonizer_name)
+        raise UnknownHarmonizerName.new(harmonizer_name.to_s) unless harmonizers.has_key?(harmonizer_name)
         harmonizer = harmonizers[harmonizer_name]
         harmonize_log = create_harmonize_log(harmonizer_name)
         strategy = harmonizer.strategy.new(*harmonizer.strategy_arguments)
@@ -53,21 +53,47 @@ module Harmonize
           )
         end
 
-        def default_harmonizer_options(harmonizer_name)
-          Harmonize::Configuration.new({
-            :source => lambda{ harmonizer_source_method(harmonizer_name) },
-            :target => lambda{ scoped }
-          })
+        def harmonize_source_method(harmonizer_name, method_name = nil)
+          method_name ||= "harmonize_source_#{harmonizer_name}".to_sym
+          raise HarmonizerSourceUndefined.new(harmonizer_name.to_s) unless respond_to?(method_name)
+          send(method_name)
         end
 
-        def harmonizer_source_method(harmonizer_name)
-          method_name = "harmonizer_source_#{harmonizer_name}".to_sym
-          raise HarmonizerSourceUndefined.new(harmonizer_name) unless respond_to?(method_name)
-          send(method_name)
+        def harmonize_target_method(harmonizer_name, method_name = nil)
+          method_name ||= :scoped
+          raise HarmonizerTargetUndefined.new(harmonizer_name.to_s) unless respond_to?(method_name)
+          target_scope = send(method_name)
+          raise HarmonizerTargetInvalid.new(harmonizer_name.to_s) unless target_scope.is_a?(ActiveRecord::Relation)
+          target_scope
+        end
+
+        def validate_harmonize_source(configuration)
+          case configuration.source.class.name
+          when "Proc"
+            configuration
+          when "Symbol"
+            configuration.source = lambda { harmonize_source_method(configuration.harmonizer_name, configuration.source) }
+          else
+            configuration.source = lambda { harmonize_source_method(configuration.harmonizer_name) }
+          end
+          configuration
+        end
+
+        def validate_harmonize_target(configuration)
+          case configuration.target.class.name
+          when "Proc"
+            configuration
+          when "Symbol"
+            configuration.target = lambda { harmonize_target_method(configuration.harmonizer_name, configuration.target) }
+          else
+            configuration.target = lambda { harmonize_target_method(configuration.harmonizer_name) }
+          end
+          configuration
         end
 
         def validate_harmonizer_configuration(configuration)
-          configuration.reverse_merge(default_harmonizer_options(configuration.harmonizer_name))
+          configuration = validate_harmonize_source(configuration)
+          configuration = validate_harmonize_target(configuration)
         end
 
         def setup_harmonizer_method(harmonizer_name)

data/lib/harmonize/errors.rb

@@ -4,4 +4,5 @@ module Harmonize
   class UnknownHarmonizerName < HarmonizeError ; end
   class HarmonizerSourceUndefined < HarmonizeError ; end
   class HarmonizerTargetUndefined < HarmonizeError ; end
+  class HarmonizerTargetInvalid < HarmonizeError ; end
 end

data/lib/harmonize/gemdata.rb

@@ -1,7 +1,7 @@
 module Harmonize
   module Gemdata
     Name    = 'harmonize'
-    Version = '0.0.1'
+    Version = '0.0.2'
     Authors = [ 'Bram Swenson' ]
     Email   = [ 'bram@craniumisajar.com' ]
     Summary = <<-END_SUMMARY

data/lib/harmonize/strategies/basic_crud_strategy.rb

@@ -3,67 +3,85 @@ module Harmonize
 
     class BasicCrudStrategy < Strategy
 
-      def find_target_instance(key, value)
-        target_relation = targets.where(key => value)
-        instance = target_relation.first rescue nil
-        instance ||= target_relation.build
-        instance
+      def harmonize!
+        touched_keys = create_and_update_targets
+        destroy_targets_not_found_in_source(touched_keys)
       end
 
-      def create_modification(instance)
-        unless instance.new_record?
-          harmonize_log.modifications.create!(:modification_type => 'update', :before_time => DateTime.now)
-        else
-          harmonize_log.modifications.create!(:modification_type => 'create', :before_time => DateTime.now)
+      private
+
+        def create_and_update_targets
+          sources.each.inject([]) do |keys, source|
+            target_instance = find_target_instance(harmonizer.key, source[harmonizer.key])
+            modification = initialize_modification(target_instance)
+            modification = harmonize_target_instance!(target_instance, source, modification)
+            modification.save! if modification
+            keys << source[harmonizer.key]
+          end
         end
-      end
 
-      def harmonize_target_instance!(target_instance, source, modification)
-        # TODO: this is a mess
-        error_message = nil
-        errored  = false
-        begin
-          unless target_instance.update_attributes(source)
-            errored = true
-            error_message = target_instance.errors.full_messages
+        def destroy_targets_not_found_in_source(touched_keys)
+          # if we didn't get any touched_keys, destroy everything in targets scope
+          destroy_scope = touched_keys.empty? ? targets : targets.where("#{harmonizer.key} NOT IN (?)", touched_keys)
+          destroy_scope.find_each do |instance|
+            modification = harmonize_log.modifications.build(
+              :modification_type => 'destroy', :before_time => DateTime.now,
+              :instance_id => instance.id
+            )
+            instance.destroy
+            modification.update_attributes!(:after_time => DateTime.now)
           end
-        rescue ActiveRecord::ActiveRecordError, ActiveRecord::UnknownAttributeError => e
-          errored = true
-          error_message = e.message
         end
-        unless errored
-          modification.update_attributes!(:after_time => DateTime.now, :instance_id => target_instance.id)
-        else
-          modification.update_attributes!(:modification_type => 'error', :instance_errors => error_message)
+
+        def find_target_instance(key, value)
+          target_relation = targets.where(key => value)
+          instance = target_relation.first rescue nil
+          instance ||= target_relation.build
+          instance
         end
-      end
 
-      def create_and_update_targets
-        sources.each.inject([]) do |keys, source|
-          target_instance = find_target_instance(harmonizer.key, source[harmonizer.key])
-          modification = create_modification(target_instance)
-          harmonize_target_instance!(target_instance, source, modification)
-          keys << source[harmonizer.key]
+        def initialize_modification(instance)
+          unless instance.new_record?
+            harmonize_log.modifications.new(:modification_type => 'update', :before_time => DateTime.now)
+          else
+            harmonize_log.modifications.new(:modification_type => 'create', :before_time => DateTime.now)
+          end
+        end
+
+        def harmonize_target_instance!(target_instance, source, modification)
+          target_instance, error_message = update_target_attributes(target_instance, source)
+          return false unless (target_instance.changed? or error_message)
+          target_instance, error_message = save_target(target_instance) unless error_message
+          if error_message
+            modification.attributes = { :modification_type => 'error', :instance_errors => error_message }
+          else
+            modification.attributes = { :after_time => DateTime.now, :instance_id => target_instance.id }
+          end
+          modification
         end
-      end
 
-      def destroy_targets_not_found_in_source(touched_keys)
-        # if we didn't get any touched_keys, destroy everything in targets scope
-        destroy_scope = touched_keys.empty? ? targets : targets.where("#{harmonizer.key} NOT IN (?)", touched_keys)
-        destroy_scope.find_each do |instance|
-          modification = harmonize_log.modifications.build(
-            :modification_type => 'destroy', :before_time => DateTime.now,
-            :instance_id => instance.id
-          )
-          instance.destroy
-          modification.update_attributes!(:after_time => DateTime.now)
+        def update_target_attributes(target_instance, source)
+          error_message = false
+          begin
+            target_instance.attributes = source
+          rescue ActiveRecord::UnknownAttributeError => e
+            error_message = e.message
+          end
+          return target_instance, error_message
+        end
+
+        def save_target(target_instance)
+          error_message = false
+          begin
+            unless target_instance.save
+              error_message = target_instance.errors.full_messages
+            end
+          rescue ActiveRecord::ActiveRecordError => e
+            error_message = e.message
+          end
+          return target_instance, error_message
         end
-      end
 
-      def harmonize!
-        touched_keys = create_and_update_targets
-        destroy_targets_not_found_in_source(touched_keys)
-      end
     end
   end
 end

metadata

@@ -2,7 +2,7 @@
 name: harmonize
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Bram Swenson
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-26 00:00:00 -07:00
+date: 2011-06-27 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -67,7 +67,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 2398958541788060618
+      hash: 3057359512407760229
       segments: 
       - 0
       version: "0"