caruby-core 1.4.9 → 1.5.1

data/lib/caruby/database/store_template_builder.rb

@@ -7,7 +7,7 @@ module CaRuby
     # 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. 
+    #   which {Attribute#cascade_update_to_create?} or have an identifier. 
     #
     # @param [Database] database the target database 
     # @yield [ref] the required selector block which determines which attributes are copied into the template
@@ -21,23 +21,23 @@ module CaRuby
       # 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) }
+      @prereq_vstr = ReferenceVisitor.new(:prune_cycle) { |ref| savable_template_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,
+      # @quirk caTissue 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.
       # The copy attributes are parameterized by the top-level save target.
       copier = Proc.new do |src|
-        copy = src.copy
-        logger.debug { "Store template builder copied #{src.qp} into #{copy}." }
-        copy_proxied_save_references(src, copy)
-        copy
+        tgt = src.copy
+        logger.debug { "Store template builder copied #{src.qp} into #{tgt}." }
+        copy_proxied_save_references(src, tgt)
+        tgt
       end
       # the template copier
-      @copy_vstr = CopyVisitor.new(:mergeable => savable, :copier => copier) { |ref| savable_cascaded_attributes(ref) }
+      @copy_vstr = CopyVisitor.new(:mergeable => savable, :copier => copier) { |ref| savable_template_attributes(ref) }
     end
 
     # Returns a new domain object which serves as the argument for obj create or update.
@@ -47,31 +47,31 @@ module CaRuby
     # to store obj. The template object graph contains only those references which are
     # essential to the store operation.
     #
-    # 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 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.
+    # @quirk caCORE +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 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 Metadata
+    #   methods.
     #
-    # 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.
+    # @quirk caCORE +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.
     #
-    # caCORE alert - application business logic performs unnecessary verification
-    # of uncascaded references as if they were a cascaded create. This can result in
-    # an obscure ApplicationException. The server.log stack trace indicates the
-    # extraneous verification code. For example, +caTissue+ +NewSpecimenBizLogic.validateStorageContainer+
-    # is unnecessarily called on a SpecimenCollectionGroup (SCG) update. SCG does not
-    # cascade to Specimen, but caTissue considers the SCG update a Specimen create
-    # anyway if the SCG references a Specimen without an identifier. The Specimen
-    # business logic then raises an exception when it finds a StorageContainer
-    # without an identifier in the Specimen object graph. Therefore, an update must
-    # build a storable template which prunes the update object graph to exclude uncascaded
-    # objects. These uncascaded objects should be ignored by the application but aren't.
+    # @quirk caCORE application business logic performs unnecessary verification
+    #   of uncascaded references as if they were a cascaded create. This can result in
+    #   an obscure ApplicationException. The server.log stack trace indicates the
+    #   extraneous verification code. For example, +caTissue+ +NewSpecimenBizLogic.validateStorageContainer+
+    #   is unnecessarily called on a SpecimenCollectionGroup (SCG) update. SCG does not
+    #   cascade to Specimen, but caTissue considers the SCG update a Specimen create
+    #   anyway if the SCG references a Specimen without an identifier. The Specimen
+    #   business logic then raises an exception when it finds a StorageContainer
+    #   without an identifier in the Specimen object graph. Therefore, an update must
+    #   build a storable template which prunes the update object graph to exclude uncascaded
+    #   objects. These uncascaded objects should be ignored by the application but aren't.
     #
     # @param [Resource] obj the domain object to save
     # @return [Resource] the template to use as the caCORE argument
@@ -92,10 +92,10 @@ module CaRuby
     # Ensure that the given domain object obj can be created or updated by setting the identifier for
     # each independent reference in the create template object graph.
     #
-    # caCORE alert - +caCORE+ raises an ApplicationException if an independent reference in the create or
-    # update argument does not have an identifier. The +caCORE+ server log error is as follows:
-    #   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.
+    # @quirk caCORE +caCORE+ raises an ApplicationException if an independent reference in the create or
+    #   update argument does not have an identifier. The +caCORE+ server log error is as follows:
+    #     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. Enable the lazy loader to fetch
       # create references from the database where needed to build defaults.
@@ -113,24 +113,24 @@ module CaRuby
     
     # Returns the attributes to visit in building the template for the given
     # domain object. The visitable attributes consist of the following:
-    # * The {ResourceAttributes#unproxied_save_template_attributes} filtered as follows:
+    # * The {Attributes#unproxied_savable_template_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_save_template_attributes} are included if and
+    # * The {Attributes#proxied_savable_template_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.
+    # @quirk caTissue 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)
+    def savable_template_attributes(obj)
       # The starting set of candidate attributes is the unproxied cascaded references.
-      unproxied = savable_attributes(obj, obj.class.unproxied_save_template_attributes)
+      unproxied = savable_attributes(obj, obj.class.unproxied_savable_template_attributes)
       # The proxied attributes to save.
       proxied = savable_proxied_attributes(obj)
       # The combined set of savable attributes
@@ -139,11 +139,11 @@ module CaRuby
     
     # Filters the given attributes, if necessary, to exclude attributes as follows:
     # * If the save operation is a create, then exclude the
-    #   {AttributeMetadata#autogenerated_on_create?} attributes.
+    #   {Attribute#autogenerated_on_create?} attributes.
     #
     # @param [Resource] obj the visited domain object
-    # @param [ResourceAttributes::Filter] the savable attribute filter
-    # @return [ResourceAttributes::Filter] the composed attribute filter
+    # @param [Attributes::Filter] the savable attribute filter
+    # @return [Attributes::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
@@ -155,7 +155,7 @@ module CaRuby
     # 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. 
+    #   which {Attribute#cascade_update_to_create?} or have an identifier. 
     #
     # @param (see #mergeable_attributes)
     # @return (see #mergeable_attributes)
@@ -178,7 +178,7 @@ module CaRuby
     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.
-      obj.class.proxied_save_template_attributes.reject do |attr|
+      obj.class.proxied_savable_template_attributes.reject do |attr|
         ref = obj.send(attr)
         case ref
           when Enumerable then ref.any? { |dep| not dep.identifier }
@@ -189,18 +189,18 @@ module CaRuby
     
     # Copies proxied references as needed.
     #
-    # caTissue alert - even though Specimen save cascades to SpecimenPosition,
-    # SpecimenPosition cannot be updated directly. Rather than simply not
-    # cascading to the SpecimenPosition, caTissue checks a Specimen save argument
-    # to ensure that the SpecimenPosition reflects the current database state
-    # rather than the desired cascaded state. Play along with this bizarre
-    # mechanism by adding our own bizarre work-around mechanism to copy a
-    # proxied reference only if it has an identifier. This works only because
-    # another work-around in the #{CaRuby::Database::Writer} updates proxied
-    # references via the proxy create before building the update template.
+    # @quirk caTissue even though Specimen save cascades to SpecimenPosition,
+    #   SpecimenPosition cannot be updated directly. Rather than simply not
+    #   cascading to the SpecimenPosition, caTissue checks a Specimen save argument
+    #   to ensure that the SpecimenPosition reflects the current database state
+    #   rather than the desired cascaded state. Play along with this bizarre
+    #   mechanism by adding our own bizarre work-around mechanism to copy a
+    #   proxied reference only if it has an identifier. This works only because
+    #   another work-around in the #{CaRuby::Database::Writer} updates proxied
+    #   references via the proxy create before building the update template.
     def copy_proxied_save_references(obj, template)
       return unless obj.identifier
-      obj.class.proxied_save_template_attributes.each do |attr|
+      obj.class.proxied_savable_template_attributes.each do |attr|
         # the proxy source
         ref = obj.send(attr)
         case ref

data/lib/caruby/database/writer.rb

@@ -19,7 +19,7 @@ module CaRuby
         # 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 } 
+        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
@@ -125,7 +125,7 @@ module CaRuby
       # Note that some applications restrict or forbid delete operations. Check the specific application
       # documentation to determine whether deletion is supported.
       #
-      #@param [Resource] obj the domain object to delete
+      # @param [Resource] obj the domain object to delete
       # @raise [DatabaseError] if the database operation fails
       def delete(obj)
         perform(:delete, obj) { delete_object(obj) }
@@ -133,9 +133,9 @@ module CaRuby
 
       # Creates the domain object obj, if necessary.
       #
-      # Raises ArgumentError if obj is nil or empty.
-      # Raises DatabaseError if obj could not be created.
-      # The return value is undefined.
+      # @param [Resource, <Resource>] obj the domain object or collection of domain objects to find or create 
+      # @raise [ArgumentError] if obj is nil or empty
+      # @raise [DatabaseError] if obj could not be created
       def ensure_exists(obj)
         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 }
