caruby-core 1.4.2 → 1.4.3

data/lib/caruby/domain/id_alias.rb

@@ -0,0 +1,22 @@
+module CaRuby
+  # Mix-in for Java classes which have an +id+ property.
+  # Since +id+ is a reserved Ruby method, this mix-in defines an +identifier+ attribute
+  # which fronts the +id+ property.
+  module IdAlias
+    # Returns the identifier.
+    # This method delegates to the Java +id+ property reader method.
+    #
+    # @return [Integer] the identifier value
+    def identifier
+      getId
+    end
+
+    # Sets the identifier to the given value.
+    # This method delegates to the Java +id+ property writer method.
+    #
+    # @param [Integer] value the value to set
+    def identifier=(value)
+      setId(value)
+    end
+  end
+end

data/lib/caruby/domain/inversible.rb

@@ -0,0 +1,91 @@
+require 'caruby/util/log'
+require 'caruby/database/persistable'
+require 'caruby/util/pretty_print'
+
+module CaRuby
+  # {Resource} inverse integrity aspect 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
+    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
+    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)
+    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 oldval == newval
+
+      # 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_attribute(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/caruby/domain/merge.rb

@@ -1,5 +1,5 @@
 module CaRuby
-  # A Mergeable supports merging attribute values.
+  # 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
@@ -17,21 +17,25 @@ module CaRuby
     # 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 the intersection of this object's
-    # mergeable attributes and the other object's mergeable attributes as determined by
+    # this object. The default attributes is this mergeable's class
     # {ResourceAttributes#mergeable_attributes}.
     #
-    # #merge_attribute is called on each attribute with the merger block given to this
-    # method.
+    # 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 {ResourceAttributes#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, &merger) # :yields: attribute, oldval, newval
+    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
@@ -39,51 +43,128 @@ module CaRuby
       # 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
-      suspend_lazy_loader do
-        vh.each { |attr, value| merge_attribute(attr, value, &merger) }
-      end
+      vh.each { |attr, value| merge_attribute(attr, value, matches, &merger) }
       self
     end
 
     alias :merge :merge_attributes
 
     alias :merge! :merge
-
-    # Merges value into attribute as follows:
-    # * if the value is nil, empty or equal to the current attribute value, then no merge
-    #   is performed
-    # * otherwise, if the merger block is given to this method, then that block is called
-    #   to perform the merge
-    # * otherwise, if the current value responds to the merge! method, then that method
-    #   is called recursively on the current value
-    # * otherwise, if the current value is nil, then the attribute is set to value
-    # * otherwise, no merge is performed
+    
+    # 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.
     #
-    # Returns the merged value.
-    def merge_attribute(attribute, value, &merger) # :yields: attribute, oldval, newval
+    # @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, then return the unchanged previous value.
-      # otherwise, if a merge block is given, then call it.
-      # otherwise, if nothing to merge into then set the attribute to the new value.
-      # otherwise, if the previous value is mergeable, then merge the new value into it.
-      if value.nil_or_empty? or mergeable__equal?(oldval, value) then
-        oldval
+      # 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
-        yield(attribute, oldval, value)
-      elsif oldval.nil? then
-        send("#{attribute}=", value)
-      elsif oldval.respond_to?(:merge!) then
-        oldval.merge!(value)
+        return yield(attribute, oldval, value)
+      end
+      
+      # Discriminate between a domain and non-domain attribute.
+      attr_md = self.class.attribute_metadata(attribute)
+      if attr_md.domain? then
+        merge_domain_attribute_value(attr_md, oldval, newval, matches)
       else
-        oldval
+        merge_nondomain_attribute_value(attr_md, oldval, newval)
       end
     end
 
     private
 
