caruby-core 1.4.2 → 1.4.3

data/lib/caruby/database/saved_matcher.rb

@@ -0,0 +1,56 @@
+require 'caruby/database/fetched_matcher'
+
+module CaRuby
+  class Database
+    # Proc that matches saved result sources to targets.
+    class SavedMatcher < FetchedMatcher
+      # Initializes a new SavedMatcher.
+      def initialize
+        super
+      end
+      
+      private
+
+      # Returns a target => source match hash for the given targets and sources.
+      #
+      # @param (see FetchedMatcher#initialize)
+      # @return (see FetchedMatcher#initialize)
+      def match_fetched(sources, targets)
+        # match source => target based on the key
+        matches = super
+        # match residual targets, if any, on a relaxed criterion
+        if matches.size != targets.size and not sources.empty? then
+          match_fetched_residual(sources, targets, matches)
+        end
+        matches
+      end
+
+      # Adds to the given target => source matches hash for the unmatched targets and sources
+      # using {#match_minimal}.
+      #
+      # @param sources (see #match_fetched)
+      # @param targets (see #match_fetched)
+      # @param [{Resource => Resource}] the source => target matches so far
+      def match_fetched_residual(sources, targets, matches)
+        unmtchd_tgts = targets.to_set - matches.keys.delete_if { |tgt| tgt.identifier }
+        unmtchd_srcs = sources.to_set - matches.values
+        min_mtchs = match_minimal(unmtchd_srcs, unmtchd_tgts)
+        matches.merge!(min_mtchs)
+      end
+      
+      #@param [<Resource>] sources the source objects to match
+      #@param [<Resource>] targets the potential match target objects
+      # @return (see #match_saved)
+      def match_minimal(sources, targets)
+        matches = {}
+        unmatched = Set === sources ? sources.to_set : sources.dup
+        targets.each do |tgt|
+          src = unmatched.detect { |src| tgt.minimal_match?(src) } || next
+          matches[src] = tgt
+          unmatched.delete(src)
+        end
+        matches
+      end
+    end
+  end
+end

data/lib/caruby/database/search_template_builder.rb

@@ -31,7 +31,7 @@ module CaRuby
       # the searchable attribute => value hash
       ref_hash, nonref_hash = hash.hash_partition { |attr, value| Resource === value }
       # make the search template from the non-reference attributes
-      tmpl = obj.class.new(nonref_hash)
+      tmpl = obj.class.new.merge_attributes(nonref_hash)
       # get references for the search template
       unless ref_hash.empty? then
         logger.debug { "Collecting search reference parameters for #{obj.qp} from attributes #{ref_hash.keys.to_series}..." }

data/lib/caruby/database/sql_executor.rb

@@ -42,7 +42,8 @@ module CaRuby
     end
 
     # Connects to the database, yields the DBI handle to the given block and disconnects.
-    # Returns the execution result.
+    #
+    # @return [Array] the execution result
     def execute
       logger.debug { "Connecting to database with user #{@username}, address #{@address}..." }
       result = DBI.connect(@address, @username, @password, "driver"=>"com.mysql.jdbc.Driver") { |dbh| yield dbh }
@@ -54,17 +55,17 @@ module CaRuby
 
     def default_driver_string(db_type)
       case db_type.downcase
-      when 'mysql' then 'jdbc:mysql'
-      when 'oracle' then 'Oracle'
-      else raise CaRuby::ConfigurationError.new("Default database connection driver string could not be determined for database type #{db_type}")
+        when 'mysql' then 'jdbc:mysql'
+        when 'oracle' then 'Oracle'
+        else raise CaRuby::ConfigurationError.new("Default database connection driver string could not be determined for database type #{db_type}")
       end
     end
 
     def default_port(db_type)
       case db_type.downcase
-      when 'mysql' then 3306
-      when 'oracle' then 1521
-      else raise CaRuby::ConfigurationError.new("Default database connection port could not be determined for database type #{db_type}")
+        when 'mysql' then 3306
+        when 'oracle' then 1521
+        else raise CaRuby::ConfigurationError.new("Default database connection port could not be determined for database type #{db_type}")
       end
     end
 

data/lib/caruby/database/store_template_builder.rb

@@ -3,17 +3,29 @@ require 'caruby/domain/reference_visitor'
 module CaRuby
   # StoreTemplateBuilder creates a template suitable for a create or update database operation.
   class StoreTemplateBuilder