@@ -237,50 +237,49 @@ module CaRuby
       # Creates obj by submitting a template to the persistence service. Ensures that the domain
       # objects referenced by the created obj exist and are correctly stored.
       #
-      # caCORE alert - submitting the object directly for create runs into various caTissue bizlogic
-      # traps, e.g. Participant CPR is not cascaded but Participant bizlogic checks that each CPR
-      # referenced by Participant is ready to be created. It is treacherous to make assumptions
-      # about what caTissue bizlogic will or will not check. Therefore, the safer strategy is to
-      # build a template for submission that includes only the object cascaded and direct
-      # non-cascaded independent references. The independent references are created if necessary.
-      # The template thus includes only as much content as can safely pass through the caTissue
-      # bizlogic minefield.
-      #
-      # caCORE alert - caCORE create does not update the submitted object to reflect the created
-      # content. The create result is a separate object, which in turn does not always reflect
-      # the created content, e.g. caTissue ignores auto-generated attributes such as Container
-      # name. Work-around is to merge the create result into the object being created, being
-      # careful to merge only the fetched content in order to avoid the dreaded out-of-session
-      # error message. The post-create cascaded dependent hierarchy is traversed to capture
-      # the created state for each created object.
-      #
-      # The ignored content is handled separately by fetching the ignored content from
-      # the database, comparing it to the desired content as reflected in the submitted
-      # create argument object, and submitting a post-create caCORE update as necessary to
-      # force caCORE to reflect the desired content. This is complicated by the various
-      # auto-generation schemes, e.g. in caTissue, that require a careful fetch, match and
-      # merge logic to make sense of how what was actually created corresponds to the desired
-      # content expressed in the create argument object graph.
-      #
-      # There are thus several objects involved in the create process:
-      # * the object to create
-      # * the template for caCORE createObject submission
-      # * the caCORE createObject result
-      # * the post-create fetched object that reflects the persistent content
-      # * the template for post-create caCORE updateObject submission
-      #
-      # This object menagerie is unfortunate but unavoidable if we are to navigate the treacherous
-      # caCORE create process and ensure that:
-      # 1. the database reflects the create argument.
-      # 2. the created object reflects the database content.
+      # @quirk caCORE submitting the object directly for create runs into various caTissue bizlogic
+      #   traps, e.g. Participant CPR is not cascaded but Participant bizlogic checks that each CPR
+      #   referenced by Participant is ready to be created. It is treacherous to make assumptions
+      #   about what caTissue bizlogic will or will not check. Therefore, the safer strategy is to
+      #   build a template for submission that includes only the object cascaded and direct
+      #   non-cascaded independent references. The independent references are created if necessary.
+      #   The template thus includes only as much content as can safely pass through the caTissue
+      #   bizlogic minefield.
+      #
+      # @quirk caCORE caCORE create does not update the submitted object to reflect the created
+      #   content. The create result is a separate object, which in turn does not always reflect
+      #   the created content, e.g. caTissue ignores auto-generated attributes such as Container
+      #   name. Work-around is to merge the create result into the object being created, being
+      #   careful to merge only the fetched content in order to avoid the dreaded out-of-session
+      #   error message. The post-create cascaded dependent hierarchy is traversed to capture
+      #   the created state for each created object.
+      #
+      #   The ignored content is handled separately by fetching the ignored content from
+      #   the database, comparing it to the desired content as reflected in the submitted
+      #   create argument object, and submitting a post-create caCORE update as necessary to
+      #   force caCORE to reflect the desired content. This is complicated by the various
+      #   auto-generation schemes, e.g. in caTissue, that require a careful fetch, match and
+      #   merge logic to make sense of how what was actually created corresponds to the desired
+      #   content expressed in the create argument object graph.
+      #
+      #   There are thus several objects involved in the create process:
+      #   * the object to create
+      #   * the template for caCORE createObject submission
+      #   * the caCORE createObject result
+      #   * the post-create fetched object that reflects the persistent content
+      #   * the template for post-create caCORE updateObject submission
+      #
+      #   This object menagerie is unfortunate but unavoidable if we are to navigate the treacherous
+      #   caCORE create process and ensure that:
+      #   1. the database reflects the create argument.
+      #   2. the created object reflects the database content.
       #
       # @param (see #create)
       # @return obj
       def create_from_template(obj)
         # The create template. Independent saved references are created as necessary.
