caruby-tissue 1.4.2 → 1.5.1

data/lib/catissue/annotation/annotation_module.rb

@@ -1,4 +1,4 @@
-require 'caruby/domain/resource_module'
+require 'caruby/domain'
 require 'catissue/annotation/annotation'
 require 'catissue/annotation/annotation_class'
 require 'catissue/annotation/proxy'
@@ -7,15 +7,15 @@ require 'catissue/annotation/de_integration'
 
 module CaTissue
   module AnnotationModule
-    include CaRuby::ResourceModule
+    include CaRuby::Domain
 
-    # @return [AnnotationClass] the annotation proxy class 
-    attr_accessor :proxy
+    # @return [ProxyClass] the annotation proxy class 
+    attr_reader :proxy
       
     # @return [Class] the hook-annotation association class, or nil for 1.1.x caTissue
     attr_reader :record_entry_class
       
-    # @return [Symbol] the {#record_entry_class} hook writer method, or nil for 1.1.x caTissue
+    # @return [Symbol] the {#de_integration_proxy_class} hook writer method, or nil for 1.1.x caTissue
     attr_reader :record_entry_hook_writer
 
     # @param [AnnotationModule] mod the annotation module to build
@@ -29,43 +29,33 @@ module CaTissue
       mod.initialize_annotation(hook, opts)
     end
     
+    # Builds the annotation module.
+    # This method intended to be called only by {AnnotationModule.extend_module}.
+    #
+    # @param (see AnnotationModule.extend_module)
     def initialize_annotation(hook, opts)
       logger.debug { "Building #{hook.qp} annotation #{qp}..." }
-      @java_package = opts[:package]
+      pkg = opts[:package]
       @svc_nm = opts[:service]
-      create_mixin(hook)
-      # Proxy initialization has to set proxy mid-initialization.
-      # That is why @proxy is writable. Although setting @proxy
-      # is redundant here, do so since that is the better approach
-      # and will be necessary if and when proxy init is cleaned up.
-      rec_entry = opts[:record_entry]
-      if rec_entry then
-        if Annotation::DEIntegration.const_defined?(rec_entry) then
-          @record_entry_class = Annotation::DEIntegration.const_get(rec_entry)
-          @record_entry_hook_writer = "#{hook.name.demodulize.underscore}=".to_sym
-        else
-          logger.warn("Ignored missing annotation #{name} record entry class #{rec_entry}.")
-          rec_entry = nil
-        end
+      # Enable the resource metadata aspect.
+      md_proc = Proc.new { |klass| AnnotationClass.extend_class(klass, self) }
+      CaRuby::Domain::Importer.extend_module(self, :mixin => Annotation, :metadata => md_proc, :package => pkg)
+      dei = hook.de_integration_proxy_class
+      if dei then
+        import_record_entry_class(dei, hook)
+        pxy_nm = dei.name.demodulize
       end
-      @proxy = import_proxy(hook, rec_entry)
-      logger.debug { "Building #{name} #{hook.qp} annotation proxy #{@proxy.class.name}..." }
-      @proxy.extend(Annotation::ProxyClass)
+      @proxy = import_proxy(hook, pxy_nm)
+      load_annotation_class_definitions(hook)
       logger.debug { "Built #{hook.qp} annotation #{qp}." }
     end
     
-    # Ensures that each primary annotation in this module has a proxy reference attribute.
-    # The primary annotation creates a proxy attribute if necessary.
-    def ensure_proxy_attributes_are_defined
-      logger.debug { "Ensuring that #{qp} primary annotations reference the proxy #{@proxy.qp}..." }
-      @rsc_classes.each { |klass| klass.ensure_primary_has_proxy(@proxy) }
-    end
-    
-    # Builds an annotation dependency hierarchy starting at the proxy.
-    def add_annotation_dependents
-      @proxy.add_annotation_dependents
+    # @return (ProxyClass#hook)
+    def hook
+      @proxy.hook
     end
     
+    # @return [CaRuby::PersistenceService] this module's application service
     def persistence_service
       @ann_svc ||= Database.instance.annotator.create_annotation_service(self, @svc_nm)
     end
@@ -73,41 +63,39 @@ module CaTissue
     private
     
     # The location of the domain class definitions.
-    DOMAIN_DIR = File.join(File.dirname(__FILE__), '..', 'domain')
+    DOMAIN_DIR = File.join(File.dirname(File.dirname(__FILE__)), 'domain')
     
-    def create_mixin(hook)
-      module_eval("module Resource; include Annotation; end")
-      @mixin = const_get('Resource')
-      class << self
-        def class_added(klass)
-          klass.extend(AnnotationClass)
-          logger.debug { "#{klass} marked as an annotation class." }
-          if @proxy then klass.ensure_primary_has_proxy(@proxy) end
-        end
-      end
-      ann_subdir = name.demodulize.underscore
-      @ann_def_dir = File.join(DOMAIN_DIR, hook.name.demodulize.underscore, ann_subdir)
-      load_dir(@ann_def_dir)
+    def load_annotation_class_definitions(hook)
+      dir = File.join(DOMAIN_DIR, hook.name.demodulize.underscore, name.demodulize.underscore)
+      load_dir(dir)
+    end
+    
+    # Sets the record entry instance variables for the given class name, if it exists
+    # as a {Annotation::DEIntegration} proxy class. caTissue v1.1.x does not have
+    # a record entry class.
+    #
+    # @param [String] the record entry class name specified in the
+    #   {CaTissue::AnntatableClass#add_annotation_attribute} +:record_entry+ option
+    def import_record_entry_class(klass, hook)
+      @record_entry_class = const_get(klass.name.demodulize.to_sym)
+      @record_entry_hook_writer = "#{hook.name.demodulize.underscore}=".to_sym
     end
     
     # @param hook (see #initialize_annotation)