-    # Creates a new StoreTemplateBuilder for the given database.
+    # Creates a new StoreTemplateBuilder for the given database. The attributes to merge into
+    # the template are determined by the block given to this initializer, filtered as follows:
+    # * If the save operation is a create, then exclude the auto-generated attributes.
+    # * If the visited object has an identifier, then include only those attributes
+    #   which {AttributeMetadata#cascade_update_to_create?} or have an identifier. 
     #
     # @param [Database] database the target database 
-    # @yield [ref] the required selector block which determines the attributes copied into the template
+    # @yield [ref] the required selector block which determines which attributes are copied into the template
     # @yieldparam [Resource] ref the domain object to copy
     def initialize(database)
       @database = database
-      unless block_given? then raise ArgumentError.new("StoreTemplateBuilder is missing the required template copy attribute selector block") end
-      # the domain attributes to copy
-      mgbl = Proc.new { |src, tgt| yield src }
-      # copy the reference
+      unless block_given? then
+        raise ArgumentError.new("StoreTemplateBuilder is missing the required template copy attribute selector block")
+      end
+      
+      # the mergeable attributes filter the given block with exclusions
+      @mergeable = Proc.new { |obj| mergeable_attributes(obj, yield(obj)) }
+      # the storable prerequisite reference visitor
+      @prereq_vstr = ReferenceVisitor.new(:prune_cycle) { |ref| savable_cascaded_attributes(ref) }
+      
+      # the savable attributes filter the given block with exclusions
+      savable = Proc.new { |obj| savable_attributes(obj, yield(obj)) }
+      # the domain attributes to copy is determined by the constructor caller
       # caTissue alert - must copy all of the non-domain attributes rather than just the identifier,
       # since caTissue auto-generated Specimen update requires the parent collection status. This
       # is the only known occurrence of a referenced object required non-identifier attribute.
@@ -24,10 +36,8 @@ module CaRuby
         copy_proxied_save_references(src, copy)
         copy
       end
-     # the template copier
-      @copy_vstr = CopyVisitor.new(:mergeable => mgbl, :copier => copier) { |src, tgt| savable_cascaded_attributes(src) }
-      # the storable prerequisite reference visitor
-      @prereq_vstr = ReferenceVisitor.new(:prune_cycle) { |ref| savable_cascaded_attributes(ref) }
+      # the template copier
+      @copy_vstr = CopyVisitor.new(:mergeable => savable, :copier => copier) { |ref| savable_cascaded_attributes(ref) }
     end
 
     # Returns a new domain object which serves as the argument for obj create or update.
@@ -40,16 +50,14 @@ module CaRuby
     # caCORE alert - +caCORE+ expects the store argument to be carefully prepared prior to
     # the create or update. build_storable_template culls the target object with a template
     # which includes only those references which are necessary for the store to succeed.
-    # This method ensures that mandatory independent references exist. Dependent references
-    # are included in the template but are not created before submission to +caCORE+ create
-    # or update. These fine distinctions are implicit application rules which are explicated
-    # in the +caRuby+ application domain class definition using ResourceMetadata methods.
-    #
-    # caCORE alert - +caCORE+ occasionally induces a stack overflow if a create argument
-    # contains a reference cycle. The template fixes this.
+    # This template builder ensures that mandatory independent references exist. Cascaded
+    # dependent references are included in the template but are not created before submission
+    # to +caCORE+. These reference attribute distinctions are implicit application rules which
+    # are explicated in the +caRuby+ application domain class definition using ResourceMetadata
+    # methods.
     #
-    # caCORE alert - +caCORE+ create raises an error if a create argument directly or
-    # indirectly references a domain objects without an identifier, even if the
+    # caCORE alert - +caCORE+ create issues an error if a create argument directly or
+    # indirectly references a non-cascaded domain object without an identifier, even if the
     # reference is not relevant to the create. The template returned by this method elides
     # all non-essential references.
     #
@@ -67,7 +75,9 @@ module CaRuby
     #
     # @param [Resource] obj the domain object to save
     # @return [Resource] the template to use as the caCORE argument
-    def build_template(obj)
+    def build_template(obj, autogenerated=false)
+      # set the database operation subject
+      @subject = obj
       # prepare the object for a store operation
       ensure_storable(obj)
       # copy the cascade hierarchy
@@ -87,7 +97,8 @@ module CaRuby
     #   java.lang.IllegalArgumentException: id to load is required for loading
     # The server log stack trace indicates a bizlogic line that offers a clue to the offending reference.
     def ensure_storable(obj)
-      # Add defaults, which might introduce independent references.
+      # Add defaults, which might introduce independent references. Enable the lazy loader to fetch
+      # create references from the database where needed to build defaults.
       obj.add_defaults
       # create the prerequisite references if necessary
       prereqs = collect_prerequisites(obj)