-        tmpl = build_create_template(obj)        
+        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.references.reject { |ref| ref.identifier }
@@ -297,7 +296,7 @@ module CaRuby
         build_save_template(obj, @cr_tmpl_bldr)
       end
 #
-      # caCORE alert - application create logic might ignore a non-domain attribute value,
+      # @quirk caCORE application create logic might ignore a non-domain attribute value,
       # e.g. the caTissue StorageContainer auto-generated name attribute. In other cases, the application
       # always ignores a non-domain attribute value, so the object should not be saved even if it differs
       # from the stored result, e.g. the caTissue CollectionProtocolRegistration unsaved
@@ -306,7 +305,7 @@ module CaRuby
       # to update the saved object.
       #
       # This method returns whether the saved obj differs from the stored source for any
-      # {ResourceAttributes#autogenerated_nondomain_attributes}.
+      # {Attributes#autogenerated_nondomain_attributes}.
       #
       # @param [Resource] the created domain object
       # @param [Resource] the stored database content source domain object
@@ -344,14 +343,14 @@ module CaRuby
       
       # Returns whether the given creatable domain attribute with value obj satisfies
       # each of the following conditions:
-      # * the attribute is {AttributeMetadata#independent?}
-      # * the attribute is not an {AttributeMetadata#owner?}
+      # * the attribute is {Attribute#independent?}
+      # * the attribute is not an {Attribute#owner?}
       # * the obj value is unsaved
       # * the attribute is not mandatory
       # * the attribute references a {#pending_create?} save context.
       #
       # @param obj (see #create)