-    # @param [String] name the demodulized name of the proxy class, or nil for caTissue 1.1.x
+    # @param [String] name the demodulized name of the proxy class
+    #   (default is the demodulized hook class name)
     def import_proxy(hook, name=nil)
-      logger.debug { "Importing #{qp} #{hook.qp} proxy#{' ' + name if name}..." }
       name ||= hook.name.demodulize
+      logger.debug { "Importing #{qp} #{hook.qp} annotation proxy..." }
       begin
-        const_get(name.to_sym)
-      rescue CaRuby::JavaIncludeError
-      raise
+        klass = const_get(name.to_sym)
+      rescue CaRuby::JavaImportError
         raise AnnotationError.new("#{hook.qp} annotation #{qp} does not have a hook proxy class - #{$!}")
       end
-    end
-    
-    # Infers the given annotation class's inverses attributes.
-    #
-    # @param (see ResourceModule#imported)
-    def imported(klass)
-      klass.infer_inverses
+      klass.extend(Annotation::ProxyClass)
+      klass.hook = hook
+      logger.debug { "Built #{name} #{hook.qp} annotation proxy #{klass}." }
+      klass
     end
   end
 end

data/lib/catissue/annotation/de_integration.rb

@@ -1,3 +1,5 @@
+require 'caruby/domain'
+
 module CaTissue
   module Annotation
     # DEIntegration encapsulates the +edu.wustl.catissuecore.domain.deintegration+ package in caTissue 1.2 and higher.
@@ -6,13 +8,21 @@ module CaTissue
       # @return [Class] yet another undocumented special-purpose association record entry class
       #   which associates the given hook proxy class symbol to an annotation
       def self.const_missing(symbol)
+        name = [PKG, symbol].join('.')
+        logger.debug { "Importing DE integration proxy Java class #{name}..." }
         begin
-          java_import [PKG, symbol].join('.')
-        rescue Exception
+          java_import name
+        rescue NameError
           super
         end
       end
       
+      # @param [String] name the annotated hook class name
+      # @return [Class, nil] the hook proxy class, or nil if none defined
+      def self.proxy(name)
+        const_get(name.to_sym) rescue nil
+      end
+    
       private
   
       # The auxiliary record entry class Java package name.

data/lib/catissue/annotation/proxy.rb

@@ -2,26 +2,20 @@ module CaTissue
   module Annotation
     # {CaTissue::Resource} annotation hook proxy mix-in.
     module Proxy
-      # The hook proxy identifier is the hook identifier.
-      # This method delegates to the hook.
-      #
-      # @return [Integer] the hook identifier
-      def identifier
-        hook.identifier if hook
+      # @return [Annotatable] the annotated domain object  
+      def hook
+        send(self.class.owner_attribute_metadata.reader)
       end
       
-      # The hook proxy identifier cannot be set directly. Assignment is a no-op.
-      #
-      # @param [Integer] value the (ignored) identifier value
-      def identifier=(value); end
+      # @param [Annotatable] obj the domain object to annotate  
+      def hook=(obj)
+        send(self.class.owner_attribute_metadata.writer, obj)
+      end
       
-      # Sets the +id+ Java property to the hook identifier.
-      # This method must be called before saving an annotation that references this proxy.
-      def ensure_identifier_reflects_hook
-        if getId.nil? then
-          setId(hook.identifier)
-          logger.debug { "Set annotation proxy #{self} identifier to that of the hook entity #{hook.qp}." }
-        end
+      # Ensures that this proxy's hook exists in the database.
+      def ensure_hook_exists
+        if hook.nil? then raise AnnotationError.new("Annotation proxy #{self} is missing the hook domain object") end
+        hook.ensure_exists
       end
     end
   end

data/lib/catissue/annotation/proxy_1_1.rb

@@ -0,0 +1,47 @@
+require 'catissue/annotation/proxy'
+
+module CaTissue
+  module Annotation
+    # caTissue 1.1.x {CaTissue::Resource} annotation hook proxy mix-in.
+    module Proxy_1_1
+      include Proxy
+      
+      # The hook proxy identifier is the hook identifier.
+      # This method delegates to the hook.
+      #
+      # @return [Integer] the hook identifier
+      def identifier
+        hook.identifier if hook
+      end
+      
+      # The proxy identifier cannot be set directly. Assignment is a no-op.
+      #
+      # @param [Integer] value the (ignored) identifier value
+      def identifier=(value); end
+      
+      # @param [Annotatable] obj the domain object to annotate  
+      def hook=(obj)
+        super
+        ensure_identifier_reflects_hook
+      end
+      
+      # Ensures that this proxy's hook exists in the database. This proxy's identifier is set to
+      # the hook identifier.
+      def ensure_hook_exists
+        super
+        ensure_identifier_reflects_hook
+      end
+      
+      private
+      
+      # Sets the +id+ Java property to the hook identifier.
+      # This method must be called before saving a caTissue 1.1.x annotation that references this proxy.
+      def ensure_identifier_reflects_hook
+        if getId.nil? and hook and hook.identifier then
+          setId(hook.identifier)
+          logger.debug { "Set annotation proxy #{self} identifier to that of the hook entity #{hook.qp}." }
+        end
+      end
+    end
+  end
+end