@@ -96,42 +107,83 @@ module CaRuby
         @database.ensure_exists(prereqs)
         logger.debug { "Prerequisite references for #{obj.qp} exist: #{prereqs.map { |ref| ref }.to_series}." }
       end
-      # If obj is being created then add defaults again, since fetched independent references might introduce new defaults.
-      obj.add_defaults unless obj.identifier
       # Verify that the object is complete
       obj.validate
     end
-      
-    # Filters the {ResourceAttributes#updatable_domain_attributes} to exclude
-    # the {ResourceAttributes#proxied_cascaded_attributes} whose reference value
-    # does not have an identifier. These references will be created by proxy
-    # instead.
+    
+    # Returns the attributes to visit in building the template for the given
+    # domain object. The visitable attributes consist of the following:
+    # * The {ResourceAttributes#unproxied_cascaded_attributes} filtered as follows:
+    #   * If the database operation is a create, then exclude the cascaded attributes.
+    #   * If the given object has an identifier, then exclude the attributes which
+    #     have the the :no_cascade_update_to_create flag set.
+    # * The {ResourceAttributes#proxied_cascaded_attributes} are included if and
+    #   only if every referenced object has an identifier, and therefore does not
+    #   need to be proxied.
+    #
+    # caTissue alert - caTissue ignores some references, e.g. Participant CPR, and auto-generates
+    # the values instead. Therefore, the create template builder excludes these auto-generated
+    # attributes. After the create, the auto-generated references are merged into the created
+    # object graph and the references are updated if necessary.
     #
     # @param [Resource] obj the domain object copied to the update template
     # @return [<Symbol>] the reference attributes to include in the update template
     def savable_cascaded_attributes(obj)
-      # always include the unproxied cascaded references
-      unproxied = obj.class.unproxied_cascaded_attributes
-      if obj.identifier then
-        unproxied = unproxied.filter do |attr|
-          obj.class.attribute_metadata(attr).cascade_update_to_create? or
-          obj.send(attr).to_enum.all? { |ref| ref.identifier }
-        end
+      # The starting set of candidate attributes is the unproxied cascaded references.
+      unproxied = savable_attributes(obj, obj.class.unproxied_cascaded_attributes)
+      # The proxied attributes to save.
+      proxied = savable_proxied_attributes(obj)
+      # The combined set of savable attributes
+      proxied.empty? ? unproxied : unproxied + proxied
+    end
+    
+    # Composes the given attributes, if necessary, to exclude attributes as follows:
+    # * If the save operation is a create, then exclude the auto-generated attributes.
+    #
+    # @param [Resource] obj the visited domain object
+    # @param [ResourceAttributes::Filter] the savable attribute filter
+    # @return [ResourceAttributes::Filter] the composed attribute filter
+    def mergeable_attributes(obj, attributes)
+      # If this is an update, then there is no filter on the given attributes.
+      return attributes if @subject.identifier
+      # This is a create: ignore the optional auto-generated attributes.
+      mas = obj.mandatory_attributes.to_set
+      attributes.compose { |attr_md| mas.include?(attr_md.to_sym) or not attr_md.autogenerated? }
+    end
+    
+    # Composes the given attributes, if necessary, to exclude attributes as follows:
+    # * If the save operation is a create, then exclude the auto-generated attributes.
+    # * If the visited object has an identifier, then include only those attributes
+    #   which {AttributeMetadata#cascade_update_to_create?} or have an identifier. 
+    #
+    # @param (see #mergeable_attributes)
+    # @return (see #mergeable_attributes)
+    def savable_attributes(obj, attributes)
+      mgbl = mergeable_attributes(obj, attributes)
+      return mgbl if obj.identifier.nil?
+      # The currently visited object is an update: include attributes which
+      # either cascade update to create or have saved references.
+      mgbl.compose do |attr_md|
+        attr_md.cascade_update_to_create? or Persistable.saved?(obj.send(attr_md.to_sym))
       end
-      
+    end
+   
+    # Returns the proxied attributes to save. A proxied attribute is included only if the proxied
+    # dependents have an identifier, since those without an identifer are created separately via
+    # the proxy.
+    #
+    # @param [Resource] obj the visited domain object
+    # @return [<Attribute>] the proxied cascaded attributes with an unsaved reference
+    def savable_proxied_attributes(obj)
       # Include a proxied reference only if the proxied dependents have an identifier,
       # since those without an identifer are created separately via the proxy.
-      proxied = obj.class.proxied_cascaded_attributes.reject do |attr|
+      obj.class.proxied_cascaded_attributes.reject do |attr|
         ref = obj.send(attr)
         case ref
