jinx 2.1.1

data/lib/jinx/resource/copy_visitor.rb

@@ -0,0 +1,36 @@
+require 'jinx/resource/merge_visitor'
+
+module Jinx
+  # A CopyVisitor copies a domain object's visitable attributes transitive closure.
+  class CopyVisitor < MergeVisitor
+    # Creates a new CopyVisitor with the options described in {MergeVisitor#initialize}.
+    # The default :copier option is {Resource#copy}.
+    #
+    # @param (see MergeVisitor#initialize)
+    # @option opts [Proc] :mergeable the mergeable domain attribute selector
+    # @option opts [Proc] :matcher the match block
+    # @option opts [Proc] :copier the unmatched source copy block
+    # @yield (see MergeVisitor#initialize)
+    # @yieldparam (see MergeVisitor#initialize)
+    def initialize(opts=nil)
+      opts = Options.to_hash(opts)
+      opts[:copier] ||= Proc.new { |src| src.copy }
+      # no match forces a copy
+      opts[:matcher] = self
+      super
+    end
+
+    # Copies the given source domain object's reference graph.
+    #
+    # @param (see MergeVisitor#visit)
+    # @return [Resource] the source copy
+    def visit(source)
+      target = @copier.call(source)
+      super(source, target)
+    end
+    
+    def match(sources, targets, from=nil, property=nil)
+      Hash::EMPTY_HASH
+    end
+  end
+end

data/lib/jinx/resource/inversible.rb

@@ -0,0 +1,90 @@
+module Jinx
+  # {Resource} inverse integrity aspect mix-in. The {Inversible} methods are intended for the
+  # sole use of the {Inverse} class mix-in.
+  module Inversible
+    # Sets an attribute inverse by calling the attribute writer method with the other argument.
+    # If other is non-nil, then the inverse writer method is called on self.
+    #
+    # @param other [Resource] the attribute value to set
+    # @param [Symbol] writer the attribute writer method
+    # @param [Symbol] inv_writer the attribute inverse writer method defined for the other object
+    # @private
+    def set_inverse(other, writer, inv_writer)
+      other.send(inv_writer, self) if other
+      send(writer, other)
+    end
+    
+    # Sets a non-collection attribute value in a way which enforces inverse integrity.
+    #
+    # @param [Object] newval the value to set
+    # @param [(Symbol, Symbol)] accessors the reader and writer methods to use in setting the
+    #   attribute
+    # @param [Symbol] inverse_writer the inverse attribute writer method
+    # @private
+    def set_inversible_noncollection_attribute(newval, accessors, inverse_writer)
+      rdr, wtr = accessors
+      # the previous value
+      oldval = send(rdr)
+      # bail if no change
+      return newval if newval.equal?(oldval)
+
+      # clear the previous inverse
+      logger.debug { "Moving #{qp} from #{oldval.qp} to #{newval.qp}..." } if oldval and newval
+      if oldval then
+        clr_wtr = self.class === oldval && oldval.send(rdr).equal?(self) ? wtr : inverse_writer
+        oldval.send(clr_wtr, nil)
+      end
+      # call the writer
+      send(wtr, newval)
+      # call the inverse writer on self
+      if newval then
+        newval.send(inverse_writer, self)
+        logger.debug { "Moved #{qp} from #{oldval.qp} to #{newval.qp}." } if oldval
+      end
+      
+      newval
+    end
+
+    # Sets a collection attribute value in a way which enforces inverse integrity.
+    # The inverse of the attribute is a collection accessed by calling inverse on newval.
+    #
+    # @param [Resource] newval the new attribute reference value
+    # @param [(Symbol, Symbol)] accessors the reader and writer to use in setting
+    #   the attribute
+    # @param [Symbol] inverse the inverse collection attribute to which
+    #   this domain object will be added
+    # @yield a factory to create a new collection on demand (default is an Array)
+    # @private
+    def add_to_inverse_collection(newval, accessors, inverse)
+      rdr, wtr = accessors
+      # the current inverse
+      oldval = send(rdr)
+      # no-op if no change
+      return newval if newval == oldval
+
+      # delete self from the current inverse reference collection
+      if oldval then
+        coll = oldval.send(inverse)
+        coll.delete(self) if coll
+      end
+      # call the writer on this object
+      send(wtr, newval)
+      # add self to the inverse collection
+      if newval then
+        coll = newval.send(inverse)
+        if coll.nil? then
+          coll = block_given? ? yield : Array.new
+          newval.set_property_value(inverse, coll)
+        end
+        coll << self
+        if oldval then
+          logger.debug { "Moved #{qp} from #{rdr} #{oldval.qp} #{inverse} to #{newval.qp}." }
+        else
+          logger.debug { "Added #{qp} to #{rdr} #{newval.qp} #{inverse}." }
+        end
+      end
+      
+      newval
+    end
+  end
+end