data/lib/catissue/annotation/proxy_class.rb

@@ -1,57 +1,61 @@
 require 'set'
+require 'caruby/util/collection'
+require 'caruby/util/partial_order'
 require 'catissue/annotation/annotation'
-require 'catissue/annotation/proxy'
+require 'catissue/annotation/proxy_1_1'
+require 'catissue/annotation/record_entry_proxy'
 
 module CaTissue
   module Annotation
     # Annotation hook proxy class mix-in.
     module ProxyClass
-      # @return [AnnotatableClass] the hook class for this proxy
-      attr_reader :hook
-      
       # @param [Class] klass the proxy class
       def self.extended(klass)
         super
-        klass.class_eval { include Proxy }
+        # distinguish the 1.1 from the 1.2 proxy class
+        mixin = klass.name =~ /RecordEntry$/ ? RecordEntryProxy : Proxy_1_1
+        klass.class_eval { include mixin }
       end
       
-      def annotation_attributes
-        @ann_attrs ||= infer_annotation_attributes
+      # @return [AnnotatableClass] the hook class for this proxy
+      def hook
+        owner_type
       end
       
-      # Sets this proxy's hook to the given class. 
-      # Creates the proxy => hook attribute with the given hook => proxy inverse.
+      # Sets this proxy's hook to the given class and creates the
+      # proxy => hook attribute with the given hook => proxy inverse.
       #
-      # @param [Class] klass the hook class
-      # @param [Symbol] inverse the hook class hook => proxy attribute
-      def set_hook(klass, inverse)
-        @hook = klass
+      # @param [AnnotatableClass] klass the annotated domain object class
+      def hook=(klass)
         # Make a new hook reference attribute.
-        attr_accessor(:hook)
+        attr = klass.name.demodulize.underscore
+        attr_accessor(attr)
         # The attribute type is the given hook class.
-        add_attribute(:hook, klass)
-        # Setting one end of the hook <-> proxy association sets the other end.
-        set_attribute_inverse(:hook, inverse)
-        logger.debug { "Added #{klass.qp} annotation proxy => hook attribute with inverse #{klass.qp}.#{inverse}." }
+        add_attribute(attr, klass)
+        logger.debug { "Added #{klass.qp} annotation proxy => hook attribute #{attr}." }
       end
       
       # Adds each proxy => annotation reference as a dependent attribute.
-      def add_annotation_dependents
-        # first add the direct dependents
-        annotation_attributes.each_metadata do |attr_md|
-          attr_md.type.add_dependent_attributes
-        end
-        # now add the recursive indirect dependents
-        annotation_attributes.each_metadata do |attr_md|
-          attr_md.type.add_dependent_attribute_closure
+      # Recursively adds dependents of all referenced annotations.
+      def build_annotation_dependency_hierarchy
+        logger.debug { "Building annotation dependency hierarchy..." }
+        non_proxy_annotation_classes.each do |klass|
+          klass.annotation_hierarchy.each do |anc|
+            if anc.primary? and anc.proxy_attribute.nil? then
+              anc.define_proxy_attribute(self)
+            end
+          end
+          logger.info(klass.pp_s)
         end
+        set_inverses
+        add_dependent_attributes
+        add_dependent_attribute_closure
       end
       
       # Creates a reference attribute from this proxy to the given primary {Annotation} class. 
       #
       # @param [Class] klass the annotation class
-      # @param [Symbol] inverse the annotation => proxy attribute
-      def create_annotation_attribute(klass, inverse)
+      def create_annotation_attribute(klass)
         # the new attribute symbol
         attr = klass.name.demodulize.underscore.pluralize.to_sym
         logger.debug { "Creating annotation proxy #{qp} attribute #{attr} to hold primary annotation #{klass.qp} instances..." }
@@ -59,20 +63,34 @@ module CaTissue
         attr_create_on_demand_accessor(attr) { Set.new }
         # add the annotation collection attribute
         add_attribute(attr, klass, :collection)
-        # make the hook attribute which delegates to this proxy
-        @hook.create_annotation_attribute(domain_module, attr)
-        # set the attribute inverse
-        set_attribute_inverse(attr, inverse)
+        # The annotation is dependent.
+        add_dependent_attribute(attr, :logical)
         attr
       end
       
       private
+    
+      # Sets each annotation reference attribute inverse to the direct, unwrapped proxy
+      # reference named by the annotation module. E.g. the caTissue +Participant+
+      # +clinical+ proxy +ParticipantRecordEntry+ -> +NewDiagnosisAnnotation+ attribute
+      # inverse is set to the +NewDiagnosisAnnotation+ -> +ParticipantRecordEntry+
+      # +clinical+ reference attribute.
+      def set_inverses
+        # The inverse is the direct, unwrapped proxy reference named by the annotation module.
+        inv = annotation_module.name.demodulize.underscore.to_sym
+        # The attributes in class hierarchy general-to-specific order
+        attr_mds = annotation_attributes.enum_metadata.partial_sort_by { |attr_md| attr_md.type }.reverse
+        logger.debug { "Setting #{self} inverses for annotation attributes #{attr_mds.to_series}." }
+        attr_mds.each do |attr_md|
+          attr_md.type.define_proxy_attribute(self)
+          set_attribute_inverse(attr_md.to_sym, inv)
+        end
+      end
       