-        when Enumerable then
-           ref.any? { |dep| not dep.identifier }
-        when Resource then
-          not ref.identifier
+          when Enumerable then ref.any? { |dep| not dep.identifier }
+          when Resource then not ref.identifier
         end
       end
-      
-      proxied.empty? ? unproxied : unproxied + proxied
     end
     
     # Copies proxied references as needed.
@@ -148,17 +200,21 @@ module CaRuby
     def copy_proxied_save_references(obj, template)
       return unless obj.identifier
       obj.class.proxied_cascaded_attributes.each do |attr|
+        # the proxy source
         ref = obj.send(attr)
         case ref
-        when Enumerable then
-          coll = template.send(attr)
-          ref.each do |dep|
-            copy = copy_proxied_save_reference(obj, attr, template, dep)
-            coll << copy if copy
-          end
-        when Resource then
-          copy = copy_proxied_save_reference(obj, attr, template, ref)
-          template.set_attribute(attr, copy) if copy
+          when Enumerable then
+            # recurse on the source collection
+            coll = template.send(attr)
+            ref.each do |dep|
+              copy = copy_proxied_save_reference(obj, attr, template, dep)
+              coll << copy if copy
+            end
+          when Resource then
+            # copy the source
+            copy = copy_proxied_save_reference(obj, attr, template, ref)
+            # set the attribute to the copy
+            template.set_attribute(attr, copy) if copy
         end
       end
     end
@@ -174,27 +230,44 @@ module CaRuby
       # map references to either the copied owner or a new copy of the reference
       tvh = vh.transform { |value| Resource === value ? (value == obj ? template : value.copy) : value }
       # the copy with the adjusted values
-      copy = proxied.class.new(tvh)
+      copy = proxied.class.new.merge_attributes(tvh)
       logger.debug { "Created #{obj.qp} proxied #{attribute} save template copy #{proxied.pp_s}." }
       copy
     end
     
-    # Returns the references which must be created in order to store obj.
+    # @param [Resource] obj the domain object to store
+    # @return [<Resource>] the references which must be created in order to store the object
     def collect_prerequisites(obj)
       prereqs = Set.new
+      # visit the cascaded attributes 
       @prereq_vstr.visit(obj) do |stbl|
-        stbl.class.storable_prerequisite_attributes.each do |attr|
+        # Check each mergeable attribute for prerequisites. The mergeable attributes includes
+        # both cascaded and independent attributes. The selection block filters for independent
+        # domain objects which don't have an identifier.
+        @mergeable.call(stbl).each_pair do |attr, attr_md|
+          # Cascaded attributes are not prerequisite, since they are created when the owner is created.
+          # Note that each non-prerequisite cascaded reference is still visited in order to ensure
+          # that each independent object referenced by a cascaded reference is recognized as a
+          # candidate prerequisite.
+          next if attr_md.cascaded?
           # add qualified prerequisite attribute references
-          stbl.send(attr).enumerate do |prereq|
-            # add the prerequisite unless it is the object being created, was already created or is
-            # in the owner hierarchy 
-            unless prereq == obj or prereq.identifier or prereq.owner_ancestor?(obj) then
-              prereqs << prereq
-            end
+          stbl.send(attr).enumerate do |ref|
+            # Add the prerequisite if it satisfies the prerequisite? condition.
+            prereqs << ref if prerequisite?(ref, obj)
           end
         end
       end
       prereqs
     end
+    
+    # A referenced object is a target object save prerequisite if is the target object, was already created
+    # or is in an immediate or recursive dependent of the target object.
+    #
+    # @param [Resource] ref the reference to check
+    # @param [Resource] obj the object being stored
+    # @return [Boolean] whether the reference should exist before storing the object
+    def prerequisite?(ref, obj)
+      not (ref == obj or ref.identifier or ref.owner_ancestor?(obj))
+    end
   end
 end

data/lib/caruby/database/writer.rb

@@ -1,7 +1,7 @@
 require 'caruby/util/collection'
 require 'caruby/util/pretty_print'
 require 'caruby/domain/reference_visitor'
-require 'caruby/database/saved_merger'
+require 'caruby/database/saved_matcher'
 require 'caruby/database/store_template_builder'
 
 module CaRuby
@@ -11,9 +11,17 @@ module CaRuby
       # Adds store capability to this Database.
       def initialize
         super