-      # @param [AttributeMetadata] attr_md candidate attribute metadata
+      # @param [Attribute] 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.independent? and
@@ -413,13 +412,10 @@ module CaRuby
         
         # update a cascaded dependent by updating the owner
         owner = cascaded_owner(obj)
-        result = update_dependent(owner, obj) if owner
-        # if not cascaded, then update directly with a template
-        result ||= create_from_template(obj)
+        if owner then return update_cascaded_dependent(owner, obj) end
         
-        # update using a template
+        # Not cascaded dependent; update using a template,
         tmpl = build_update_template(obj)
-        
         # call the caCORE service with an obj update template
         save_with_template(obj, tmpl) { |svc| svc.update(tmpl) }
         # take a snapshot of the updated content
@@ -427,9 +423,9 @@ module CaRuby
       end
       
       # Returns the owner that can cascade update to the given object.
-      # The owner is the #{Resource#effective_owner_attribute_metadata} value
-      # for which the owner attribute {AttributeMetadata#inverse_attribute_metadata}
-      # is {AttributeMetadata#cascaded?}.
+      # The owner is the #{Resource#effective_owner_attribute} value
+      # for which the owner attribute {Attribute#inverse_metadata}
+      # is {Attribute#cascaded?}.
       # 
       # @param [Resource] obj the domain object to update
       # @return [Resource, nil] the owner which can cascade an update to the object, or nil if none
@@ -439,14 +435,14 @@ module CaRuby
         # the owner attribute
         oattr = obj.effective_owner_attribute
         if oattr.nil? then raise DatabaseError.new("Dependent #{obj} does not have an owner") end
-        dep_md = obj.class.attribute_metadata(oattr).inverse_attribute_metadata
+        dep_md = obj.class.attribute_metadata(oattr).inverse_metadata
         if dep_md and dep_md.cascaded? then
           obj.send(oattr)
         end
       end
       
-      def update_dependent(owner, obj)
-        logger.debug { "Updating #{obj} by saving the owner #{owner}..." }
+      def update_cascaded_dependent(owner, obj)
+        logger.debug { "Updating cascaded dependent #{obj} by updating the owner #{owner}..." }
         update(owner)
       end
       
@@ -458,33 +454,33 @@ module CaRuby
         obj.take_snapshot
       end
       