-      def infer_annotation_attributes
-        # Infer the domain attributes first. Do so with a copy of the attribute metadata objects
-        # since the domain type infereence can result in adding a new annotation attribute.
-        attribute_metadata_hash.values.each { |attr_md| attr_md.domain? }
-        domain_attributes.compose { |attr_md| attr_md.type < Annotation }
+      # @return <AnnotationClass> the non-proxy annotation classes
+      def non_proxy_annotation_classes
+        consts = annotation_module.constants.map { |s| annotation_module.const_get(s) }
+        consts.select { |c| Class === c and c < Annotation and not c < Proxy }
       end
     end
   end

data/lib/catissue/annotation/record_entry_proxy.rb

@@ -0,0 +1,20 @@
+require 'catissue/annotation/proxy'
+
+module CaTissue
+  module Annotation
+    # caTissue 1.2 {CaTissue::Resource} annotation hook proxy mix-in.
+    module RecordEntryProxy
+      include Proxy
+      
+      # @return [Annotatable] the annotated domain object  
+      def hook
+        send(self.class.owner_attribute_metadata.reader)
+      end
+      
+      # @param [Annotatable] obj the domain object to annotate  
+      def hook=(obj)
+        send(self.class.owner_attribute_metadata.writer, obj)
+      end
+    end
+  end
+end

data/lib/catissue/database.rb

@@ -17,11 +17,10 @@ module CaTissue
     # return [CaRuby::SQLExecutor] a utility SQL executor
     attr_reader :executor, :access_properties
 
-    # Creates a new Database with the {SERVICE_NAME} service and {CaTissue.access_properties}.
+    # Creates a new Database with the +catissuecore+ service and {CaTissue.access_properties}.
     def initialize
       @access_properties = CaTissue.access_properties
-      @access_properties[:database] ||= DEF_DATABASE_NAME
-      super(SERVICE_NAME, @access_properties)
+      super(SVC_NAME, @access_properties)
       @executor = CaRuby::SQLExecutor.new(@access_properties)
     end
 
@@ -37,16 +36,16 @@ module CaTissue
     # @param (see CaRuby::Database#persistence_service)
     # @return (see CaRuby::Database#persistence_service)
     def persistence_service(klass)
-      klass < Annotation ? klass.domain_module.persistence_service : super
+      klass < Annotation ? klass.annotation_module.persistence_service : super
     end
     
     # Augments {CaRuby::Database#ensure_exists} to ensure that an {Annotation::Proxy} reference identifier
     # reflects the hook identifier.
     #
-    # @param (see CaRuby::Database#ensure_exists)
-    def ensure_exists(ref)
-      if Annotation::Proxy === ref then
-        ref.ensure_identifier_reflects_hook
+    # @param (see CaRuby::Database::Writer#ensure_exists)
+    def ensure_exists(obj)
+      if Annotation::Proxy === obj then
+        obj.ensure_hook_exists
       end
       super
     end
@@ -54,10 +53,7 @@ module CaTissue
     private
 
     # The application service name
-    SERVICE_NAME = 'catissuecore'
-
-    # The default database name
-    DEF_DATABASE_NAME = 'catissue'
+    SVC_NAME = 'catissuecore'
     
     UPD_EID_SQL = 'update catissue_external_identifier set name = ?, value = ?, specimen_id = ? where identifier = ?'
     
@@ -103,13 +99,13 @@ module CaTissue
 
     # This method patches up fetched sources to correct the following anomaly:
     #
-    # caCORE alert - fetched references are not reconciled within an existing query result, e.g.
-    # given a query result with two Specimens s1 and s2, the parent reference is not fetched.
-    # Subsequently fetching the parent is independent of the query result. Thus if s1 is the parent
-    # of s2 in the database, the fetched s2 parent s3 is distinct from s1, even though
-    # s1.identifier == s3.identifier. Thus, enforcing reference consistency requires a post-fetch step
-    # that matches the fetched objects to the original query result on identifier and resets the
-    # references.
+    # @quirk caCORE fetched references are not reconciled within an existing query result, e.g.
+    #   given a query result with two Specimens s1 and s2, the parent reference is not fetched.
+    #   Subsequently fetching the parent is independent of the query result. Thus if s1 is the parent
+    #   of s2 in the database, the fetched s2 parent s3 is distinct from s1, even though
+    #   s1.identifier == s3.identifier. Thus, enforcing reference consistency requires a post-fetch step
+    #   that matches the fetched objects to the original query result on identifier and resets the
+    #   references.
     #
     # Not yet enabled. TODO - plug this into fetch_object.
     #
@@ -125,10 +121,9 @@ module CaTissue
       end
     end
 
-    # Work around the following caTissue bugs:
-    # * caTissue alert - Bug #135: Update SCG SpecimenEventParameters raises AuditException.
+    # @quirk caTissue Bug #135: Update SCG SpecimenEventParameters raises AuditException.
     #   Work around is to update the SCG instead.