-        @cr_tmpl_bldr = StoreTemplateBuilder.new(self) { |ref| ref.class.creatable_domain_attributes }
+        @ftchd_vstr = ReferenceVisitor.new { |tgt| tgt.class.fetched_domain_attributes }
+        @cr_tmpl_bldr = StoreTemplateBuilder.new(self) { |ref| creatable_domain_attributes(ref) }
         @upd_tmpl_bldr = StoreTemplateBuilder.new(self) { |ref| updatable_domain_attributes(ref) }
-        @svd_mrgr = SavedMerger.new(self)
+        # the save result => argument reference matcher
+        svd_mtchr = SavedMatcher.new
+        # the save (result, argument) synchronization visitor
+        @svd_sync_vstr = MatchVisitor.new(:matcher => svd_mtchr) { |ref| ref.class.dependent_attributes }
+        # the attributes to merge from the save result
+        mgbl = Proc.new { |ref| ref.class.domain_attributes } 
+        # the save result => argument merge visitor
+        @svd_mrg_vstr = MergeVisitor.new(:matcher => svd_mtchr, :mergeable => mgbl) { |ref| ref.class.dependent_attributes }
       end
 
       # Creates the specified domain object obj and returns obj. The pre-condition for this method is as
@@ -106,8 +114,6 @@ module CaRuby
       # @raise [DatabaseError] if the database operation fails
       def save(obj)
         logger.debug { "Storing #{obj}..." }
-        # add defaults now, since a default key value could be used in the existence check
-        obj.add_defaults
         # if obj exists then update it, otherwise create it
         exists?(obj) ? update(obj) : create(obj)
       end
@@ -134,7 +140,7 @@ module CaRuby
         raise ArgumentError.new("Database ensure_exists is missing a domain object argument") if obj.nil_or_empty?
         obj.enumerate { |ref| find(ref, :create) unless ref.identifier }
       end
-
+      
       # Returns whether there is already the given obj operation in progress that is not in the scope of
       # an operation performed on a dependent obj owner, i.e. a second obj save operation of the same type
       # is only allowed if the obj operation was delegated to an owner save which in turn saves the dependent
@@ -144,8 +150,8 @@ module CaRuby
       # @param [Symbol] operation the +:create+ or +:update+ save operation
       # @return [Boolean] whether the save operation is redundant
       def recursive_save?(obj, operation)
-        @operations.detect { |op| op.type == operation and op.subject == obj } and
-        @operations.last.subject != obj.owner
+        @operations.any? { |op| op.type == operation and op.subject == obj } and
+          not obj.owner_ancestor?(@operations.last.subject)
       end
 
       private
@@ -167,8 +173,8 @@ module CaRuby
           # A dependent of an uncreated owner can be created by creating the owner.
           # Otherwise, create obj from a template.
           create_as_dependent(obj) or
-          create_from_template(obj) or
-          raise DatabaseError.new("#{obj.class.qp} is not creatable in context #{print_operations}")
+            create_from_template(obj) or
+            raise DatabaseError.new("#{obj.class.qp} is not creatable in context #{print_operations}")
         ensure
           # since obj now has an id, removed from transients set
           @transients.delete(obj)
@@ -188,17 +194,16 @@ module CaRuby
       # @return [Resource] dep
       def create_as_dependent(dep)
         # bail if not dependent or owner is not set
-        owner = dep.owner || return
-        unless owner.identifier then
-          logger.debug { "Adding #{owner.qp} dependent #{dep.qp} defaults..." }
-          dep.add_defaults
-          logger.debug { "Ensuring that dependent #{dep.qp} owner #{owner.qp} exists..." }
-          ensure_exists(owner)
+        ownr = dep.owner || return
+        unless ownr.identifier then
+          logger.debug { "Adding #{ownr.qp} dependent #{dep.qp} defaults..." }
+          logger.debug { "Ensuring that dependent #{dep.qp} owner #{ownr.qp} exists..." }
+          ensure_exists(ownr)
         end
 
         # If the dependent was created as a side-effect of creating the owner, then we are done.
         if dep.identifier then
-          logger.debug { "Created dependent #{dep.qp} by saving owner #{owner.qp}." }
+          logger.debug { "Created dependent #{dep.qp} by saving owner #{ownr.qp}." }
           return dep
         end
 
@@ -274,10 +279,9 @@ module CaRuby
         # The create template. Independent saved references are created as necessary.
         tmpl = build_create_template(obj)        
         save_with_template(obj, tmpl) { |svc| svc.create(tmpl) }
-        
         # If obj is a top-level create, then ensure that remaining references exist.
         if @operations.first.subject == obj then
