caruby-core 1.4.9 → 1.5.1

data/lib/caruby/domain/inverse.rb

@@ -0,0 +1,173 @@
+require 'caruby/import/java'
+require 'caruby/domain/java_attribute'
+
+module CaRuby
+  module Domain
+    # Meta-data mix-in to infer and set inverse attributes.
+    module Inverse
+      
+      # Returns the inverse of the given attribute. If the attribute has an #{Attribute#inverse_metadata},
+      # then that attribute's inverse is returned. Otherwise, if the attribute is an #{Attribute#owner?},
+      # then the target class dependent attribute which matches this type is returned, if it exists.
+      #
+      # @param [Attribute] attr_md the subject attribute
+      # @param [Class, nil] klass the target class
+      # @return [Attribute, nil] the inverse attribute, if any
+      def inverse_attribute_metadata(attr_md, klass=nil)
+        inv_md = attr_md.inverse_metadata
+        return inv_md if inv_md
+        if attr_md.dependent? and klass then
+          klass.owner_attribute_metadata_hash.each { |otype, oattr_md|
+          return oattr_md if self <= otype }
+        end
+      end
+      
+      protected
+      
+      # Infers the inverse of the given attribute declared by this class. A domain attribute is
+      # recognized as an inverse according to the {Inverse#detect_inverse_attribute}
+      # criterion.
+      #
+      # @param [Attribute] attr_md the attribute to check
+      def infer_attribute_inverse(attr_md)
+        inv = attr_md.type.detect_inverse_attribute(self)
+        if inv then set_attribute_inverse(attr_md.to_sym, inv) end
+      end
+      
+      # Sets the given bi-directional association attribute's inverse.
+      #
+      # @param [Symbol] attribute the subject attribute
+      # @param [Symbol] the attribute inverse
+      # @raise [TypeError] if the inverse type is incompatible with this Resource
+      def set_attribute_inverse(attribute, inverse)
+        attr_md = attribute_metadata(attribute)
+        # return if inverse is already set
+        return if attr_md.inverse == inverse
+        # the default inverse
+        inverse ||= attr_md.type.detect_inverse_attribute(self)
+        # the inverse attribute meta-data
+        inv_md = attr_md.type.attribute_metadata(inverse)
+        # If the attribute is the many side of a 1:M relation, then delegate to the one side.
+        if attr_md.collection? and not inv_md.collection? then
+          return attr_md.type.set_attribute_inverse(inverse, attribute)
+        end
+        # This class must be the same as or a subclass of the inverse attribute type.
+        unless self <= inv_md.type then
+          raise TypeError.new("Cannot set #{qp}.#{attribute} inverse to #{attr_md.type.qp}.#{attribute} with incompatible type #{inv_md.type.qp}")
+        end
+        # If the attribute is not declared by this class, then make a new attribute
+        # metadata specialized for this class.
+        unless attr_md.declarer == self then
+          attr_md = restrict_attribute_inverse(attr_md, inverse)
+        end
+        # Set the inverse in the attribute metadata.
+        attr_md.inverse = inverse
+        # If attribute is the one side of a 1:M or non-reflexive 1:1 relation, then add the inverse updater.
+        unless attr_md.collection? then
+          # Make the 
+          add_inverse_updater(attribute, inverse)
+          unless attr_md.type == inv_md.type or inv_md.collection? then
+            attr_md.type.delegate_writer_to_inverse(inverse, attribute)
+          end
+        end
+      end
+      
+      # Detects an unambiguous attribute which refers to the given referencing class.
+      # If there is exactly one attribute with the given return type, then that attribute is chosen.
+      # Otherwise, the attribute whose name matches the underscored referencing class name is chosen,
+      # if any.
+      #
+      # @param [Class] klass the referencing class
+      # @return [Symbol, nil] the inverse attribute for the given referencing class and inverse,
+      #   or nil if no owner attribute was detected
+      def detect_inverse_attribute(klass)
+        # The candidate attributes return the referencing type and don't already have an inverse.
+        candidates = domain_attributes.compose { |attr_md| klass <= attr_md.type and attr_md.inverse.nil? }
+        attr = detect_inverse_attribute_from_candidates(klass, candidates)
+        if attr then
+          logger.debug { "#{qp} #{klass.qp} inverse attribute is #{attr}." }
+        else
+          logger.debug { "#{qp} #{klass.qp} inverse attribute was not detected." }
+        end
+        attr
+      end
+      
+      # Redefines the attribute writer method to delegate to its inverse writer.
+      # This is done to enforce inverse integrity.
+      #
+      # For a +Person+ attribute +account+ with inverse +holder+, this is equivalent to the following:
+      #   class Person
+      #     alias :set_account :account=
+      #     def account=(acct)
+      #       acct.holder = self if acct
+      #       set_account(acct)
+      #     end
+      #   end
+      def delegate_writer_to_inverse(attribute, inverse)
+        attr_md = attribute_metadata(attribute)
+        # nothing to do if no inverse
+        inv_attr_md = attr_md.inverse_metadata || return
+        logger.debug { "Delegating #{qp}.#{attribute} update to the inverse #{attr_md.type.qp}.#{inv_attr_md}..." }
+        # redefine the write to set the dependent inverse
+        redefine_method(attr_md.writer) do |old_writer|
+          # delegate to the CaRuby::Resource set_inverse method
+          lambda { |dep| set_inverse(dep, old_writer, inv_attr_md.writer) }
+        end
+      end
+  
+      private
+      
+      # Copies the given attribute metadata from its declarer to this class. The new attribute metadata
+      # has the same attribute access methods, but the declarer is this class and the inverse is the
+      # given inverse attribute.
+      #
+      # @param [Attribute] attr_md the attribute to copy
+      # @param [Symbol] the attribute inverse
+      # @return [Attribute] the copied attribute metadata
+      def restrict_attribute_inverse(attr_md, inverse)
+        rst_attr_md = attr_md.dup
+        rst_attr_md.declarer = self
+        add_attribute_metadata(rst_attr_md)
+        logger.debug { "Copied #{attr_md.declarer}.#{attr_md} to #{qp} with inverse #{inverse}." }
+        rst_attr_md
+      end
+      
+      # @param klass (see #detect_inverse_attribute)
+      # @param [<Symbol>] candidates the attributes constrained to the target type
+      # @return (see #detect_inverse_attribute)
+      def detect_inverse_attribute_from_candidates(klass, candidates)
+        return if candidates.empty?
+        # there can be at most one owner attribute per owner.
+        return candidates.first.to_sym if candidates.size == 1
+        # by convention, if more than one attribute references the owner type,
+        # then the attribute named after the owner type is the owner attribute
+        tgt = klass.name[/\w+$/].underscore.to_sym
+        tgt if candidates.detect { |attr| attr == tgt }
+      end
+      
+      # Modifies the given attribute writer method to update the given inverse.
+      #
+      # @param (see #set_attribute_inverse)
+      def add_inverse_updater(attribute, inverse)
+        attr_md = attribute_metadata(attribute)
+        # the reader and writer methods
+        rdr, wtr = attr_md.accessors
+        logger.debug { "Injecting inverse #{inverse} updater into #{qp}.#{attribute} writer method #{wtr}..." }
+        # the inverse atttribute metadata
+        inv_attr_md = attr_md.inverse_metadata
+        # the inverse attribute reader and writer
+        inv_rdr, inv_wtr = inv_accessors = inv_attr_md.accessors
+        # Redefine the writer method to update the inverse by delegating to the inverse
+        redefine_method(wtr) do |old_wtr|
+          # the attribute reader and (superseded) writer
+          accessors = [rdr, old_wtr]
+          if inv_attr_md.collection? then
+            lambda { |other| add_to_inverse_collection(other, accessors, inv_rdr) }
+          else
+            lambda { |other| set_inversible_noncollection_attribute(other, accessors, inv_wtr) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/caruby/domain/inversible.rb

@@ -60,14 +60,13 @@ module CaRuby
       # the current inverse
       oldval = send(rdr)
       # no-op if no change
-      return newval if oldval == newval
+      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

data/lib/caruby/domain/java_attribute.rb

@@ -0,0 +1,173 @@
+require 'caruby/util/inflector'
+require 'caruby/domain/attribute'
+
+module CaRuby
+  module Domain
+    # The attribute metadata for an introspected Java property. 
+    class JavaAttribute < Attribute
+  
+      # This attribute's Java property descriptor.
+      attr_reader :property_descriptor
+  
+      # This attribute's Java property [reader, writer] accessors, e.g. +[:getActivityStatus, :setActivityStatus]+.
+      attr_reader :property_accessors
+  
+      # Creates a Ruby Attribute symbol corresponding to the given Ruby Java class wrapper klazz
+      # and Java property_descriptor.
+      #
+      # The attribute name is the lower-case, underscore property descriptor name with the alterations
+      # described in {JavaAttribute.to_attribute_symbol} and {Class#unocclude_reserved_method}.
+      #
+      # The attribute type is inferred as follows:
+      # * If the property descriptor return type is a primitive Java type, then that type is returned.
+      # * If the return type is a parameterized collection, then the parameter type is returned.
+      # * If the return type is an unparameterized collection, then this method infers the type from
+      #   the property name, e.g. +StudyProtocolCollection+type is inferred as +StudyProtocol+
+      #   by stripping the +Collection+ suffix, capitalizing the prefix and looking for a class of
+      #   that name in the {Metadata#domain_module}.
+      # * If the declarer class metadata configuration includes a +domain_attributes+ property, then
+      #   the type specified in that property is returned.
+      # * Otherwise, this method returns Java::Javalang::Object.
+      #
+      # The optional restricted_type argument restricts the attribute to a subclass of the declared
+      # property type.
+      def initialize(pd, declarer, restricted_type=nil)
+        symbol = create_standard_attribute_symbol(pd, declarer)
+        super(symbol, declarer, restricted_type)
+        @property_descriptor = pd
+        # deficient Java introspector does not recognize 'is' prefix for a Boolean property
+        rm = declarer.property_read_method(pd)
+        raise ArgumentError.new("Property does not have a read method: #{declarer.qp}.#{pd.name}") unless rm
+        reader = rm.name.to_sym
+        unless declarer.method_defined?(reader) then
+          reader = "is#{reader.to_s.capitalize_first}".to_sym
+          unless declarer.method_defined?(reader) then
+            raise ArgumentError.new("Reader method not found for #{declarer} property #{pd.name}")
+          end
+        end
+        unless pd.write_method then
+          raise ArgumentError.new("Property does not have a write method: #{declarer.qp}.#{pd.name}")
+        end
+        writer = pd.write_method.name.to_sym
+        unless declarer.method_defined?(writer) then
+          raise ArgumentError.new("Writer method not found for #{declarer} property #{pd.name}")
+        end
+        @property_accessors = [reader, writer]
+        qualify(:collection) if collection_java_class?
+        @type = infer_type
+      end
+      
+      # @return [Symbol] the JRuby wrapper method for the Java property reader
+      def property_reader
+        property_accessors.first
+      end
+      
+      # @return [Symbol] the JRuby wrapper method for the Java property writer
+      def property_writer
+        property_accessors.last
+      end
+  
+      # Returns a lower-case, underscore symbol for the given property_name.
+      # A name ending in 'Collection' is changed to a pluralization.
+      #
+      # @example
+      #   JavaAttribute.to_attribute_symbol('specimenEventCollection') #=> :specimen_events
+      def self.to_attribute_symbol(property_name)
+        name = if property_name =~ /(.+)Collection$/ then
+          property_name[0...-'Collection'.length].pluralize.underscore
+        else
+          property_name.underscore
+        end
+        name.to_sym
+      end
+  
+      private
+  
+      # @param pd the Java property descriptor
+      # @param [Class] klass the declarer
+      # @return [String] the lower-case, underscore symbol for the given property descriptor
+      def create_standard_attribute_symbol(pd, klass)
+        propname = pd.name
+        name = propname.underscore
+        renamed = klass.unocclude_reserved_method(pd)
+        if renamed then
+          logger.debug { "Renamed #{klass.qp} reserved Ruby method #{name} to #{renamed}." }
+          renamed
+        else
+          JavaAttribute.to_attribute_symbol(propname)
+        end
+      end
+  
+      # @return [Boolean] whether this property's Java type is +Iterable+
+      def collection_java_class?
+        # the Java property type
+        ptype = @property_descriptor.property_type
+        # Test whether the corresponding JRuby wrapper class or module is an Iterable.
+        Class.to_ruby(ptype) < Java::JavaLang::Iterable
+      end
+  
+      # @return [Class] the type for the specified klass property descriptor pd as described in {#initialize}
+      def infer_type
+        collection? ? infer_collection_type : infer_non_collection_type
+      end
+  
+      # Returns the domain type for this attribute's Java Collection property descriptor.
+      # If the property type is parameterized by a single domain class, then that generic type argument is the domain type.
+      # Otherwise, the type is inferred from the property name as described in {#infer_collection_type_from_name}.
+      #
+      # @return [Class] this property's Ruby type
+      def infer_collection_type
+         generic_parameter_type or infer_collection_type_from_name or Java::JavaLang::Object
+      end
+  
+      # @return [Class] this property's Ruby type
+      def infer_non_collection_type
+        jtype = @property_descriptor.property_type
+        Class.to_ruby(jtype)
+      end
+  
+      # @return [Class, nil] the domain type of this attribute's property descriptor Collection generic
+      #   type argument, or nil if none
+      def generic_parameter_type
+        method = @property_descriptor.readMethod || return
+        gtype = method.genericReturnType
+        return unless Java::JavaLangReflect::ParameterizedType === gtype
+        atypes = gtype.actualTypeArguments
+        return unless atypes.size == 1
+        atype = atypes[0]
+        klass = java_to_ruby_class(atype)
+        logger.debug { "Inferred #{declarer.qp} #{self} domain type #{klass.qp} from generic parameter #{atype.name}." } if klass
+        klass
+      end
+  
+      # @param [Class, String] jtype the Java class or class name
+      # @return [Class] the corresponding Ruby type 
+      def java_to_ruby_class(jtype)
+        name = String === jtype ? jtype : jtype.name
+        Class.to_ruby(name)
+      end
+  
+      # Returns the domain type for this attribute's collection Java property descriptor name.
+      # By convention, caBIG domain collection properties often begin with a domain type
+      # name and end in 'Collection'. This method strips the Collection suffix and checks
+      # whether the prefix is a domain class.
+      #
+      # For example, the type of the property named +distributionProtocolCollection+
+      # is inferred as +DistributionProtocol+ by stripping the +Collection+ suffix,
+      # capitalizing the prefix and looking for a class of that name in this classifier's
+      # domain_module.
+      #
+      # @return [Class] the collection item type
+      def infer_collection_type_from_name
+        # the property name
+        pname = @property_descriptor.name
+        # The potential class name is the capitalized property name without a 'Collection' suffix.
+        cname = pname.capitalize_first.sub(/Collection$/, '')
+        jname = [@declarer.parent_module, cname].join('::')
+        klass = eval jname rescue nil
+        if klass then logger.debug { "Inferred #{declarer.qp} #{self} collection domain type #{klass.qp} from the attribute name." } end
+        klass
+      end
+    end
+  end
+end

data/lib/caruby/domain/merge.rb

@@ -20,13 +20,13 @@ module CaRuby
     #
     # 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
-    # {ResourceAttributes#mergeable_attributes}.
+    # {Attributes#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 {ResourceAttributes#nondomain_attributes})
+    # @param [<Symbol>, nil] attributes the attributes to merge (default {Attributes#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
@@ -76,7 +76,7 @@ module CaRuby
     # @return the merged attribute value
     def merge_attribute(attribute, newval, matches=nil)
       # the previous value
-      oldval = send(attribute)      
+      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
@@ -109,9 +109,13 @@ module CaRuby
     # @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
+      if attr_md.dependent? then
+        val = attr_md.collection? ? newval.first : newval
+        klass = val.class if val
+        inv_md = self.class.inverse_attribute_metadata(attr_md, klass)
+        if inv_md and not inv_md.collection? then
+          owtr = inv_md.writer
+        end
       end
 
       # If the attribute is a collection, then merge the matches into the current attribute
@@ -161,9 +165,8 @@ module CaRuby
         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
+        # The target is either a source match or the source itself.
+        ref = (matches[newval] if matches) || 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.
@@ -172,7 +175,7 @@ module CaRuby
       newval
     end
 
-    # Java alert - Java TreeSet comparison uses the TreeSet comparator rather than an
+    # 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)

data/lib/caruby/domain/metadata.rb

@@ -0,0 +1,141 @@
+require 'caruby/util/collection'
+require 'caruby/import/java'
+require 'caruby/domain/java_attribute'
+require 'caruby/domain/introspection'
+require 'caruby/domain/inverse'
+require 'caruby/domain/dependency'
+require 'caruby/domain/attributes'
+
+module CaRuby
+  module Domain
+    # Exception raised if a meta-data setting is missing or invalid.
+    class MetadataError < RuntimeError; end
+    
+    # Adds introspected metadata to a Class.
+    module Metadata
+      include Introspection, Inverse, Dependency, Attributes
+      
+      # @return [Module] the {Domain} module context
+      attr_accessor :domain_module
+      
+      def self.extended(klass)
+        super
+        klass.class_eval do
+          # Add this class's metadata.
+          introspect
+          # Add the {attribute=>value} argument constructor.
+          class << self
+            def new(opts=nil)
+              obj = super()
+              obj.merge_attributes(opts) if opts
+              obj
+            end
+          end
+        end
+      end
+  
+      # @return the domain type for attribute, or nil if attribute is not a domain attribute
+      def domain_type(attribute)
+        attr_md = attribute_metadata(attribute)
+        attr_md.type if attr_md.domain?
+      end
+  
+      # Returns an empty value for the given attribute.
+      # * If this class is not abstract, then the empty value is the initialized value.
+      # * Otherwise, if the attribute is a Java primitive number then zero.
+      # * Otherwise, if the attribute is a Java primitive boolean then +false+.
+      # * Otherwise, the empty value is nil.
+      #
+      # @param [Symbol] attribute the target attribute
+      # @return [Numeric, Boolean, Enumerable, nil] the empty attribute value
+      def empty_value(attribute)
+        if abstract? then
+          attr_md = attribute_metadata(attribute)
+          # the Java property type
+          jtype = attr_md.property_descriptor.property_type if JavaAttribute === attr_md
+          # A primitive is either a boolean or a number (String is not primitive).
+          if jtype and jtype.primitive? then
+            type.name == 'boolean' ? false : 0
+          end
+        else
+          # Since this class is not abstract, create a prototype instance on demand and make
+          # a copy of the initialized collection value from that instance.
+          @prototype ||= new
+          value = @prototype.send(attribute) || return
+          value.class.new
+        end
+      end
+      
+     # Prints this classifier's content to the log.
+      def pretty_print(q)
+        # the Java property descriptors
+        property_descriptors = java_attributes.wrap { |attr| attribute_metadata(attr).property_descriptor }
+        # build a map of relevant display label => attributes
+        prop_printer = property_descriptors.wrap { |pd| PROP_DESC_PRINTER.wrap(pd) }
+        prop_syms = property_descriptors.map { |pd| pd.name.to_sym }.to_set
+        aliases = @alias_std_attr_map.keys - attributes.to_a - prop_syms
+        alias_attr_hash = aliases.to_compact_hash { |aliaz| @alias_std_attr_map[aliaz] }
+        dependents_printer = dependent_attributes.wrap { |attr| DEPENDENT_ATTR_PRINTER.wrap(attribute_metadata(attr)) }
+        owner_printer = owners.wrap { |type| TYPE_PRINTER.wrap(type) }
+        inverses = @attributes.to_compact_hash do |attr|
+           attr_md = attribute_metadata(attr)
+           "#{attr_md.type.qp}.#{attr_md.inverse}" if attr_md.inverse
+        end
+        domain_attr_printer = domain_attributes.to_compact_hash { |attr| domain_type(attr).qp }
+        map = {
+          "Java properties" => prop_printer,
+          "standard attributes" => attributes,
+          "aliases to standard attributes" => alias_attr_hash,
+          "secondary key" => secondary_key_attributes,
+          "mandatory attributes" => mandatory_attributes,
+          "domain attributes" => domain_attr_printer,
+          "creatable domain attributes" => creatable_domain_attributes,
+          "updatable domain attributes" => updatable_domain_attributes,
+          "fetched domain attributes" => fetched_domain_attributes,
+          "cascaded domain attributes" => cascaded_attributes,
+          "owners" => owner_printer,
+          "owner attributes" => owner_attributes,
+          "inverse attributes" => inverses,
+          "dependent attributes" => dependents_printer,
+          "default values" => defaults
+        }.delete_if { |key, value| value.nil_or_empty? }
+        
+        # one indented line per entry, all but the last line ending in a comma
+        content = map.map { |label, value| "  #{label}=>#{format_print_value(value)}" }.join(",\n")
+        # print the content to the log
+        q.text("#{qp} structure:\n#{content}")
+      end
+  
+      protected
+  
+      def self.extend_class(klass, mod)
+        klass.extend(self)
+        klass.add_metadata(mod)
+      end
+  
+      private
+      
+      # A proc to print the unqualified class name.
+      TYPE_PRINTER = PrintWrapper.new { |type| type.qp }
+  
+      DEPENDENT_ATTR_PRINTER = PrintWrapper.new do |attr_md|
+        flags = []
+        flags << :logical if attr_md.logical?
+        flags << :autogenerated if attr_md.autogenerated?
+        flags << :disjoint if attr_md.disjoint?
+        flags.empty? ? "#{attr_md}" : "#{attr_md}(#{flags.join(',')})"
+      end
+  
+      # A proc to print the property descriptor name.
+      PROP_DESC_PRINTER = PrintWrapper.new { |pd| pd.name }
+
+      def format_print_value(value)
+        case value
+          when String then value
+          when Class then value.qp
+          else value.pp_s(:single_line)
+        end
+      end
+    end
+  end
+end

data/lib/caruby/domain/mixin.rb

@@ -0,0 +1,35 @@
+require 'caruby/domain/metadata'
+
+module CaRuby
+  module Domain
+    # Mixin extends a module to add meta-data to included classes.
+    module Mixin
+      # Adds {Metadata} to an included class.
+      #
+      # @example
+      #   module CaRuby
+      #     module Resource
+      #       def self.included(mod)
+      #         mod.extend(Domain::Mixin)
+      #       end
+      #     end
+      #   end
+      #   module ClinicalTrials
+      #     module Resource
+      #       include CaRuby::Resource
+      #     end
+      #     class Subject
+      #       include Resource #=> introspects the Subject meta-data
+      #     end
+      #   end
+      #
+      # @param [Module] class_or_module the included module, usually a class
+      def included(class_or_module)
+        super
+        if Class === class_or_module then
+          Metadata.ensure_metadata_introspected(class_or_module)
+        end
+      end
+    end
+  end
+end

data/lib/caruby/domain/reference_visitor.rb

@@ -21,7 +21,7 @@ module CaRuby
     # Creates a new ReferenceVisitor on domain reference attributes.
     #
     # If a selector block is given to this initializer, then the reference attributes to visit
-    # are determined by calling the block. Otherwise, the {ResourceAttributes#saved_domain_attributes}
+    # are determined by calling the block. Otherwise, the {Attributes#saved_domain_attributes}
     # are visited.
     #
     # @param options (see Visitor#initialize)
@@ -345,6 +345,8 @@ module CaRuby
     # @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
       attrs = @mergeable.call(source)
       logger.debug { format_merge_log_message(source, target, attrs) }
@@ -391,9 +393,9 @@ module CaRuby
     # @param (see MergeVisitor#visit)
     # @yield (see MergeVisitor#visit)
     # @yieldparam (see MergeVisitor#visit)
-    def visit(source, &block)
+    def visit(source)
       target = @copier.call(source)
-      super(source, target, &block)
+      super(source, target)
     end
   end