-    # * caTissue alert - CPR consent tier response update results in Access denied error.
+    # @quirk caTissue CPR consent tier response update results in Access denied error.
     #   Work-around is to update the response using a direct SQL call.
     #
     # @param (see CaRuby::Database#update_object)
@@ -138,6 +133,8 @@ module CaTissue
         save_collectible_event_parameters(obj)
       elsif CaTissue::ConsentTierResponse === obj then
         update_consent_tier_response(obj)
+      elsif Annotation === obj then
+         raise CaRuby::DatabaseError.new("Annotation update is not supported on #{obj}")
       else
         case obj
           when CaTissue::Specimen then
@@ -154,8 +151,8 @@ module CaTissue
     
     # Updates the given dependent.
     #
-    # caTissue alert - 1.2 user address update results in authorization error. Work-around is to
-    # create a new address record.
+    # @quirk caTissue 1.2 user address update results in authorization error. Work-around is to
+    #   create a new address record.
     #
     # @param (see CaRuby::Writer#update_changed_dependent)
     def update_changed_dependent(owner, attribute, dependent, autogenerated)
@@ -197,44 +194,44 @@ module CaTissue
       
     # Augments {CaRuby::Database#save_with_template} to work around the following caTissue anomalies:
     #
-    # caTissue alert - Bug #149: API update TissueSpecimen position validation incorrect.
-    # The Specimen update argument must reference the old position, even though the position is not
-    # updatable, unless old status is Pending. The validation defect described in Bug #149 requires
-    # a work-around that is also used for a different reason described in the following paragraph.
-    #
-    # caTissue alert - Update of a {CaTissue::Specimen} which references a position must include the former
-    # position in the caTissue service update argument. A Specimen position is altered as a side-effect
-    # by creating a proxy save {CaTissue::TransferEventParameters}. The changed position is not reflected
-    # in the Specimen position, which must be refetched to reflect the database state. This fetch is
-    # done automatically by {CaRuby::Database} as part of the save proxy mechanism. The Specimen update
-    # template must include a reference to the former position but not the changed position.
-    #
-    # However, the Specimen {CaRuby::Writer#update} argument will include the changed position, not the
-    # former position. The template built {CaRuby::Writer#update} for submission to the caTissue app
-    # does not include a position reference, since the position has a save proxy which handles position
-    # change as part of the {CaRuby::Writer} update dependent propagation.
-    #
-    # Thus, updating a Specimen which includes a position change is performed as follows:
-    # * reconstitute the former position from the Position snapshot taken as part of the
-    #    {CaRuby::Persistable} change tracker.
-    # * add the former position to the template (which will now differ from the {CaRuby::Writer#update}
-    #   argument).
-    # * submit the adjusted Specimen template to the caTissue app updateObject.
-    # * {CaRuby::Writer#update} will propagate the Specimen update to the changed position dependent,
-    #   which in turn saves via the {CaTissue::TransferEventParameters} proxy.
-    # * The proxy save will in turn refetch the proxied Specimen position to obtain the identifier
-    #   and merge this into the Specimen position.
-    # * The Specimen update template is used solely to satisfy the often arcane caTissue interaction
-    #   requirements like this work-around, and is thrown away along with its aberrant state.
-    #
-    # This work-around is the only case of a save template modification to handle a caTissue special
-    # case. Note that the {CaTissue::SpecimenPosition} logic does not apply to a
-    # {CaTissue::ContainerPosition}, which can be updated directly.
-    #
-    # The additional complexity of this work-around is necessitated by the caTissue policy of update
-    # by indirect server-side side-effects that are not reflected back to the client. The caRuby
-    # policy of a declarative API that persists the save argument as given and reflects the
-    # changed database state requires this work-around.
+    # @quirk caTissue Bug #149: API update TissueSpecimen position validation incorrect.
+    #   The Specimen update argument must reference the old position, even though the position is not
+    #   updatable, unless old status is Pending. The validation defect described in Bug #149 requires
+    #   a work-around that is also used for a different reason described in the following paragraph.
+    #
+    # @quirk caTissue Update of a {CaTissue::Specimen} which references a position must include the former
+    #   position in the caTissue service update argument. A Specimen position is altered as a side-effect
+    #   by creating a proxy save {CaTissue::TransferEventParameters}. The changed position is not reflected
+    #   in the Specimen position, which must be refetched to reflect the database state. This fetch is
+    #   done automatically by {CaRuby::Database} as part of the save proxy mechanism. The Specimen update
+    #   template must include a reference to the former position but not the changed position.
+    #
+    #   However, the Specimen {CaRuby::Writer#update} argument will include the changed position, not the
+    #   former position. The template built {CaRuby::Writer#update} for submission to the caTissue app
+    #   does not include a position reference, since the position has a save proxy which handles position
+    #   change as part of the {CaRuby::Writer} update dependent propagation.
+    #
+    #   Thus, updating a Specimen which includes a position change is performed as follows:
+    #   * reconstitute the former position from the Position snapshot taken as part of the
+    #      {CaRuby::Persistable} change tracker.
+    #   * add the former position to the template (which will now differ from the {CaRuby::Writer#update}
+    #     argument).
+    #   * submit the adjusted Specimen template to the caTissue app updateObject.
+    #   * {CaRuby::Writer#update} will propagate the Specimen update to the changed position dependent,
+    #     which in turn saves via the {CaTissue::TransferEventParameters} proxy.
+    #   * The proxy save will in turn refetch the proxied Specimen position to obtain the identifier
+    #     and merge this into the Specimen position.
+    #   * The Specimen update template is used solely to satisfy the often arcane caTissue interaction
+    #     requirements like this work-around, and is thrown away along with its aberrant state.
+    #
+    #   This work-around is the only case of a save template modification to handle a caTissue special
+    #   case. Note that the {CaTissue::SpecimenPosition} logic does not apply to a
+    #   {CaTissue::ContainerPosition}, which can be updated directly.
+    #
+    #   The additional complexity of this work-around is necessitated by the caTissue policy of update
+    #   by indirect server-side side-effects that are not reflected back to the client. The caRuby
+    #   policy of a declarative API that persists the save argument as given and reflects the
+    #   changed database state requires this work-around.
     #
     # @param obj (see #store)
     # @param [Resource] template the obj template to submit to caCORE