-          refs = obj.suspend_lazy_loader { obj.references.reject { |ref| ref.identifier } }
+          refs = obj.references.reject { |ref| ref.identifier }
           logger.debug { "Ensuring that created #{obj.qp} references exist: #{refs.qp}..." } unless refs.empty?
           refs.each { |ref| ensure_exists(ref) }
         end
@@ -285,8 +289,10 @@ module CaRuby
         obj
       end
       
+      # @param (see #create)
+      # @return (see #build_save_template)
       def build_create_template(obj)
-        @cr_tmpl_bldr.build_template(obj)
+        build_save_template(obj, @cr_tmpl_bldr)
       end
 #
       # caCORE alert - application create logic might ignore a non-domain attribute value,
@@ -313,19 +319,64 @@ module CaRuby
         end
       end
       
-      # Returns the {MetadataAttributes#updatable_domain_attributes} which are either
-      # {AttributeMetadata#cascade_update_to_create?} or have identifiers for all
-      # references in the attribute value.
+      # Returns the {MetadataAttributes#creatable_domain_attributes} which are not contravened by a
+      # one-to-one independent pending create.
+      # 
+      # @param (see #create)
+      # @return [<Symbol>] the attributes to include in the create template
+      def creatable_domain_attributes(obj)
+        # filter the creatable attributes
+        obj.class.creatable_domain_attributes.compose do |attr_md|
+          if exclude_pending_create_attribute?(obj, attr_md) then
+            # Avoid printing duplicate log message.
+            if obj != @cr_dom_attr_log_obj then
+              logger.debug { "Excluded #{obj.qp} #{attr_md} in the create template since it references a 1:1 bidirectional independent pending create." }
+              @cr_dom_attr_log_obj = obj
+            end
+            false
+          else
+            true
+          end
+        end
+      end
+      
+      # Returns whether the given creatable domain attribute with value obj is a 
+      # {AttributeMetadata#one_to_one_bidirectional_independent?}
+      # unsaved optional attribute without an obj {#pending_create?} save context.
+      #
+      # @param obj (see #create)
+      # @param [AttributeMetadata] attr_md candidate attribute metadata
+      # @return [Boolean] whether the attribute should not be included in the create template
+      def exclude_pending_create_attribute?(obj, attr_md)
+        attr_md.one_to_one_bidirectional_independent? and
+          obj.identifier.nil? and
+          not obj.mandatory_attributes.include?(attr_md.to_sym) and
+          ref = obj.send(attr_md.to_sym) and
+          ref.identifier.nil? and
+          pending_create?(ref)
+      end
+      
+      # @param [Resource] obj the object to check
+      # @return [Boolean] whether the penultimate create operation is on the object
+      def pending_create?(obj)
+        op = penultimate_create_operation
+        op and op.subject == obj
+      end
+      
+      # @return [Operation] the create operation which scopes the innermost create operation
+      def penultimate_create_operation
+        @operations.reverse_each { |op| return op if op.type == :create and op != @operations.last }
+        nil
+      end
+      
+      # Returns the {MetadataAttributes#updatable_domain_attributes}.
       # 
       # @param (see #update)
       # @return the attributes to include in the update template
       def updatable_domain_attributes(obj)
-        obj.class.updatable_domain_attributes.filter do |attr|
-          obj.class.attribute_metadata(attr).cascade_update_to_create? or
-          obj.send(attr).to_enum.all? { |ref| ref.identifier }
-        end
+        obj.class.updatable_domain_attributes
       end
-
+      
       # @param (see #update)
       def update_object(obj)
         # database identifier is required for update
@@ -389,8 +440,16 @@ module CaRuby
       end
       
       # @param (see #update)
+      # @return (see #build_save_template)
       def build_update_template(obj)
-        @upd_tmpl_bldr.build_template(obj)
+        build_save_template(obj, @upd_tmpl_bldr)
+      end
+      
+      # @param obj (see #save)
+      # @param [StoreTemplateBuilder] builder the builder to use
+      # @return [Resource] the template to use as the save argument
+      def build_save_template(obj, builder)
+        builder.build_template(obj)
       end
 
       # @param (see #delete)
@@ -421,49 +480,190 @@ module CaRuby
         sync_saved(obj, result)
       end
       