-      # caTissue alert - the conditions for when and how to include a proxied dependent are
-      # are intricate and treacherous. So far as can be determined, in the case of a
-      # SpecimenPosition proxied by a TransferEventParameters, the sequence is as follows:
-      # * If a Specimen without a previous position is updated with a position, then
-      #   the update template should not include the target position. Subsequent to the
-      #   Specimen update, the TransferEventParameters proxy is created.
-      #   This creates a new position in the database as a server side-effect. caRuby
-      #   then fetches the new position and merges it into the target position.
-      # * If a Specimen with a previous position is updated, then the update template
-      #   must reflect the current datbase position state. Therefore, caRuby first
-      #   creates the proxy to update the database state.
-      # * The TransferEventParameters create must reference a Specimen with the current
-      #   database position state, not the new position state.
-      # * Update of a Specimen with a current database position must reference a
-      #   position which reflects that database state. This is true even if the position
-      #   has not changed. The position must be complete and consistent with the database
-      #   state. E.g. omitting the position storage container is accepted by caTissue
-      #   but corrupts the database side and has adverse delayed effects.
-      # * Specimen create (but not auto-generated update) cannot include a position
-      #   (although that might have changed in the 1.1.2 release). The target position
-      #   must be created via the proxy after the Specimen is created.
+      # @quirk caTissue the conditions for when and how to include a proxied dependent are
+      #   are intricate and treacherous. So far as can be determined, in the case of a
+      #   SpecimenPosition proxied by a TransferEventParameters, the sequence is as follows:
+      #   * If a Specimen without a previous position is updated with a position, then
+      #     the update template should not include the target position. Subsequent to the
+      #     Specimen update, the TransferEventParameters proxy is created.
+      #     This creates a new position in the database as a server side-effect. caRuby
+      #     then fetches the new position and merges it into the target position.
+      #   * If a Specimen with a previous position is updated, then the update template
+      #     must reflect the current datbase position state. Therefore, caRuby first
+      #     creates the proxy to update the database state.
+      #   * The TransferEventParameters create must reference a Specimen with the current
+      #     database position state, not the new position state.
+      #   * Update of a Specimen with a current database position must reference a
+      #     position which reflects that database state. This is true even if the position
+      #     has not changed. The position must be complete and consistent with the database
+      #     state. E.g. omitting the position storage container is accepted by caTissue
+      #     but corrupts the database side and has adverse delayed effects.
+      #   * Specimen create (but not auto-generated update) cannot include a position
+      #     (although that might have changed in the 1.1.2 release). The target position
+      #     must be created via the proxy after the Specimen is created.
       #
       # @param (see #update)
-      # @return [<Resource>] the #{ResourceAttributes#proxied_save_template_attributes} dependents
+      # @return [<Resource>] the #{Attributes#proxied_savable_template_attributes} dependents
       #   which are #{Persistable#changed?}
       def updatable_proxied_dependents(obj)
-        attrs = obj.class.proxied_save_template_attributes
+        attrs = obj.class.proxied_savable_template_attributes
         return Array::EMPTY_ARRAY if attrs.empty?
         deps = []
         attrs.each do |attr|
@@ -537,7 +533,7 @@ module CaRuby
       def submit_save_template(obj, template)
         svc = persistence_service(template.class)
         result = template.identifier ? svc.update(template) : svc.create(template)
-        logger.debug { "Store #{obj.qp} with template #{template.qp} produced caCORE result: #{result}." }
+        logger.debug { "Save #{obj.qp} with template #{template.qp} produced caCORE result: #{result}." }
         result
       end
       
@@ -557,7 +553,6 @@ module CaRuby
         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?(target, source) then
@@ -581,26 +576,30 @@ module CaRuby
       # 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.
+      # @quirk caTissue 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.
+        # 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|
+          # Skip unsaved source objects. This occurs, e.g., if a transient source reference is generated
+          # on demand.
+          next if src.identifier.nil?
           # capture the id
           prev_id = tgt.identifier
+          # The target dependents will be visited, so persistify the target non-recursively.
           persistify_object(tgt, src)
-          # if tgt is an auto-generated reference, then add defaults
+          # 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:
@@ -621,7 +620,7 @@ module CaRuby
         set_inverses(source)
       end
       
-      # Refetches the given create result source if there are any {ResourceAttributes#autogenerated_nondomain_attributes}
+      # Refetches the given create result source if there are any {Attributes#autogenerated_nondomain_attributes}
       # which must be fetched to reflect the database state.
       #
       # @param source (see #sync_saved)