data/lib/jinx/resource/match_visitor.rb

@@ -0,0 +1,180 @@
+require 'jinx/helpers/lazy_hash'
+require 'jinx/resource/reference_visitor'
+
+module Jinx
+  # A MatchVisitor visits two domain objects' visitable attributes transitive closure in lock-step.
+  class MatchVisitor < ReferenceVisitor
+    # @return [{Resource => Resource}] the domain object matches
+    attr_reader :matches
+
+    # Creates a new visitor which matches source and target domain object references.
+    # The domain attributes to visit are determined by calling the selector block given to
+    # this initializer. The selector arguments consist of the match source and target.
+    #
+    # @param (see ReferenceVisitor#initialize)
+    # @option opts [Proc] :mergeable the block which determines which attributes are merged
+    # @option opts [Proc] :matchable the block which determines which attributes to match
+    #   (default is the visit selector)
+    # @option opts [:match] :matcher an object which matches sources to targets
+    # @option opts [Proc] :copier the block which copies an unmatched source
+    # @yield (see ReferenceVisitor#initialize)
+    # @yieldparam [Resource] source the matched source object
+    def initialize(opts=nil)
+      Jinx.fail(ArgumentError, "Reference visitor missing domain reference selector") unless block_given?
+      opts = Options.to_hash(opts)
+      @matcher = opts.delete(:matcher) || DEF_MATCHER
+      @matchable = opts.delete(:matchable)
+      @copier = opts.delete(:copier)
+      # the source => target matches
+      @matches = {}
+      # Apply a filter to the selected references so that only a matched reference is visited.
+      opts[:filter] = Proc.new { |src| @matches[src] }
+      # the class => {id => target} hash
+      @id_mtchs = LazyHash.new { Hash.new }
+      # Match the source references before navigating from the source to its references, since
+      # only a matched reference is visited.
+      super do |src|
+        tgt = @matches[src]
+        attrs = yield(src)
+        match_references(src, tgt, attrs)
+        attrs
+      end
+    end
+
+    # Visits the source and target.
+    #
+    # If a block is given to this method, then this method returns the evaluation of the block on the visited
+    # source reference and its matching copy, if any. The default return value is the target which matches
+    # source.
+    #
+    # @param [Resource] source the match visit source
+    # @param [Resource] target the match visit target
+    # @yield [target, source] the optional block to call on the matched source and target
+    # @yieldparam [Resource] source the visited source domain object
+    # @yieldparam [Resource] target the domain object which matches the visited source
+    # @yieldparam [Resource] from the visiting domain object
+    # @yieldparam [Property] property the visiting property
+    def visit(source, target, &block)
+      # clear the match hashes
+      @matches.clear
+      @id_mtchs.clear
+      # seed the matches with the top-level source => target
+      add_match(source, target)
+      # Visit the source reference.
+      super(source) { |src| visit_matched(src, &block) }
+    end
+
+    private
+    
+    # Matches sources to targets using {Resource#match_all}
+    class DefaultMatcher
+      def match(sources, targets, from, attribute)
+        Resource.match_all(sources, targets)
+      end
+    end
+    
+    DEF_MATCHER = DefaultMatcher.new
+    
+    # Visits the given source domain object.
+    #
+    # @param [Resource] source the match visit source
+    # @yield [target, source] the optional block to call on the matched source and target
+    # @yieldparam [Resource] source the visited source domain object
+    # @yieldparam [Resource] target the domain object which matches the visited source
+    # @yieldparam [Resource] from the visiting domain object
+    # @yieldparam [Property] property the visiting property
+    def visit_matched(source)
+      tgt = @matches[source] || return
+      # Match the unvisited matchable references, if any.
+      if @matchable then
+        mas = @matchable.call(source) - attributes_to_visit(source)
+        mas.each { |ma| match_reference(source, tgt, ma) }
+      end
+      block_given? ? yield(source, tgt) : tgt
+    end
+    
+    # @param source (see #match_visited)
+    # @return [<Resource>] the source match
+    # @raise [ValidationError] if there is no match
+    def match_for_visited(source)
+      target = @matches[source]
+      if target.nil? then Jinx.fail(ValidationError, "Match visitor target not found for #{source}") end
+      target
+    end
+
+    # @param [Resource] source (see #match_visited)
+    # @param [Resource] target the source match
+    # @param [<Symbol>] attributes the attributes to match on
+    # @return [{Resource => Resource}] the referenced attribute matches
+    def match_references(source, target, attributes)
+      # collect the references to visit
+      matches = {}
+      attributes.each do |ma|
+        matches.merge!(match_reference(source, target, ma))
+      end
+      matches
+    end
+    
+    # Matches the given source and target attribute references.
+    # The match is performed by this visitor's matcher.
+    #
+    # @param source (see #visit)
+    # @param target (see #visit)
+    # @param [Symbol] attribute the parent reference attribute
+    # @return [{Resource => Resource}] the referenced source => target matches
+    def match_reference(source, target, attribute)
+      srcs = source.send(attribute).to_enum
+      tgts = target.send(attribute).to_enum
+      
+      # the match targets
+      mtchd_tgts = Set.new
+      # capture the matched targets and the the unmatched sources
+      unmtchd_srcs = srcs.reject do |src|
+        # the prior match, if any
+        tgt = match_for(src)
+        mtchd_tgts << tgt if tgt
+      end
+      
+      # the unmatched targets
+      unmtchd_tgts = tgts.difference(mtchd_tgts)
+      logger.debug { "#{qp} matching #{unmtchd_tgts.qp}..." } if @verbose and not unmtchd_tgts.empty?
+      # match the residual targets and sources
+      rsd_mtchs = @matcher.match(unmtchd_srcs, unmtchd_tgts, source, attribute)
+      # add residual matches
+      rsd_mtchs.each { |src, tgt| add_match(src, tgt) }
+      logger.debug { "#{qp} matched #{rsd_mtchs.qp}..." } if @verbose and not rsd_mtchs.empty?
+      
+      # The source => target match hash.
+      # If there is a copier, then copy each unmatched source.
+      matches = srcs.to_compact_hash { |src| match_for(src) or copy_unmatched(src) }
+      
+      matches
+    end
+
+    # @return the target matching the given source
+    def match_for(source)
+      @matches[source] or identifier_match(source)
+    end
+    
+    def add_match(source, target)
+      @matches[source] = target
+      @id_mtchs[source.class][source.identifier] = target if source.identifier
+      target
+    end
+
+    # @return the target matching the given source on the identifier, if any
+    def identifier_match(source)
+      tgt = @id_mtchs[source.class][source.identifier] if source.identifier
+      @matches[source] = tgt if tgt
+    end
+
+    # @return [Resource, nil] a copy of the given source if this ReferenceVisitor has a copier,
+    #   nil otherwise
+    def copy_unmatched(source)
+      return unless @copier
+      copy = @copier.call(source)
+      logger.debug { "#{qp} copied unmatched #{source} to #{copy}." } if @verbose
+      add_match(source, copy)
+    end
+  end
+end