-    # Fixes a rare Java TreeSet aberration: comparison uses the TreeSet comparator rather than an element-wise comparator.
+    # @see #merge_attribute
+    def merge_nondomain_attribute_value(attr_md, oldval, newval)
+      oldval.nil? ? send(attr_md.writer, newval) : oldval
+    end
+    
+    # @see #merge_attribute
+    def merge_domain_attribute_value(attr_md, oldval, newval, matches)
+      # the dependent owner writer method, if any
+      inv_md = attr_md.inverse_attribute_metadata
+      if inv_md and not inv_md.collection? then
+        owtr = inv_md.writer
+      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 attr_md.collection? then
+        # TODO - refactor into method
+        if oldval.nil? then
+          raise ValidationError.new("Merge into #{qp} #{attr_md} with nil collection value is not supported")
+        end
+        # the references to add
+        adds = []
+        logger.debug { "Merging #{newval.qp} into #{qp} #{attr_md} #{oldval.qp}..." } unless newval.empty?
+        newval.each 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 oldval.include?(tgt) then
+              tgt.merge_attributes(src)
+            else
+              adds << tgt
+            end
+          else
+            adds << src
+          end
+        end
+        # add the unmatched sources
+        logger.debug { "Adding #{qp} #{attr_md} 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(attr_md, 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
+        ref ||= newval
+        logger.debug { "Setting #{qp} #{attr_md} 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(attr_md, ref, owtr) : send(attr_md.writer, ref)
+      end
+      newval
+    end
+
+    # Java alert - 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

data/lib/caruby/domain/properties.rb

@@ -44,7 +44,7 @@ module CaRuby
       # Loads the properties in the following low-to-high precedence order:
       # * the home file +.+_application_+.yaml+, where _application_ is the application name
       # * the given property file
-      # * the environment varialables
+      # * the environment variables
       def load_properties(file)
         # canonicalize the file path
         file = File.expand_path(file)

data/lib/caruby/domain/reference_visitor.rb

@@ -27,8 +27,8 @@ module CaRuby
     # @yield [ref] selects which attributes to visit next
     # @yieldparam [Resource] ref the currently visited domain object
     def initialize(options=nil, &selector)
-      # use the default attributes if no block given
-      @slctr = selector || Proc.new { |obj| obj.class.saved_domain_attributes }
+      raise ArgumentError.new("Reference visitor missing domain reference selector") unless block_given?
+      @selector = selector
       # delegate to Visitor with the visit selector block
       super { |parent| references_to_visit(parent) }
       # the visited reference => parent attribute hash
@@ -74,8 +74,8 @@ module CaRuby
     # @yield [ref, others] matches ref in others (optional)
     # @yieldparam [Resource] ref the domain object to match
     # @yieldparam [<Resource>] the candidates for matching ref
-    def sync
-      block_given? ? super : super { |ref, others| ref.match_in(others) }
+    def sync(&matcher)
+      MatchVisitor.new(:matcher => matcher, &@selector)
     end
 
     protected
@@ -86,13 +86,20 @@ module CaRuby
     end
 
     private
+    
+    # @param [Resource] parent the referencing domain object
+    # @return [<Resource>] the domain attributes to visit next
+    def attributes_to_visit(parent)
+       @selector.call(parent)
+    end
 
-    # @return the domain objects to visit next for the given parent
+    # @param [Resource] parent the referencing domain object
+    # @return [<Resource>] the referenced domain objects to visit next for the given parent
     def references_to_visit(parent)
-      attributes = @slctr.call(parent)
-      if attributes.nil? then return Array::EMPTY_ARRAY end
+      attrs = attributes_to_visit(parent)
+      if attrs.nil? then return Array::EMPTY_ARRAY end
       refs = []
-      attributes.each do | attr|
+      attrs.each do | attr|
         # the reference(s) to visit
         value = parent.send(attr)
         # associate each reference to visit with the current visited attribute
@@ -104,45 +111,44 @@ module CaRuby
       if DETAIL_DEBUG then
         logger.debug { "Visiting #{parent.qp} references: #{refs.qp}" }
         logger.debug { " lineage: #{lineage.qp}" }
-        logger.debug { " attributes: #{@ref_attr_hash.qp}..." }
+        logger.debug { " attributes: #{attrs.qp}..." }
       end
+      
       refs
     end
   end
-
-  # A MergeVisitor merges a domain object's visitable attributes transitive closure into a target.
-  class MergeVisitor < ReferenceVisitor
+  
+  # A MatchVisitor visits two domain objects' visitable attributes transitive closure in lock-step.
+  class MatchVisitor < ReferenceVisitor
 
     attr_reader :matches
 
-    # Creates a new MergeVisitor on domain attributes.
+    # 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 as described in {ReferenceVisitor#initialize}.
+    # this initializer. The selector arguments consist of the match source and target.
     #
-    # @param [Hash] options the visit options
-    # @option options [Proc] :mergeable the mergeable domain attribute selector
-    # @option options [Proc] :matcher the match block
-    # @option options [Proc] :copier the unmatched source copy block
-    # @yield [source, target] the visit domain attribute selector block
-    # @yieldparam [Resource] source the current merge source domain object
-    # @yieldparam [Resource] target the current merge target domain object
-    def initialize(options=nil, &selector)
+    # @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 [Proc] :matcher the block 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)
       raise ArgumentError.new("Reference visitor missing domain reference selector") unless block_given?
-      options = Options.to_hash(options)
-      @mergeable = options.delete(:mergeable) || selector
-      @matcher = options.delete(:matcher) || Resource.method(:match_all)
-      @copier = options.delete(:copier)
+      opts = Options.to_hash(opts)
+      @matcher = opts.delete(:matcher) || Resource.method(:match_all)
+      @matchable = opts.delete(:matchable)
+      @copier = opts.delete(:copier)
       # the source => target matches
       @matches = {}
       # the class => {id => target} hash
       @id_mtchs = LazyHash.new { Hash.new }
-      super do |src|
-        tgt = @matches[src]
-        yield(src, tgt) if tgt
-      end
+      super { |src| yield(src) if @matches[src] }
     end
 
-    # Visits the source and target and returns a recursive copy of obj and each of its visitable references.
+    # 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
@@ -150,15 +156,15 @@ module CaRuby
     #
     # caCORE alert = caCORE does not enforce reference identity integrity, i.e. a search on object _a_
     # with database record references _a_ => _b_ => _a_, the search result might be _a_ => _b_ => _a'_,
-    # where _a.identifier_ == _a'.identifier_. This visit method remedies the caCORE defect by matching source
-    # references on a previously matched identifier where possible.
+    # where _a.identifier_ == _a'.identifier_. This visit method remedies this caCORE defect by matching
+    # source references on a previously matched identifier where possible.
     #
-    # @param [Resource] target the domain object to merge into 
-    # @param [Resource] source the domain object to merge from
-    # @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
+    # @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
-    def visit(target, source)
+    # @yieldparam [Resource] target the domain object which matches the visited source
+    def visit(source, target, &block)
       # clear the match hashes
       @matches.clear
       @id_mtchs.clear
@@ -166,57 +172,96 @@ module CaRuby
       add_match(source, target)
       # visit the source reference. the visit block merges each source reference into
       # the matching target reference.
-      super(source) do |src|
-        tgt = match(src) || next
-        merge(tgt, src)
-        block_given? ? yield(tgt, src) : tgt
-      end
+      super(source) { |src| visit_matched(src, &block) }
     end
 
     private
-
-    # Merges the given source object into the target object.
+    
+    # Visits the given source domain object.
     #
-    # @param [Resource] target thedomain object to merge into
-    # @param [Resource] source the domain object to merge from
-    def merge(target, source)
-      # the domain attributes to merge; non-domain attributes are always merged
-      attrs = @mergeable.call(source, target)
-      # Match each source reference to a target reference.
-      target.merge_match(source, attrs, &method(:match_all))
+    # @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
+    def visit_matched(source)
+      target = match_for_visited(source)
+      # match the matchable references, if any
+      if @matchable then
+        attrs = @matchable.call(source) - attributes_to_visit(source)
+        attrs.each { |attr| match_reference(source, target, attr) }
+      end
+      block_given? ? yield(source, target) : target
+    end
+
+    # @param source (see #match_visited)
+    # @return [<Resource>] the domain objects referenced by the source to visit next
+    def references_to_visit(source)
+      # the source match
+      target = match_for_visited(source)
+      # the attributes to visit
+      attrs = attributes_to_visit(source)
+      # the matched source references
+      match_references(source, target, attrs).keys
+    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 raise ValidationError.new("Match visitor target not found for #{source}") end
       target
     end
 
-    # Matches the given sources to targets. The match is performed by this visitor's matcher Proc.
+    # @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 |attr|
+        matches.merge!(match_reference(source, target, attr))
+      end
+      matches
+    end
+    
+    # Matches the given source and target attribute references.
+    # The match is performed by this visitor's matcher Proc.
     #
-    # @param [<Resource>] sources the domain objects to match
-    # @param [<Resource>] targets the match candidates
-    # @return [{Resource => Resource}] the source => target matches
-    def match_all(sources, targets)
-     # the match targets
+    # @param source (see #visit)
+    # @param target (see #visit)
+    # @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 = sources.reject do |src|
+      unmtchd_srcs = srcs.reject do |src|
         # the prior match, if any
-        tgt = match(src)
+        tgt = match_for(src)
         mtchd_tgts << tgt if tgt
       end
+      
       # the unmatched targets
-      unmtchd_tgts = targets.difference(mtchd_tgts)
-
+      unmtchd_tgts = tgts.difference(mtchd_tgts)
       # match the residual targets and sources
       rsd_mtchs = @matcher.call(unmtchd_srcs, unmtchd_tgts)
       # add residual matches
       rsd_mtchs.each { |src, tgt| add_match(src, tgt) }
+      
       # The source => target match hash.
       # If there is a copier, then copy each unmatched source.
-      matches = sources.to_compact_hash { |src| match(src) or copy_unmatched(src) }
-      logger.debug { "Merge visitor matched #{matches.qp}." } unless matches.empty?
+      matches = srcs.to_compact_hash { |src| match_for(src) or copy_unmatched(src) }
+      logger.debug { "Match visitor matched #{matches.qp}." } unless matches.empty?
+      
       matches
     end
 
     # @return the target matching the given source
-    def match(source)
+    def match_for(source)
       @matches[source] or identifier_match(source)
     end
     
@@ -232,7 +277,8 @@ module CaRuby
       @matches[source] = tgt if tgt
     end
 
-    # @return [Resource, nil] a copy of the given source if this ReferenceVisitor has a copier, nil otherwise
+    # @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)
@@ -240,13 +286,99 @@ module CaRuby
     end
   end
 
+  # 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
+      unless @mergeable == selector then
+        opts[:matchable] = @mergeable
+      end
+      super
+    end
+
+    # Visits the source and target and returns a recursive copy of obj and each of its visitable references.
+    #
+    # 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.
+    #
+    # caCORE alert = caCORE does not enforce reference identity integrity, i.e. a search on object _a_
+    # with database record references _a_ => _b_ => _a_, the search result might be _a_ => _b_ => _a'_,
+    # where _a.identifier_ == _a'.identifier_. This visit method remedies the caCORE defect by matching source
+    # references on a previously matched identifier where possible.
+    #
+    # @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)
+      # visit the source reference. the visit block merges each source reference into
+      # the matching target reference.
+      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)
+      # the domain attributes to merge
+      attrs = @mergeable.call(source)
+      logger.debug { format_merge_log_message(source, target, attrs) }
+      # merge the non-domain attributes
+      target.merge_attributes(source)
+      # merge the source domain attributes into the target
+      target.merge(source, attrs, @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
+
   # 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}.
-    def initialize(options=nil) # :yields: source
-      options = Options.to_hash(options)
-      options[:copier] ||= Proc.new { |src| src.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] = Proc.new { Hash::EMPTY_HASH }
       super
     end
 
@@ -254,9 +386,13 @@ module CaRuby
     #
     # If a block is given to this method, then the block is called with the visited
     # source reference and its matching copy target.
-    def visit(source, &block) # :yields: target, source
+    #
+    # @param (see MergeVisitor#visit)
+    # @yield (see MergeVisitor#visit)
+    # @yieldparam (see MergeVisitor#visit)
+    def visit(source, &block)
       target = @copier.call(source)
-      super(target, source, &block)
+      super(source, target, &block)
     end
   end