-      def sync_saved(obj, result)
-        # delegate to the merge visitor
-        src = @svd_mrgr.merge(obj, result)
-        # make the saved object persistent, if not already so
-        persistify(obj)
+      # Synchronizes the content of the given saved domain object and the save result source as follows:
+      # 1. The save result source is first synchronized with the database content as necessary.
+      # 2. Then the source is merged into the target.
+      # 3. If the target must be resaved based on the call to {#update_saved?}, then the source
+      #    result is resaved.
+      # 4. Each target dependent which differs from the corresponding source dependent is saved.
+      #
+      # @param [Resource] target the saved domain object
+      # @param [Resource] source the caCORE save result
+      def sync_saved(target, source)
+        # clear the toxic source attributes
+        detoxify(source)
+        # sync the save result source with the database
+        sync_saved_result_with_database(source, target)
+        # merge the source into the target
+        merge_saved(target, source)
 
         # If saved must be updated, then update recursively.
         # Otherwise, save dependents as needed.
-        if update_saved?(obj, src) then
-          logger.debug { "Updating saved #{obj} to store unsaved attributes..." }
-          # call update_savedect(saved) rather than update(saved) to bypass the redundant update check
-          perform(:update, obj) { update_object(obj) }
+        if update_saved?(target, source) then
+          logger.debug { "Updating saved #{target} to store unsaved attributes..." }
+          # call update_object(saved) rather than update(saved) to bypass the redundant update check
+          perform(:update, target) { update_object(target) }
         else
           # recursively save the dependents
-          save_dependents(obj)
+          save_changed_dependents(target)
         end
       end
-
+      
+      # Synchronizes the given saved target result source with the database content.
+      # The source is synchronized by {#sync_save_result}.
+      #
+      # @param (see #sync_saved)
+      def sync_saved_result_with_database(source, target)
+        @svd_sync_vstr.visit(source, target) { |src, tgt| sync_save_result(src, tgt) }
+      end
+      
+      # Merges the database content into the given saved domain object.
+      # Dependents are merged recursively.
+      #
+      # caTissue alert - the auto-generated references are not necessarily valid, e.g. the auto-generated
+      # SpecimenRequirement characteristics tissue site is nil rather than the default 'Not Specified'.
+      # This results in an obscure downstream error when creating an CPR which auto-generates a SCG
+      # which auto-generates a Specimen which copies the invalid characteristics. The work-around for
+      # this bug is to add defaults to auto-generated references. Then, if the content differs from
+      # the database, the difference induces an update of the reference.
+      #
+      # @param (see #sync_saved)
+      # @return [Resource] the merged target object
+      def merge_saved(target, source)
+        logger.debug { "Merging saved result #{source} into saved #{target.qp}..." }
+        # Update each saved reference snapshot to reflect the database state and add a lazy loader if necessary.
+        @svd_mrg_vstr.visit(source, target) do |src, tgt|
+          # capture the id
+          prev_id = tgt.identifier
+          persistify_object(tgt, src)
+          # if tgt is an auto-generated reference, then add defaults
+          if target != tgt and prev_id.nil? then tgt.add_defaults end
+        end
+        logger.debug { "Merged saved result #{source} into saved #{target.qp}." }
+      end
+      
+      # Synchronizes the given save result source object to reflect the database content, as follows:
+      # * If the save result has autogenerated non-domain attributes, then the source is refetched.
+      # * Each of the dependent {#synchronization_attributes} is fetched.
+      # * Inverses are set consistently within the save result object graph.
+      #
+      # @param (see #sync_saved)
+      def sync_save_result(source, target)
+        logger.debug { "Synchronizing #{target} save result #{source} with the database..." }
+        # If the target was created, then refetch and merge the source if necessary to reflect auto-generated
+        # non-domain attribute values.
+       if target.identifier.nil? then sync_created_result_object(source) end
+        # If there are auto-generated attributes, then merge them into the save result.
+        sync_save_result_references(source, target)
+        # Set inverses consistently in the source object graph
+        set_inverses(source)
+        logger.debug { "Synchronized #{target} save result #{source} with the database." }
+      end
+      
+      # Refetches the given create result source if there are any {ResourceAttributes#autogenerated_nondomain_attributes}
+      # which must be fetched to reflect the database state.
+      #
+      # @param source (see #sync_saved)
+      def sync_created_result_object(source)
+        attrs = source.class.autogenerated_nondomain_attributes
+        return if attrs.empty?
+        logger.debug { "Refetch #{source} to reflect auto-generated database content for attributes #{attrs.to_series}..." }
+        find(source)
+      end
+      
+      # Fetches the {#synchronization_attributes} into the given target save result source.
+      #
+      # @param (see #sync_saved)
+      def sync_save_result_references(source, target)
+        attrs = synchronization_attributes(source, target)
+        return if attrs.empty?
+        logger.debug { "Fetching the saved #{target.qp} attributes #{attrs.to_series} into save result #{source.qp}..." }
+        attrs.each { |attr| sync_save_result_attribute(source, attr) }
+        logger.debug { "Fetched the saved #{target.qp} attributes #{attrs.to_series} into the save result #{source.qp}." }
+      end
+      
+      # @see #sync_save_result_references
+      def sync_save_result_attribute(source, attribute)
+        # fetch the value
+        fetched = fetch_association(source, attribute)
+        # set the attribute
+        source.set_attribute(attribute, fetched)
+      end
+      
+      # Returns the saved target attributes which must be fetched to reflect the database content, consisting
+      # of the following:
+      # * {Persistable#saved_fetch_attributes}
+      # * {ResourceAttributes#domain_attributes} which include a source reference without an identifier
+      #
+      # @param (see #sync_saved)
+      # @return [<Symbol>] the attributes which must be fetched
+      def synchronization_attributes(source, target)
+        # the target save operation
+        op = @operations.last
+        # the attributes to fetch
+        attrs = target.saved_fetch_attributes(op).to_set
+        # the pending create, if any
+        pndg_op = penultimate_create_operation
+        pndg = pndg_op.subject if pndg_op
+        # add in the domain attributes whose identifier was not set in the result
+        source.class.saved_domain_attributes.select do |attr|
+          srcval = source.send(attr)
+          tgtval = target.send(attr)
+          if Persistable.unsaved?(srcval) then
+            logger.debug { "Fetching save result #{source.qp} #{attr} since a referenced object identifier was not set in the result..." }
+            attrs << attr
+          elsif srcval.nil_or_empty? and Persistable.unsaved?(tgtval) and tgtval != pndg then
+            logger.debug { "Fetching save result #{source.qp} #{attr} since the target #{target.qp} value #{tgtval.qp} is missing an identifier..." }
+            attrs << attr
+          end
+        end
+        attrs
+      end
+      
       # Saves the given domain object dependents.
       #
       # @param [Resource] obj the owner domain object