@@ -294,18 +291,21 @@ module CaTissue
         logger.debug { "caTissue #{ctr} update work-around completed." }
     end
 
-    # Overrides {CaRuby::Database::Writer#save_dependents} to handle the work-around described
-    # in {#save_specimen_dependents}.
+    # Overrides {CaRuby::Database::Writer#save_changed_dependents} to handle the following anomalies:
+    # * create Specimen disposal event last, as described in {#save_changed_specimen_dependents}
     #
     # @param (see CaRuby::Writer#save_dependents)
-    def save_dependents(obj)
-      Specimen === obj ? save_specimen_dependents(obj) { super } : super
+    def save_changed_dependents(obj)
+      case obj
+        when Specimen then save_changed_specimen_dependents(obj) { super }
+        else super
+      end   
     end
     
-    # Overrides {CaRuby::Database::Writer#save_dependents} on a Specimen to correct the
+    # Overrides {CaRuby::Database::Writer#save_changed_dependents} on a Specimen to correct the
     # following problem:
     #
-    # caTissue alert - DisposalEventParameters must be created after all other Specimen SEPs.
+    # @quirk caTissue DisposalEventParameters must be created after all other Specimen SEPs.
     #
     # The process for migrating a discarded Specimen is as follows:
     # * Create the Specimen with status Active.
@@ -321,9 +321,9 @@ module CaTissue
     # for the subtle interaction required between these two work-arounds.
     #
     # @param [CaTissue::Specimen] the specimen whose dependents are to be saved
-    # @yield [dependent] calls the base {CaRuby::Writer#save_dependents} 
+    # @yield [dependent] calls the base {CaRuby::Writer#save_changed_dependents} 
     # @yieldparam [Resource] dependent the dependent to save
-    def save_specimen_dependents(specimen)
+    def save_changed_specimen_dependents(specimen)
       dsp = specimen.specimen_events.detect { |ep| CaTissue::DisposalEventParameters === ep }
       if dsp then
         logger.debug { "Work around caTissue #{specimen.qp} event parameters save order dependency by deferring #{dsp.qp} save..." }
@@ -350,7 +350,7 @@ module CaTissue
     # @return (see CaRuby::Database#build_save_template)
     def build_save_template(obj, builder)
       Annotation === obj ? prepare_annotation_for_save(obj) : super
-    end    
+    end
     
     # Ensures that a primary annotation hook exists.
     #
@@ -358,8 +358,10 @@ module CaTissue
     # @return [Annotation] the annotation object
     # @raise [DatabaseError] if the annotation does not reference a hook entity
     def prepare_annotation_for_save(annotation)
-      hook = annotation.owner
-      if hook.nil? then raise CaRuby::DatabaseError.new("Cannot save annotation #{annotation} since it does not reference a hook entity") end
+      hook = annotation.hook
+      if hook.nil? then
+        raise CaRuby::DatabaseError.new("Cannot save annotation #{annotation} since it does not reference a hook entity")
+      end
       if hook.identifier.nil? then
         logger.debug { "Ensuring that the annotation #{annotation.qp} hook entity #{hook.qp} exists in the database..." }
         ensure_exists(hook)
@@ -367,15 +369,16 @@ module CaTissue
       annotation
     end
 
-    # Overrides {CaRuby::Database::Writer#save_with_template} to work around the following
-    # caTissue bugs:
-    # * caTissue alert -  Bug #63: a SpecimenCollectionGroup update requires the referenced CollectionProtocolRegistration
+    # Overrides {CaRuby::Database::Writer#save_with_template} to work around caTissue bugs.
+    # @quirk caTissue  Bug #63: a SpecimenCollectionGroup update requires the referenced CollectionProtocolRegistration
     #   with an identifier to hold extraneous CollectionProtocolRegistration content, including the CPR
     #   collection protocol and PPI.
-    # * caTissue alert - Bug: CollectionProtocolRegistration must cascade throughCP, but the CP events
+    # @quirk caTissue Bug: CollectionProtocolRegistration must cascade throughCP, but the CP events
     #   cannot cascade to SpecimenRequirement without raising an Exception. Work-around is to clear the template CP events.
-    # * caTissue alert - Create Specimen with nil label does not auto-generate the label.
+    # @quirk caTissue Create Specimen with nil label does not auto-generate the label.
     #   Work-around is to set the label to a unique value.