data/lib/jinx/resource/matcher.rb

@@ -0,0 +1,20 @@
+module Jinx
+  module Resource
+    # Matches the given targets to sources using {Resource#match_in}.
+    # @private
+    class Matcher
+      def match(sources, targets)
+        unmatched = Set === sources ? sources.dup : sources.to_set
+        matches = {}
+        targets.each do |tgt|
+          src = tgt.match_in(unmatched)
+          if src then
+            unmatched.delete(src)
+            matches[src] = tgt
+          end
+        end
+        matches
+      end
+    end
+  end
+end

data/lib/jinx/resource/merge_visitor.rb

@@ -0,0 +1,73 @@
+require 'jinx/resource/match_visitor'
+
+module Jinx
+  # A MergeVisitor merges a domain object's visitable attributes transitive closure into a target.
+  class MergeVisitor < MatchVisitor
+    # Creates a new MergeVisitor on domain attributes.
+    # The domain attributes to visit are determined by calling the selector block given to
+    # this initializer as described in {ReferenceVisitor#initialize}.
+    #
+    # @param (see MatchVisitor#initialize)
+    # @option opts [Proc] :mergeable the block which determines which attributes are merged
+    # @option opts [Proc] :matcher the block which matches sources to targets
+    # @option opts [Proc] :copier the block which copies an unmatched source
+    # @yield (see MatchVisitor#initialize)
+    # @yieldparam (see MatchVisitor#initialize)
+    def initialize(opts=nil, &selector)
+      opts = Options.to_hash(opts)
+      # Merge is depth-first, since the source references must be matched, and created if necessary,
+      # before they can be merged into the target.
+      opts[:depth_first] = true
+      @mergeable = opts.delete(:mergeable) || selector
+      # each mergeable attribute is matchable
+      opts[:matchable] = @mergeable unless @mergeable == selector
+      super
+    end
+
+    # Visits the source and target reference graphs and recursively merges each matching source
+    # reference into its corresponding target reference.
+    #
+    # If a block is given to this method, then the block is called on each matched (source, target) pair.
+    #
+    # @param [Resource] source the domain object to merge from
+    # @param [Resource] target the domain object to merge into 
+    # @yield [target, source] the optional block to call on the visited source domain object and its
+    #   matching target
+    # @yieldparam [Resource] target the domain object which matches the visited source
+    # @yieldparam [Resource] source the visited source domain object
+    def visit(source, target)
+      super(source, target) do |src, tgt|
+         merge(src, tgt)
+         block_given? ? yield(src, tgt) : tgt
+      end
+    end
+
+    private
+
+    # Merges the given source object into the target object.
+    #
+    # @param [Resource] source the domain object to merge from
+    # @param [Resource] target the domain object to merge into
+    # @return [Resource] the merged target
+    def merge(source, target)
+      # trivial case
+      return target if source.equal?(target)
+      # the domain attributes to merge
+      mas = @mergeable.call(source)
+      logger.debug { format_merge_log_message(source, target, mas) }
+      # merge the non-domain attributes
+      target.merge_attributes(source)
+      # merge the source domain attributes into the target
+      target.merge(source, mas, @matches)
+    end
+    
+    # @param source (see #merge)
+    # @param target (see #merge)
+    # @param attributes (see Mergeable#merge)
+    # @return [String] the log message
+    def format_merge_log_message(source, target, attributes)
+      attr_clause = " including domain attributes #{attributes.to_series}" unless attributes.empty?
+      "Merging #{source.qp} into #{target.qp}#{attr_clause}..."
+    end
+  end
+end