-      def save_dependents(obj)
-        obj.dependents.each { |dep| save_dependent(obj, dep) }
+      def save_changed_dependents(obj)
+        # JRuby alert - copy the Resource dependents call result to an array, since iteration based on
+        # Forwardable enum_for breaks here with an obscure Java ConcurrentModificationException
+        # in the CaTissue SCG save test case. TODO - isolate and fix at source.
+        obj.class.dependent_attributes.each do |attr|
+          deps = obj.send(attr).to_enum
+          logger.debug { "Saving the #{obj} #{attr} dependents #{deps.qp} which have changed..." } unless deps.empty?
+          deps.each { |dep| save_dependent_if_changed(obj, attr, dep) }
+        end
       end
       
       # Saves the given dependent domain object if necessary.
       # Recursively saves the obj dependents as necessary.
       #
       # @param [Resource] obj the dependent domain object to save
-      def save_dependent(owner, dep)
-        if dep.identifier.nil? then
-          logger.debug { "Creating dependent #{dep.qp}..." }
-          return create(dep)
+      def save_dependent_if_changed(owner, attribute, dependent)
+        if dependent.identifier.nil? then
+          logger.debug { "Creating #{owner.qp} #{attribute} dependent #{dependent.qp}..." }
+          return create(dependent)
         end
-        changes = dep.changed_attributes
-        logger.debug { "#{owner.qp} dependent #{dep.qp} changed for attributes #{changes.to_series}." } unless changes.empty?
-        if changes.any? { |attr| not dep.class.attribute_metadata(attr).dependent? } then
-          logger.debug { "Updating changed #{owner.qp} dependent #{dep.qp}..." }
-          update(dep)
+        changes = dependent.changed_attributes
+        logger.debug { "#{owner.qp} #{attribute} dependent #{dependent.qp} changed for attributes #{changes.to_series}." } unless changes.empty?
+        if changes.any? { |attr| not dependent.class.attribute_metadata(attr).dependent? } then
+          # the owner save operation
+          op = operations.last
+          # The dependent is auto-generated if the owner was created or auto-generated and
+          # the dependent attribute is auto-generated.
+          ag = (op.type == :create or op.autogenerated?) && owner.class.attribute_metadata(attribute).autogenerated?
+          logger.debug { "Updating the changed #{owner.qp} #{attribute} dependent #{dependent.qp}..." }
+          perform(:update, dependent, :autogenerated => ag) { update_object(dependent) }
         else
-          save_dependents(dep)
+          save_changed_dependents(dependent)
         end
       end
+      
+      # Creates the given dependent domain object.
+      #
+      # @param (see #save_dependent)
+      def create_dependent(owner, dep)
+        create(dep)
+      end
     end
   end
 end