+    #
+    # @raise DatabaseError if the object to save is an {Annotation::Proxy}, which is not supported
     def save_with_template(obj, template)
       # special cases to work around caTissue bugs
       if CaTissue::CollectionProtocolRegistration === obj  and template.collection_protocol then
@@ -450,10 +453,12 @@ module CaTissue
           if cep.nil? then raise CaRuby::DatabaseError.new("Default collection event parameters were not added to #{obj}.") end
           cep.copy.merge_attributes(:user => cep.user, :specimen_collection_group => template)
         end
-      elsif Annotation === obj and obj.class.secondary? then
+      elsif Annotation::Proxy === obj then
+        raise CaRuby::DatabaseError.new("Annotation proxy direct database save is not supported: #{obj}")
+      elsif Annotation === obj and obj.class.primary? then
         copy_annotation_proxy_owner_to_template(obj, template)
       end
-      
+
       # delegate to standard save
       super
     end
@@ -474,18 +479,19 @@ module CaTissue
       template.send(wtr, pxy)
     end
 
-    # Augment {CaRuby::Database::Writer#create_object} for the following work-arounds:
-    # * caTissue alert - Bug #124: SCG SpecimenEventParameters save fails validation.
+    # Augment {CaRuby::Database::Writer#create_object} to work around caTissue bugs.
+    # @quirk caTissue Bug #124: SCG SpecimenEventParameters save fails validation.
     #   Work-around is to create the SEP by updating the SCG.
-    # * If obj is a CaTissue::Specimen with the is_available flag set to false, then work around the bug
+    # @quirk If obj is a CaTissue::Specimen with the is_available flag set to false, then work around the bug
     #   described in {#create_unavailable_specimen}.
-    # * caTissue alert - Bug #161: Specimen API disposal not reflected in result activity status.
+    # @quirk caTissue Bug #161: Specimen API disposal not reflected in result activity status.
     #   DisposalEventParameters create sets the owner Specimen activity_status to +Closed+ as a side-effect.
     #   Reflect this side-effect in the submitted DisposalEventParameters owner Specimen object.
+    # Pass through an {Annotation::Proxy} to the referenced annotations.
     #
     # @param [Resource] obj the dependent domain object to save
     def create_object(obj)
-      if collectible_event_parameters?(obj) then
+     if collectible_event_parameters?(obj) then
         save_collectible_event_parameters(obj)
       elsif CaTissue::Specimen === obj then
         obj.add_defaults
@@ -507,10 +513,33 @@ module CaTissue
       
       obj
     end
-
+    
+    # Overrides {CaRuby::Database#create_from_template} as follows:
+    # * Surrogate {Annotation::Proxy} is "created" by setting the identifier to its hook owner.
+    #   The create operation then creates referenced uncreated dependents.
+    #
+    # @param (CaRuby::Database#create_from_template)
+    def create_from_template(obj)
+      if Annotation::Proxy === obj then
+        hook = obj.hook
+        if hook.identifier.nil? then
+          raise CaRuby::DatabaseError.new("Annotation proxy #{obj.qp} hook owner #{hook.qp} does not have an identifier")
+        end
+        obj.identifier = hook.identifier
+        obj.take_snapshot
+        logger.debug { "Marked annotation proxy #{obj} as created by setting the identifier to that of the hook owner #{hook}." }
+        logger.debug { "Creating annotation proxy #{obj} dependent primary annotations..." }
+        save_changed_dependents(obj)
+        persistify(obj)
+        obj
+      else
+        super
+      end
+    end
+    
     # Creates the given specimen by working around the following bug:
     #
-    # caTissue alert - Bug #160: Missing Is Available? validation.
+    # @quirk caTissue Bug #160: Missing Is Available? validation.
     # Cannot create a Specimen with any of the following conditions:
     # * zero available_quantity
     # * is_available flag set to false
@@ -567,6 +596,8 @@ module CaTissue
       specimen
     end
 
+    # Overrides {CaRuby::Database::Reader#fetch_object} to circumvent {Annotation} fetch, since an annotation
+    # does not have a key.
     def fetch_object(obj)
       super or fetch_alternative(obj)
     end
@@ -579,9 +610,9 @@ module CaTissue
     end
       
     # Override {CaRuby::Database#query_safe} to work around the following +caTissue+ bugs:
-    # * caTissue alert - Specimen auto-generates blank ExternalIdentifier.
-    #   cf. https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=19&t=436&sid=ef98f502fc0ab242781b7759a0eaff36
-    # * caTissue alert - Specimen auto-generates blank PMI. 
+    # * @quirk caTissue Specimen auto-generates blank ExternalIdentifier.
+    #     cf. https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=19&t=436&sid=ef98f502fc0ab242781b7759a0eaff36
+    # * @quirk caTissue Specimen auto-generates blank PMI. 
     def query_safe(obj_or_hql, *path)
       if path.last == :external_identifiers then
         CaTissue::Specimen.remove_empty_external_identifier(super)
@@ -592,19 +623,19 @@ module CaTissue
       end
     end
 
-    # caTissue alert - Bug #147: SpecimenRequirement query ignores CPE.
-    # Work around this bug by an inverted query on the referenced CPE.
+    # @quirk caTissue Bug #147: SpecimenRequirement query ignores CPE.
+    #   Work around this bug by an inverted query on the referenced CPE.
     #
