simplesync 0.0.2

data/lib/simple_sync.rb

@@ -0,0 +1,387 @@
+# See README for usage.
+module SimpleSync
+  # Syncer represents the sync setup: Add to this Sources via add_source, and use as a hub for the Mappings between them.
+  class Syncer
+    attr_reader :last_sync
+
+    # Call with an optional Time object, which will be initiated into the Syncer object as the last_sync time.
+    def initialize(last_sync)
+      @last_sync = last_sync
+    end
+
+    # Keeps a list of sources in a simple Array
+    def sources
+      @sources ||= []
+    end
+
+    # Initializes and holds on to the Mappings for this Syncer object.
+    def mappings
+      @mappings ||= Mappings.new
+    end
+
+    # Adds a Source to the Syncer's list of sources. If a block is supplied, it is sent to Source.new,
+    # where it is understood to be a block to be run on a newly-created record object of this source type.
+    def add_source(klass, identifier, finder_scope=nil, &block)
+      (block_given? ? (sources << Source.new(klass, identifier, mappings, finder_scope, &block)) : (sources << Source.new(klass, identifier, mappings, finder_scope)))[-1]
+    end
+
+    # Lists the new_records from all sources put together. Generally only for `poking around' purposes, not used internally.
+    def new_records
+      sources.collect {|s| s.new_records.set}.flatten
+    end
+    # Lists the changed_records from all sources put together. Generally only for `poking around' purposes, not used internally.
+    def changed_records
+      sources.collect {|s| s.changed_records.set}.flatten
+    end
+    # Lists the deleted_records from all sources put together. Generally only for `poking around' purposes, not used internally.
+    def deleted_records
+      sources.collect {|s| s.deleted_records.set}.flatten
+    end
+
+    def inspect # :nodoc:
+      "#<SimpleSync::Syncer:#{object_id} sources: #{@sources.collect {|s| s.name}.join(', ')}>"
+    end
+
+    # Takes a snapshot of every source, provided you've set a block to each source's new_records, changed_records, and deleted_records
+    # so it knows how to retrieve them.
+    def snapshot!
+      sources.each {|s| s.snapshot!}
+    end
+
+    # Synchronizes only the deleted_records, from each source one at a time. With each source, first it takes a snapshot of just the
+    # deleted_records on just that source, then it loops through the other sources and deletes the record from each of them,
+    # after checking to make sure it exists before attempting to delete it. (This is rather inefficient, we should just 'delete' and
+    # if it doesn't exist it doesn't matter.)
+    def sync_deleted!
+      sources.each do |source|
+        source.deleted_records.snapshot!
+        puts "Deleting #{source.deleted_records.length} records that were deleted on #{source.name}..."
+        source.deleted_records.each do |sourcerec|
+          sources.except(source).each do |target|
+            # Some of these may already be deleted on the other sources. (Especially if we've synced within the last sync time already.)
+            # If the record exists on the source,
+            targetrec = sourcerec.find_on(target)
+            # delete it.
+            if targetrec
+              puts "\tDeleting #{sourcerec.identifier} -> #{targetrec.identifier} on #{target.name}"
+              targetrec.delete
+            else
+              puts "\tSkipped #{sourcerec.identifier} on #{target.name}"
+            end
+          end
+        end
+      end
+    end
+
+    # Synchronizes only the new_records, from each source one at a time. With each source, first it takes a snapshot of just the
+    # new_records on just that source, then it loops through the other sources and creates the record on each of them. Since creating
+    # new records sometimes requires saving the associated-id back to the original record, the just-updated record is morphed back to
+    # see if there are any attributes that should be updated on the original record, and if so, it is also updated with the differences.
+    def sync_new!
+      sources.each do |source|
+        source.new_records.snapshot!
+        puts "Creating #{source.new_records.length} records that were created on #{source.name}..."
+        source.new_records.each do |sourcerec|
+          sources.except(source).each do |target|
+            # Need to weed out the ones that were already created
+            targetrec = sourcerec.find_on(target)
+            if targetrec
+              puts "\tSkipped #{sourcerec.identifier} -> #{targetrec.identifier} on #{target.name}"
+            else
+              if (targetrec = sourcerec.morph_to(target)).save
+                puts "\tCreated #{sourcerec.identifier} -> #{targetrec.identifier} on #{target.name}"
+                if sourcerec.morph_to(target).morph_to(source).to_hash != targetrec.morph_to(source).to_hash
+                  sourcerec.data = targetrec.morph_to(source).to_hash.delete_if {|k,v| v.nil?}
+                  if sourcerec.save
+                    puts "\t -> Saved record relationship #{sourcerec.identifier} -> #{targetrec.identifier}."
+                  else
+                    puts "\t -> PROBLEM SAVING record relationship  #{sourcerec.identifier} -> #{targetrec.identifier} !"
+                  end
+                end
+              else
+                puts "\tPROBLEM SAVING #{sourcerec.identifier} on #{target.name} !"
+              end
+            end
+          end
+        end
+      end
+    end
+
+    # Synchronizes only the changed_records, from each source one at a time. With each source, first it takes a snapshot of just the
+    # changed_records on just that source, then it loops through the other sources and updates them, by grabbing the existing record,
+    # updating the attributes, and saving the record back.
+    def sync_changed!
+      sources.each do |source|
+        source.changed_records.snapshot!
+        puts "Updating #{source.changed_records.length} records that were updated on #{source.name}..."
+        source.changed_records.each do |sourcerec|
+          sources.except(source).each do |target|
+            # 1) Get the same record from the target
+            targetrec = sourcerec.find_on(target)
+            # 2) Update the attributes
+            target_update = sourcerec.morph_to(target).to_hash.reject {|k,v| !mappings[target => source].has_key?(k) }
+            target_attrs = targetrec.to_hash.reject {|k,v| !target_update.has_key?(k)}
+            if target_update != target_update # If any data was actually changed.
+              targetrec.update_data(target_update)
+              # 3) Save the target record
+              if targetrec.save
+                puts "\tUpdated #{sourcerec.identifier} -> #{targetrec.identifier} on #{target.name}"
+              else
+                puts "\tPROBLEM SAVING #{sourcerec.identifier} -> #{targetrec.identifier} on #{target.name}"+(targetrec.respond_to?(:error) ? targetrec.error.to_s : '')
+              end
+            else
+              puts "\tNo changes mapped from #{sourcerec.identifier} -> #{targetrec.identifier} on #{target.name}"
+            end
+          end
+        end
+      end
+    end
+
+    # Synchronizes deleted_records, then new_records, then changed_records, simply by calling the sync! method for each of them in turn.
+    # By sync-ing deleted_records first and snapshot!-ing the new_records and changed_records when their turn comes, we can be sure
+    # those records deleted on one source won't show up in the new_records or changed_records on other sources.
+    def sync!
+      # To sync, we have all the tools, here comes the magic!
+      # 1) Sync DELETED.
+      sync_deleted!
+      # 2) Sync NEW.
+      sync_new!
+      # 3) Sync CHANGED.
+      sync_changed!
+      @last_sync = Time.now
+    end
+  end
+
+  # Mappings represents and encapsulates the mappings for a group of sync sources.
+  class Mappings
+
+    # The mappings hash is to be accessed not by a word-index but rather by a single key-value hash of {source => target_source}
+    # For example, mappings[@source_a => @source_b] should be set to a hash that represents the attribute mappings where
+    # @source_a's attributes are the keys and @source_b's attributes are the values.
+    def [](src_tgt)
+      source, target = src_tgt.keys[0], src_tgt.values[0]
+      mappings[source.name + '--' + target.name] || {}
+    end
+
+    # See above.
+    def []=(src_tgt, mapping)
+      source, target = src_tgt.keys[0], src_tgt.values[0]
+      raise TypeError, "mapping must be a hash" unless mapping.is_a?(Hash)
+      mappings[source.name + '--' + target.name] = mapping
+    end
+
+    private
+      def mappings
+        @mappings ||= {}
+      end
+  end
+
+  # Source represents each sync source. There may be more than two. A source must be tied to a Syncer
+  # (use Syncer#add_source to create sources), and any two sources must have mappings defined between them.
+  class Source
+    attr_accessor :klass, :identifier, :finder_scope, :targets, :mappings
+    def name # :nodoc:
+      "#{klass.name}#{finder_scope ? '('+finder_scope.inspect+')' : ''}"
+    end
+
+    # When called with a block, that block is stored for use when snapshot! is called, in order to retrieve the new_records
+    # from the source. Whether a block is given or not, a RecordSet object is returned that holds the current known list of
+    # new_records for this source.
+    def new_records(&block)
+      new_records.getter = block if block_given?
+      @new_records ||= RecordSet.new(self)
+    end
+    # When called with a block, that block is stored for use when snapshot! is called, in order to retrieve the changed_records
+    # from the source. Whether a block is given or not, a RecordSet object is returned that holds the current known list of
+    # changed_records for this source.
+    def changed_records(&block)
+      changed_records.getter = block if block_given?
+      @changed_records ||= RecordSet.new(self)
+    end
+    # When called with a block, that block is stored for use when snapshot! is called, in order to retrieve the deleted_records
+    # from the source. Whether a block is given or not, a RecordSet object is returned that holds the current known list of
+    # deleted_records for this source.
+    def deleted_records(&block)
+      deleted_records.getter = block if block_given?
+      @deleted_records ||= RecordSet.new(self)
+    end
+
+    # Creates a new Source object. Use Syncer#add_source unless you know why you want to call this directly. If a block is
+    # supplied, it is understood to be a block to be run on a newly-created record object of this source type.
+    def initialize(klass, identifier, mappings, finder_scope, &block)
+      @klass = klass
+      @identifier = identifier
+      @mappings = mappings
+      @finder_scope = finder_scope
+      @initialize = block if block_given?
+    end
+
+    # Calls klass.get with the :finder_scope option(s) merged into the finder_options.
+    def get(finder_options={})
+      klass.get(finder_options.merge(@finder_scope || {}))
+    end
+
+    # Initializes a record retrieved by the SimpleSync gem. Simply runs the block supplied to the Source object creation, if one was given.
+    def initialize_record(record)
+      return record if @initialize.nil?
+      record.send(:eval, @initialize.to_ruby).call
+      record
+    end
+
+    def inspect # :nodoc:
+      "#<SimpleSync::Source #{name}: #{new_records.length} new, #{changed_records.length} changed, #{deleted_records.length} deleted >"
+    end
+
+    # Takes a snapshot of new_records, changed_records and deleted_records. Returns self (the Source object).
+    def snapshot!
+      raise RuntimeError, "Must send new_records, changed_records, and deleted_records each a block before this function can be run" unless @new_records_getter.is_a?(Proc) && @changed_records_getter.is_a?(Proc) && @deleted_records_getter.is_a?(Proc)
+      new_records.snapshot!
+      changed_records.snapshot!
+      deleted_records.snapshot!
+      self
+    end
+
+    # source.mapping_to(target) is synonymous to source.mappings[source => target].
+    def mapping_to(target)
+      mappings[self => target].merge(self.identifier.to_s => target.identifier.to_s)
+    end
+    # Returns true or false after checking to see if mappings are defined in source.mappings[source => target].
+    def can_map?(target)
+      !mappings[self => target].empty?
+    end
+  end
+
+  # RecordSet is a class used internally to store collections of records, for new_records, changed_records, and deleted_records.
+  # Though not documented here, you can use several of the Array or Enumerable methods: [], <<, each, clear, length.
+  # RecordSets are created automatically, so the new method isn't documented either. The biggest thing it does is extend
+  # all record objects with the SimpleSync::Record module, which gives them a few essential methods.
+  # RecordSet is also where all the snapshot! methods actually do their work.
+  class RecordSet
+    attr_accessor :getter # :nodoc:
+
+    def initialize(source,getter_proc=nil) # :nodoc:
+      @source = source
+      @getter = getter_proc if getter_proc
+    end
+
+    # Takes a snapshot of whatever type of records this RecordSet holds, by using the block assigned to the RecordSet.
+    def snapshot!
+      if @getter.is_a?(Proc)
+        clear
+        self << @getter.call
+      else
+        nil
+      end
+    end
+
+    # Returns a simple Array of the collection - provided public mostly for debugging purposes. Typically you won't use this method
+    # publicly in production code.
+    def set
+      @set ||= []
+    end
+
+    def [](i) # :nodoc:
+      set[i]
+    end
+
+    def <<(values) # :nodoc:
+      [values].flatten.compact.each do |rec|
+        rec.extend Record
+        rec.source = @source
+        @set << rec
+      end
+    end
+
+    # Same as RecordSet#find (below), but removes the found record from this RecordSet.
+    def delete(record_or_identifier)
+      identifier = get_mapped_identifier(record_or_identifier)
+      !!(set.reject! {|e| e.identifier == identifier})
+    end
+
+    # Finds a in this RecordSet given a record from another RecordSet on another source, or returns nil on not found.
+    def find(record)
+      # ident_key = source.mapping_to(record.source)[source.identifier.to_s]
+      # ident = {source.identifier.to_s => record.send(ident_key)}
+      set.reject {|e| e.identifier != record.identifier}[0]
+    end
+
+    def each(&block) # :nodoc:
+      set.each(&block)
+    end
+
+    # Simply clears the collection.
+    def clear
+      set.clear
+    end
+
+    def length # :nodoc:
+      set.length
+    end
+
+    private
+      def get_mapped_identifier(record_or_identifier)
+        if record_or_identifier.respond_to?(:identifier)
+          (record_or_identifier.source == @source ? record_or_identifier : record_or_identifier.morph_to(@source)).identifier
+        else
+          record_or_identifier
+        end
+      end
+  end
+
+  # The Record module is used to extend record objects with a couple methods needed for sync-ing purposes.
+  module Record
+    def self.extended(base)
+      # Automatically adds 'identifier' method to the object if the object's class has an 'identifier'
+      # method that mentions the name of the identifier attribute.
+      def base.identifier
+        send(self.class.identifier.to_sym)
+      end if base.class.respond_to?(:identifier) && !base.respond_to?(:identifier)
+    end
+    attr_accessor :source
+    def morph_to(target)
+      raise ArgumentError, "can only morph by known mappings." unless source.can_map?(target)
+      new_attrs = to_hash.merge(self.class.identifier => identifier).transform_keys_by_mapping(source.mapping_to(target))
+      rec = target.initialize_record(target.klass.new(new_attrs))
+      rec.extend Record
+      rec.source = target
+      rec
+    end
+# slave  from master:  {self =>        rec(external_id):map}
+# slave  from deleted: {self =>        rec(external_id):map}
+# master from slave:   {external_id => rec(self):map}
+# master from deleted: {external_id => rec(self):map}
+    def find_on(target)
+      ident_key = target.mapping_to(source)[target.identifier.to_s]
+      ident = {target.identifier.to_s => send(ident_key)}
+      # puts "Looking for record #{source.identifier.to_s} => #{identifier} as record #{ident_key} => #{ident.inspect}"
+      found = ident.values[0].nil? ? nil : target.get(ident)
+      # puts "Found: #{found.inspect}"
+      found.extend Record
+      found.source = target
+      found
+    end
+  end
+end
+
+# A little enhancement that we need...
+class Hash
+  # Given a mapping (hash), this will transform the keys from the keys to the values in the mapping.
+  # For example:
+  #   mapping = {:cat => :Cat, :dog => :Canine}
+  #   hash = {:cat => 'Felix', :dog => 'Toby'}
+  #   hash.transform_keys_by_mapping(mapping)
+  #   => {:Cat => 'Felix', :Canine => 'Toby'}
+  def transform_keys_by_mapping(mapping)
+    ddup = {}
+    self.each do |k,v|
+      if mapping[k]
+        if mapping[k].is_a?(Proc)
+          ddup = mapping[k].call(ddup,v)
+        else
+          ddup[mapping[k]] = v
+        end
+      end
+    end
+    ddup
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification 
+name: simplesync
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Daniel Parker
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-03-20 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: "QuickSync: an interface to synchronization logic."
+email: gems@behindlogic.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+files: 
+- lib/simple_sync.rb
+- LICENSE
+- Rakefile
+- README
+- doc/classes
+- doc/classes/Hash.html
+- doc/classes/Hash.src
+- doc/classes/Hash.src/M000001.html
+- doc/classes/SimpleSync
+- doc/classes/SimpleSync/Mappings.html
+- doc/classes/SimpleSync/Mappings.src
+- doc/classes/SimpleSync/Mappings.src/M000026.html
+- doc/classes/SimpleSync/Mappings.src/M000027.html
+- doc/classes/SimpleSync/Record.html
+- doc/classes/SimpleSync/Record.src
+- doc/classes/SimpleSync/Record.src/M000002.html
+- doc/classes/SimpleSync/Record.src/M000003.html
+- doc/classes/SimpleSync/Record.src/M000004.html
+- doc/classes/SimpleSync/RecordSet.html
+- doc/classes/SimpleSync/RecordSet.src
+- doc/classes/SimpleSync/RecordSet.src/M000028.html
+- doc/classes/SimpleSync/RecordSet.src/M000029.html
+- doc/classes/SimpleSync/RecordSet.src/M000030.html
+- doc/classes/SimpleSync/RecordSet.src/M000031.html
+- doc/classes/SimpleSync/RecordSet.src/M000032.html
+- doc/classes/SimpleSync/Source.html
+- doc/classes/SimpleSync/Source.src
+- doc/classes/SimpleSync/Source.src/M000005.html
+- doc/classes/SimpleSync/Source.src/M000006.html
+- doc/classes/SimpleSync/Source.src/M000007.html
+- doc/classes/SimpleSync/Source.src/M000008.html
+- doc/classes/SimpleSync/Source.src/M000009.html
+- doc/classes/SimpleSync/Source.src/M000010.html
+- doc/classes/SimpleSync/Source.src/M000011.html
+- doc/classes/SimpleSync/Source.src/M000012.html
+- doc/classes/SimpleSync/Source.src/M000013.html
+- doc/classes/SimpleSync/Syncer.html
+- doc/classes/SimpleSync/Syncer.src
+- doc/classes/SimpleSync/Syncer.src/M000014.html
+- doc/classes/SimpleSync/Syncer.src/M000015.html
+- doc/classes/SimpleSync/Syncer.src/M000016.html
+- doc/classes/SimpleSync/Syncer.src/M000017.html
+- doc/classes/SimpleSync/Syncer.src/M000018.html
+- doc/classes/SimpleSync/Syncer.src/M000019.html
+- doc/classes/SimpleSync/Syncer.src/M000020.html
+- doc/classes/SimpleSync/Syncer.src/M000021.html
+- doc/classes/SimpleSync/Syncer.src/M000022.html
+- doc/classes/SimpleSync/Syncer.src/M000023.html
+- doc/classes/SimpleSync/Syncer.src/M000024.html
+- doc/classes/SimpleSync/Syncer.src/M000025.html
+- doc/classes/SimpleSync.html
+- doc/created.rid
+- doc/files
+- doc/files/lib
+- doc/files/lib/simple_sync_rb.html
+- doc/files/LICENSE.html
+- doc/files/README.html
+- doc/fr_class_index.html
+- doc/fr_file_index.html
+- doc/fr_method_index.html
+- doc/index.html
+- doc/rdoc-style.css
+has_rdoc: true
+homepage: http://simplesync.rubyforge.org
+post_install_message: 
+rdoc_options: []
+
+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: simplesync
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: "QuickSync: an interface to synchronization logic."
+test_files: []
+