@@ -654,7 +653,7 @@ module CaRuby
       # 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
+      # * {Attributes#domain_attributes} which include a source reference without an identifier
       #
       # @param (see #sync_saved)
       # @return [<Symbol>] the attributes which must be fetched
@@ -687,7 +686,7 @@ module CaRuby
       def save_changed_dependents(obj)
         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?
+          logger.debug { "Saving the #{obj} #{attr} dependents #{deps.qp(:single_line)} which have changed..." } unless deps.empty?
           deps.each { |dep| save_dependent_if_changed(obj, attr, dep) }
         end
       end
@@ -704,6 +703,7 @@ module CaRuby
           return create(dependent)
         end
         changes = dependent.changed_attributes
+        # If the dependent identifier is missing, then the identifier was probably created on demand. 
         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

data/lib/caruby/database.rb

@@ -77,23 +77,23 @@ module CaRuby
 
     # Creates a new Database with the specified service name and options.
     #
-    # caCORE alert - obtaining a caCORE session instance mysteriously depends on referencing the
-    # application service first. Therefore, the default persistence service appService method must
-    # be called after it is instantiated and before the session is instantiated. However, when
-    # the appService method is called just before a session is acquired, then this call corrupts
-    # the object state of existing objects.
+    # @quirk caCORE obtaining a caCORE session instance mysteriously depends on referencing the
+    #   application service first. Therefore, the default persistence service appService method must
+    #   be called after it is instantiated and before the session is instantiated. However, when
+    #   the appService method is called just before a session is acquired, then this call corrupts
+    #   the object state of existing objects.
     #
-    # Specifically, when a CaTissue::CollectionProtocol is created which references a
-    # CaTissue::CollectionProtocolRegistration which in turn references a CaTissue::Participant,
-    # then the call to PersistenceService.appService replaces the CaTissue::Participant
-    # reference with a difference CaTissue::Participant instance. The work-around for
-    # this extremely bizarre bug is to call appService immediately after instantiating
-    # the default persistence service.
+    #   Specifically, when a CaTissue::CollectionProtocol is created which references a
+    #   CaTissue::CollectionProtocolRegistration which in turn references a CaTissue::Participant,
+    #   then the call to PersistenceService.appService replaces the CaTissue::Participant
+    #   reference with a difference CaTissue::Participant instance. The work-around for
+    #   this extremely bizarre bug is to call appService immediately after instantiating
+    #   the default persistence service.
     #
-    # This bug might be a low-level JRuby-Java-caCORE-Hibernate confusion where something in
-    # caCORE stomps on an existing JRuby object graph. To reproduce, move the appService call
-    # to the start_session method and run PCBIN::MigrationTest#test_save with all but the
-    # verify_save(:biopsy, BIOPSY_OPTS) line commented out.
+    #   This bug might be a low-level JRuby-Java-caCORE-Hibernate confusion where something in
+    #   caCORE stomps on an existing JRuby object graph. To reproduce, move the appService call
+    #   to the start_session method and run {PCBIN::MigrationTest#test_save} with all but the
+    #   verify_save(:biopsy, BIOPSY_OPTS) line commented out.
     #
     # @param [String] service_name the name of the default {PersistenceService}
     # @param [{Symbol => String}] opts access options
@@ -251,10 +251,10 @@ module CaRuby
     
     # @return [Cache] a new object cache.
     def create_cache
-      # JRuby alert - identifier is not a stable object when fetched from the database, i.e.:
-      #   obj.identifier.equal?(obj.identifier) #=> false
-      # This is probably an artifact of jRuby Numeric - Java Long conversion interaction
-      # combined with hash access use of the eql? method. Work-around is to make a Ruby Integer.
+      # @quirk JRuby identifier is not a stable object when fetched from the database, i.e.:
+      #     obj.identifier.equal?(obj.identifier) #=> false
+      #   This is probably an artifact of jRuby Numeric - Java Long conversion interaction
+      #   combined with hash access use of the eql? method. Work-around is to make a Ruby Integer.
       Cache.new do |obj|
         raise ArgumentError.new("Can't cache object without identifier: #{obj}") unless obj.identifier
         obj.identifier.to_s.to_i