-    # caTissue alert - Accessing an annotation hook DE proxy attribute uses a separate mechanism.
-    # Redirect the query to the annotation integration service in that case.
+    # @quirk caTissue Accessing an annotation hook DE proxy attribute uses a separate mechanism.
+    #   Redirect the query to the annotation integration service in that case.
     #
-    # caTissue alert - Bug #169: ContainerPosition occupied container query returns parent
-    # container instead. Substitute a hard-coded HQL search for this case.
+    # @quirk caTissue Bug #169: ContainerPosition occupied container query returns parent
+    #   container instead. Substitute a hard-coded HQL search for this case.
     #
     # @see CaRuby::Database#query_object
     def query_object(obj, attribute=nil)
       if hook_proxy_attribute?(obj, attribute) then
-        query_hook_proxy(obj, attribute)
+        query_hook_proxies(obj, attribute)
       elsif CaTissue::SpecimenRequirement === obj and not obj.identifier and obj.collection_protocol_event then
         query_requirement_using_cpe_inversion(obj, attribute)
       elsif CaTissue::ContainerPosition === obj and obj.identifier and attribute == :occupied_container then
@@ -621,34 +652,48 @@ module CaTissue
     end
     
     # @param (see #query_object)
-    # @return [Boolean] whether the given attribute is a reference from an {Annotatable} to a #{Annotation}
+    # @return [Boolean] whether the given attribute is a reference from an {Annotatable} to a #{Annotation::Proxy}
     def hook_proxy_attribute?(obj, attribute)
       return false if attribute.nil?
       attr_md = obj.class.attribute_metadata(attribute)
-      attr_md.declarer < Annotatable and attr_md.type < Annotation
+      attr_md.declarer < Annotatable and attr_md.type < Annotation::Proxy
     end
     
     # Queries on the given object attribute using the {Annotation::IntegationService}.
     #
-    # @param (see #query_object)
+    # @param [Annotatable] hook the annotated domain object
+    # @param [Symbol] attribute the proxy attribute
     # @result (see #query_object)
-    def query_hook_proxy(hook, attribute)
+    def query_hook_proxies(hook, attribute)
       unless hook.identifier then
         logger.debug { "Querying annotation hook #{hook.qp} proxy reference #{attribute} by collecting the matching #{hook.class.qp} proxy references..." }
-        return query(hook).map { |ref| query_hook_proxy(ref, attribute) }.flatten
+        return query(hook).map { |ref| query_hook_proxies(ref, attribute) }.flatten
       end
-      proxy = hook.annotation_proxy(attribute)
+      # the hook proxies
+      proxies = hook.send(attribute)
+      # catenate the query results for each proxy
+      proxies.each { |pxy| find_hook_proxy(pxy, hook) }
+      proxies
+    end    
+    
+    # Queries on the given proxy using the {Annotation::IntegationService}.
+    #
+    # @param [Annotation::Proxy] proxy the proxy object
+    # @param hook (see #query_hook_proxies)
+    # @param [Symbol] attribute the proxy attribute
+    # @result (see #query_object)
+    def find_hook_proxy(proxy, hook)
       # update the proxy identifier if necessary
       proxy.identifier ||= hook.identifier
       # delegate to the integration service to find the  referenced hook annotation proxies
-      logger.debug { "Delegating #{hook.qp} annotation #{attribute} query to proxy #{proxy} integration service query..." }
-      annotator.integrator.query(proxy, attribute)
+      logger.debug { "Delegating #{hook.qp} proxy #{proxy} query to the integration service..." }
+      annotator.integrator.find(proxy)
     end
     
-    # caCORE alert - Override {CaRuby::Database::Reader#invertible_query?} to enable the Bug #147 work
-    # around in {#query_object}. Invertible queries are performed to work around Bug #79. However, this
-    # work-around induces Bug #147, so we disable the Bug #79 work-around here for the special case of
-    # a CPE in order to enable the Bug #147 work-around. And so it goes....
+    # @quirk caCORE Override {CaRuby::Database::Reader#invertible_query?} to enable the Bug #147 work
+    #   around in {#query_object}. Invertible queries are performed to work around Bug #79. However, this
+    #   work-around induces Bug #147, so we disable the Bug #79 work-around here for the special case of
+    #   a CPE in order to enable the Bug #147 work-around. And so it goes....
     #
     # @see CaRuby::Database#invertible_query?
     def invertible_query?(obj, attribute)
@@ -673,9 +718,16 @@ module CaTissue
       pmi = pnt.medical_identifiers.first
       return if pmi.nil?
       logger.debug { "Using alternative Participant fetch strategy to find Participant by medical record number..." }
-      return unless exists?(pmi)
-      candidates = query(pmi.copy, :participant)
-      candidates.first if candidates.size == 1
+      # If the PMI has an identifier (unlikely) then find the PMI participant.
+      if pmi.identifier then return query(pmi.copy, :participant).first end
+      # Add the default site. If no default site, then bail.
+      if pmi.site.nil? then
+        pmi.add_defaults
+        return unless pmi.site
+      end
+      return unless exists?(pmi.site)
+      # Find the PMI based on the site and MRN.
+      return query(pmi.copy(:site, :medical_record_number), :participant).first
     end
 
     # @param [CaTissue::Specimen] spc the specimen to fetch