data/lib/jinx/resource/mergeable.rb

@@ -0,0 +1,185 @@
+require 'jinx/helpers/validation'
+
+module Jinx
+  # A Mergeable supports merging {Resource} attribute values.
+  module Mergeable
+    # Merges the values of the other attributes into this object and returns self.
+    # The other argument can be either a Hash or an object whose class responds to the
+    # +mergeable_attributes+ method.
+    # The optional attributes argument can be either a single attribute symbol or a
+    # collection of attribute symbols.
+    #
+    # A hash argument consists of attribute name => value associations.
+    # For example, given a Mergeable +person+ object with attributes +ssn+ and +children+, the call:
+    #   person.merge_attributes(:ssn => '555-55-5555', :children => children)
+    # is equivalent to:
+    #   person.ssn ||= '555-55-5555'
+    #   person.children ||= []
+    #   person.children.merge(children, :deep)
+    # An unrecognized attribute is ignored.
+    #
+    # If other is not a Hash, then the other object's attributes values are merged into
+    # this object. The default attributes is this mergeable's class
+    # {Propertied#mergeable_attributes}.
+    #
+    # The merge is performed by calling {#merge_attribute} on each attribute with the matches
+    # and merger block given to this method.
+    #
+    # @param [Mergeable, {Symbol => Object}] other the source domain object or value hash to merge from
+    # @param [<Symbol>, nil] attributes the attributes to merge (default {Propertied#nondomain_attributes})
+    # @param [{Resource => Resource}, nil] the optional merge source => target reference matches
+    # @yield [attribute, oldval, newval] the optional merger block
+    # @yieldparam [Symbol] attribute the merge target attribute
+    # @yieldparam oldval the current merge attribute value
+    # @yieldparam newval the new merge attribute value
+    # @return [Mergeable] self
+    # @raise [ArgumentError] if none of the following are true:
+    #   * other is a Hash
+    #   * attributes is non-nil
+    #   * the other class responds to +mergeable_attributes+
+    def merge_attributes(other, attributes=nil, matches=nil, &merger)
+      return self if other.nil? or other.equal?(self)
+      attributes = [attributes] if Symbol === attributes
+      attributes ||= self.class.mergeable_attributes
+
+      # if the source object is not a hash, then convert it to an attribute => value hash
+      vh = Hashable === other ? other : other.value_hash(attributes)
+      # merge the value hash
+      vh.each { |pa, value| merge_attribute(pa, value, matches, &merger) }
+      self
+    end
+
+    alias :merge :merge_attributes
+
+    alias :merge! :merge
+    
+    # Merges the value newval into the attribute as follows:
+    # * If the value is nil, empty or equal to the current attribute value, then no merge
+    #   is performed.
+    # * Otherwise, if a merger block is given to this method, then that block is called
+    #   to perform the merge.
+    # * Otherwise, if the attribute is a non-domain attribute and the current value is non-nil,
+    #   then no merge is performed.
+    # * Otherwise, if the attribute is a non-domain attribute and the current value is nil,
+    #   then set the attribute to the newval.
+    # * Otherwise, if the attribute is a domain non-collection attribute, then newval is recursively
+    #   merged into the current referenced domain object.
+    # * Otherwise, attribute is a domain collection attribute and matching newval members are
+    #   merged into the corresponding current collection members and non-matching newval members
+    #   are added to the current collection.
+    #
+    # @param [Symbol] attribute the merge attribute
+    # @param newval the value to merge
+    # @param [{Resource => Resource}, nil] the optional merge source => target reference matches
+    # @yield (see #merge_attributes)
+    # @yieldparam (see #merge_attributes)
+    # @return the merged attribute value
+    def merge_attribute(attribute, newval, matches=nil)
+      # the previous value
+      oldval = send(attribute)
+      # If nothing to merge or a block can take over, then bail. 
+      if newval.nil? or mergeable__equal?(oldval, newval) then
+        return oldval
+      elsif block_given? then
+        return yield(attribute, oldval, value)
+      end
+      
+      # Discriminate between a domain and non-domain attribute.
+      prop = self.class.property(attribute)
+      if prop.domain? then
+        merge_domain_attribute_value(prop, oldval, newval, matches)
+      else
+        merge_nondomain_attribute_value(prop, oldval, newval)
+      end
+    end
+
+    private
+
+    # @see #merge_attribute
+    def merge_nondomain_attribute_value(prop, oldval, newval)
+      if oldval.nil? then
+        send(prop.writer, newval)
+      elsif prop.collection? then
+        oldval.merge(newval)
+      else
+        oldval
+      end
+    end
+    
+    # @see #merge_attribute
+    def merge_domain_attribute_value(prop, oldval, newval, matches)
+      # the dependent owner writer method, if any
+      if prop.dependent? then
+        val = prop.collection? ? newval.first : newval
+        klass = val.class if val
+        inv_prop = self.class.inverse_property(prop, klass)
+        if inv_prop and not inv_prop.collection? then
+          owtr = inv_prop.writer
+        end
+      end
+
+      # If the attribute is a collection, then merge the matches into the current attribute
+      # collection value and add each unmatched source to the collection.
+      # Otherwise, if the attribute is not yet set and there is a new value, then set it
+      # to the new value match or the new value itself if unmatched.
+      if prop.collection? then
+        # TODO - refactor into method
+        if oldval.nil? then
+          Jinx.fail(ValidationError, "Merge into #{qp} #{prop} with nil collection value is not supported")
+        end
+        # the references to add
+        adds = []
+        logger.debug { "Merging #{newval.qp} into #{qp} #{prop} #{oldval.qp}..." } unless newval.nil_or_empty?
+        newval.enumerate do |src|
+          # If the match target is in the current collection, then update the matched
+          # target from the source.
+          # Otherwise, if there is no match or the match is a new reference created
+          # from the match, then add the match to the oldval collection.
+          if matches && matches.has_key?(src) then
+            # the source match
+            tgt = matches[src]
+            if tgt then
+              if oldval.include?(tgt) then
+                tgt.merge_attributes(src)
+              else
+                adds << tgt
+              end
+            end
+          else
+            adds << src
+          end
+        end
+        # add the unmatched sources
+        logger.debug { "Adding #{qp} #{prop} unmatched #{adds.qp}..." } unless adds.empty?
+        adds.each do |ref|
+          # If there is an owner writer attribute, then add the ref to the attribute collection by
+          # delegating to the owner writer. Otherwise, add the ref to the attribute collection directly.
+          owtr ? delegate_to_inverse_setter(prop, ref, owtr) : oldval << ref
+        end
+        oldval
+      elsif newval.nil? then
+        # no merge source
+        oldval
+      elsif oldval then
+        # merge the source into the target
+        oldval.merge(newval)
+      else
+        # No target; set the attribute to the source.
+        # The target is either a source match or the source itself.
+        ref = (matches[newval] if matches) || newval
+        logger.debug { "Setting #{qp} #{prop} reference #{ref.qp}..." }
+        # If the target is a dependent, then set the dependent owner, which will in turn
+        # set the attribute to the dependent. Otherwise, set the attribute to the target.
+        owtr ? delegate_to_inverse_setter(prop, ref, owtr) : send(prop.writer, ref)
+      end
+      newval
+    end
+
+    # @quirk Java Java TreeSet comparison uses the TreeSet comparator rather than an
+    # element-wise comparator. Work around this rare aberration by converting the TreeSet
+    # to a Ruby Set.
+    def mergeable__equal?(v1, v2)
+      Java::JavaUtil::TreeSet === v1 && Java::JavaUtil::TreeSet === v2 ? v1.to_set == v2.to_set : v1 == v2
+    end
+  end
+end