caruby-tissue 1.2.2 → 1.2.3

data/lib/catissue/database/annotation/entity_facade.rb

@@ -0,0 +1,265 @@
+require 'singleton'
+require 'caruby/import/java'
+require 'caruby/database/sql_executor'
+require 'catissue/database/annotation/id_generator'
+
+module CaTissue
+  module Annotation
+    # Import this EntityManager dependency before EntityManager.
+    java_import('edu.wustl.common.security.exceptions.UserNotAuthorizedException')
+    
+    # Import the caTissue Java EntityManager.
+    java_import('edu.common.dynamicextensions.entitymanager.EntityManager')
+   
+    # EntityFacade is the caRuby interface to the caTissue EntityManager. EntityManager is
+    # the caTissue singleton Winnebago object for doing lots of things with dynamic extensions.
+    class EntityFacade
+      include Singleton
+      
+      private
+      
+      # Initializes the caTissue EntityManager, an id generator and a SQL executor. The id
+      # generator and executor are used for the caTissue bug work-arounds described in the
+      # method docs and {IdGenerator}.
+      def initialize
+        # the encapsulated caTissue singleton
+        @emgr = EntityManager.instance
+        # the work-around id generator
+        @idgen = IdGenerator.new
+        # a general-purpose SQL executor for calling the work-arounds
+        @executor = CaRuby::SQLExecutor.new(CaTissue.access_properties)
+        # the primary entity class => entity id hash
+        @pr_eid_hash = {}
+      end
+      
+      public
+
+      # @param [Annotation] the annotation object
+      # @return [Integer] a new identifier for the given annotation object
+      def next_identifier(annotation)
+        # Commented line is broken - see IdGenerator doc.
+        # EntityManager.instance.getNextIdentifierForEntity(annotation.class.name.demodulize)
+        
+        # The entity table name, which will be a cryptic value like DE_E_1283.
+        eid = primary_entity_id(annotation.class)
+        aeid = common_ancestor_entity_id(eid)
+        tbl = annotation_table_for_entity_id(aeid)
+        next_identifier_for_table(tbl)
+      end
+      
+      # @param [String] the table name
+      # @return [Integer] the next identifier to use when creating a table record
+      def next_identifier_for_table(table)
+        # delegate to id generator
+        @idgen.next_identifier(table)
+      end
+      
+      # caTissue alert - unlike the hook entity id lookup, the annotation entity id lookup strips the leading
+      # package prefix from the annotation class name. caTissue DE API requires this undocumented inconsistency.
+      #
+      # caTissue alert - call into caTissue to get entity id doesn't work. caRuby uses direct SQL instead.
+      #
+      # @param [Class] klass the {Annotation} primary class
+      # @param [Boolean] validate flag indicating whether to raise an exception if the class is not primary
+      # @return [Integer] the caTissue entity id for the class
+      # @raise [AnnotationError] if the validate flag is set and the class is not primary
+      def primary_entity_id(klass, validate=true)
+        eid = @pr_eid_hash[klass] ||= recursive_primary_entity_id(klass)
+        if eid.nil? and validate then raise AnnotationError.new("Entity not found for annotation #{klass}") end
+        eid
+      end
+      
+      # @param [Class] klass the {Annotatable} class
+      # @return [Integer] the class entity id
+      def hook_entity_id(klass)
+        entity_id_for_class_designator(klass.java_class.name)
+      end
+      
+      # caTissue alert - call into caTissue to get entity id doesn't work for non-primary object.
+      # Furthermore, the SQL used for the #{#primary_entity_id} doesn't work for associated annotation
+      # classes. Use alternative SQL instead.
+      #
+      # @param [Integer] eid the referencing entity id
+      # @param [String] eid the association property name
+      # @return [Integer] the referenced {Annotation} class entity id
+      def associated_entity_id(eid, name)
+        # The caTissue role is capitalized.
+        role = name.capitalize_first
+        ref_eid = recursive_associated_entity_id(eid, role)
+        if ref_eid then
+          logger.debug { "Entity id #{eid} is associated with property #{name} via entity id #{ref_eid}." }
+        else
+          logger.debug { "Entity id #{eid} is not associated with property #{name}." }
+        end
+        ref_eid
+      end
+
+      # caTissue alert - Annotation classes are incorrectly mapped to entity ids, which in turn are
+      # incorrectly mapped to a table name. A candidate work-around is to bypass the caTissue DE
+      # mechanism and hit the DE Hibernate config files directly. However, the DE Hibernate mappings
+      # are incorrect and possibly no longer used. Therefore, the table must be obtained by SQL
+      # work-arounds.
+      #
+      # @param [Annotation] obj the annotation object
+      # @return [String] the entity table name
+      # @param [Integer] the annotation entity identifier
+      # @return [String] the entity table name
+      def annotation_table_for_entity_id(eid)
+        result = @executor.execute { |dbh| dbh.select_one(TABLE_NAME_SQL, eid) }
+        if result.nil? then raise AnnotationError.new("Table not found for annotation entity id #{eid}") end
+        tbl = result[0]
+        logger.debug { "Annotation entity with id #{eid} has table #{tbl}." }
+        tbl
+      end
+      
+      # @param (see #associated_entity_id)
+      # @return [Integer, nil] the parent entity id, if any
+      def parent_entity_id(eid)
+        result = @executor.execute { |dbh| dbh.select_one(PARENT_ENTITY_ID_SQL, eid) }
+        result[0] if result
+      end
+      
+      # Obtains the undocumented caTisue container id for the given primary entity id.
+      #
+      # caTissue alert - EntityManager.getContainerIdForEntitycontainer uses incorrect table
+      # (cf. https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=19&t=421&sid=5252d951301e598eebf3e90036da43cb).
+      # The standard DE API call submits the query:
+      #   SELECT IDENTIFIER FROM dyextn_container WHERE ENTITY_ID = ?
+      # This results in the error:
+      #   Unknown column 'ENTITY_ID' in 'where clause'
+      # The correct SQL is as follows:
+      #   SELECT IDENTIFIER FROM dyextn_container WHERE ABSTRACT_ENTITY_ID = ?
+      # The work-around is to call this SQL directly.
+      # 
+      # @return [Integer] eid the primary entity id
+      # @raise [AnnotationError] if no container id is found
+      def container_id(eid)
+        # The following call is broken (see method doc).
+        # EntityManager.instance.get_container_id_for_entity(eid)
+        # Work-around caTissue bug with direct query.
+        result = @executor.execute { |dbh| dbh.select_one(CTR_ID_SQL, eid) }
+        cid = result[0].to_i if result
+        if cid.nil? then
+          raise AnnotationError.new("Dynamic extension container id not found for annotation #{annotation} with entity id #{eid}")
+        end
+        logger.debug { "Annotation with entity id #{eid} has container id #{cid}." }
+        cid
+      end
+      
+      private
+      
+      # @param (see #primary_entity_id)
+      # @return (see #primary_entity_id)
+      def recursive_primary_entity_id(klass)
+        eid = nonrecursive_primary_entity_id(klass) || parent_primary_entity_id(klass)
+        if eid then logger.debug { "#{klass.qp} has entity id #{eid}." } end
+        eid
+      end
+      
+      # @param (see #primary_entity_id)
+      # @return (see #primary_entity_id)
+      def nonrecursive_primary_entity_id(klass)
+        # The Java class package is the entity group, the Java class unqualified name is the caption.
+        pkg, cls_nm = klass.java_class.name.split('.')
+        # Dive into some obscure SQL
+        result = @executor.execute { |dbh| dbh.select_one(CTR_ENTITY_ID_SQL, pkg, cls_nm) }
+        result[0] if result
+      end
+      
+      # @param (see #primary_entity_id)
+      # @return (see #primary_entity_id)
+      def parent_primary_entity_id(klass)
+        nonrecursive_primary_entity_id(klass.superclass) if klass.superclass < Annotation
+      end
+      
+      # @param [Integer] the starting entity id
+      # @return [Integer] the top-most ancestor entity id
+      def common_ancestor_entity_id(eid)
+        peid = parent_entity_id(eid)
+        peid ? common_ancestor_entity_id(peid) : eid
+      end
+      
+      # @param eid (see #associated_entity_id)
+      # @param role the property role name
+      # @return [Integer, nil] the associated entity id, if any
+      def recursive_associated_entity_id(eid, role)
+        nonrecursive_associated_entity_id(eid, role) or parent_associated_entity_id(eid, role)
+      end
+      
+      # @param (see #recursive_associated_entity_id)
+      # @return [Integer, nil] the associated entity id in the context of the parent, if any
+      def parent_associated_entity_id(eid, role)
+        peid = parent_entity_id(eid) || return
+        logger.debug { "Finding  entity id #{eid} #{role} associated entity id using parent entity id #{peid}..." }
+        recursive_associated_entity_id(peid, role)
+      end
+      
+      # @param (see #recursive_associated_entity_id)
+      # @return @return [Integer, nil] the directly associated entity id, if any
+      def nonrecursive_associated_entity_id(eid, role)
+        logger.debug { "Finding entity id #{eid} #{role} associated entity id..." }
+        result = @executor.execute { |dbh| dbh.select_one(ASSN_ENTITY_ID_SQL, eid, role) }
+        # The role role can be a mutation of the property name with spaces inserted in the
+        # camel-case components, e.g. 'Additional Finding' instead of 'AdditionalFinding'.
+        # TODO - fix this kludge by finding out how the role relates to the property in the
+        # database.
+        if result.nil? and role =~ /.+[A-Z]/ then
+          alt = role.gsub(/(.)([A-Z])/, '\1 \2')
+          logger.debug { "Attempting to find  entity id #{eid} #{role} associated entity id using variant #{alt}..." }
+          result = @executor.execute { |dbh| dbh.select_one(ASSN_ENTITY_ID_SQL, eid, alt) }
+        end
+        if result.nil? and role =~ /[pP]athologic[^a]/ then
+          alt = role.sub(/([pP])athologic/, '\1athological')
+          logger.debug { "Attempting to find  entity id #{eid} #{role} associated entity id using variant #{alt}..." }
+          result = @executor.execute { |dbh| dbh.select_one(ASSN_ENTITY_ID_SQL, eid, alt) }
+        end
+        if result.nil? then
+          logger.debug { "Entity id #{eid} is not directly associated with #{role}." }
+        end
+        result[0] if result
+      end
+      
+      # @param [String] designator the class name, demodulized in the case of an annotation entity
+      # @return [Integer] the caTissue entity id for the given class name
+      # @raise [CaRuby::DatabaseError] if the DE entity id is not found for the given designator
+      def entity_id_for_class_designator(designator)
+        @emgr.getEntityId(designator) or
+          raise CaRuby::DatabaseError.new("Dynamic extension entity id not found for #{designator}")
+      end
+      
+      # The SQL to find an entity id for a primary entity.
+      CTR_ENTITY_ID_SQL = <<EOS
+      select ctr.ABSTRACT_ENTITY_ID
+      from DYEXTN_CONTAINER ctr, DYEXTN_ENTITY_GROUP grp
+      where ctr.ENTITY_GROUP_ID = grp.IDENTIFIER
+      and grp.SHORT_NAME = ?
+      and ctr.CAPTION = ?
+EOS
+
+      # The SQL to find an entity id for a secondary annotation referenced by a primary annotation.
+      ASSN_ENTITY_ID_SQL = <<EOS
+      select assn.TARGET_ENTITY_ID
+      from DYEXTN_ATTRIBUTE attr, DYEXTN_ABSTRACT_ENTITY ae, DYEXTN_ASSOCIATION assn, DYEXTN_ROLE role
+      where assn.IDENTIFIER = attr.IDENTIFIER
+      and attr.ENTIY_ID = ae.id
+      and assn.TARGET_ROLE_ID = role.IDENTIFIER
+      and ae.id = ?
+      and role.name = ?
+EOS
+
+      # The SQL to find a parent entity id for a given entity id.
+      PARENT_ENTITY_ID_SQL = 'select e.parent_entity_id from DYEXTN_ENTITY e where e.identifier = ?'
+
+      # The SQL to find the database table for an entity id.
+      TABLE_NAME_SQL = <<EOS
+        select dp.name
+        from dyextn_database_properties dp, dyextn_table_properties tp
+        where dp.identifier = tp.identifier
+        and tp.abstract_entity_id = ?
+EOS
+      
+      # The caTissue DE API container id bug work-around query
+      CTR_ID_SQL = "select identifier from dyextn_container where abstract_entity_id = ?"
+    end
+  end
+end

data/lib/catissue/database/annotation/id_generator.rb

@@ -0,0 +1,62 @@
+require 'caruby/database/sql_executor'
+
+module CaTissue
+  module Annotation
+    # The IdGenerator delegates to the caTissue entity manager to create a new identifier for an annotation.
+    class IdGenerator
+      def initialize
+        @executor = CaRuby::SQLExecutor.new(CaTissue.access_properties)
+      end
+
+      # caTissue alert - DE API subquery search fails.
+      # EntityManager.getNextIdentifierForEntity(EntityManager.java:2689) returns zero for some, but not all, DEs.
+      # This is a cascading error that is difficult to trace. The EntityManager.getNextIdentifierForEntity error
+      # is printed to the console rather than propagated up the call stack. A subsequent create then fails because
+      # the identifier is not set.
+      #
+      # A candidate work-around is to resolve the DE table name by issuing a direct SQL call and pass this
+      # to DE API EntityManagerUtil.getNextIdentifier. However, EntityManagerUtil is broken as well, for a
+      # different reason.
+      #
+      # Another candidate work-around is to get the next id manually from the caTissue DYEXTN_ID_GENERATOR table.
+      # However, this table is suspect since it is not defined as a database sequence generator and is not
+      # referenced in the caTissue source code. It is not used by the caTissue GUI when creating an annotation.
+      # 
+      # The work-around to the work-around to the work-around is to call the following SQL directly:
+      #   select max(identifier) from <table>
+      # where \<table\> is the result of the EntityManager work-around query. The EntityManager work-around query
+      # is described in
+      # https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=19&t=404&p=2785&sid=febe0a1271b3d00020927741a94e9bff#p2785.
+      #
+      # Unfortunately, the +select max+ work-around is hampered by the obvious concurrent access race condition.
+      # For an unknown reason, caTissue DE does not use database sequence generators to make DE identifiers.
+      # Even if the caTissue DE API worked, it might suffer from the same race condition. The DE API
+      # EntityManagerUtil caches identifiers. The API call is synchronized, but it is unclear whether each DE
+      # client accesses the same EntityManagerUtil instance as the GUI DE action processor. If not, then the
+      # caTissue DE API, assuming that it were functional, would be open to an even more serious concurrency
+      # conflict than the work-around race condition.
+      #
+      # @param [String] the entity table
+      # @return [Integer] a new identifier for the given annotation object
+      def next_identifier(table)
+        # Commented line is broken - see method doc.
+        # The caTissue EntityManagerUtil hands out table record ids in the work-around.
+        #identifier = EntityManagerUtil.getNextIdentifier(table)
+        
+        logger.debug { "Work around caTissue DE EntityManagerUtil bug by fetching the maximum #{table} identifier directly from the database..." }
+        sql = TABLE_MAX_ID_SQL_TMPL % table
+        result = @executor.execute { |dbh| dbh.select_one(sql) }
+        max = result ? result[0].to_i : 0
+        identifier = max + 1
+        # End of work-around
+        
+        logger.debug { "Next #{table} identifier is #{identifier}." }
+        identifier
+      end
+      
+      private
+      
+      TABLE_MAX_ID_SQL_TMPL = "select max(identifier) from %s"
+    end
+  end
+end

data/lib/catissue/database/annotation/integration_service.rb

@@ -2,85 +2,131 @@ require 'caruby/database/persistence_service'
 
 module CaTissue
   module Annotation
-    # An IntegrationService fetches and saves CaTissue anchor-annotation associations.
+    # An IntegrationService fetches and saves CaTissue hook-annotation associations.
     class IntegrationService < CaRuby::PersistenceService
       SERVICE_NAME = 'deintegration'
 
       java_import('deintegration.EntityMap')
+      
       java_import('deintegration.EntityMapRecord')
+      
+      java_import('deintegration.FormContext')
 
-      def initialize(entity_manager)
+      # @param [EntityFacade] the global entity manager
+      def initialize
         super(SERVICE_NAME)
-        @entity_manager = entity_manager
+        # SQL executor to handle caTissue DE API bug work-around 
+        @executor = CaRuby::SQLExecutor.new(CaTissue.access_properties)
       end
 
-      # Associates the given anchor domain object to annotation.
-      def associate(anchor, annotation)
-        logger.debug { "Associating annotation #{annotation} to owner #{anchor}..." }
-        association = create_entity_map_record(anchor, annotation)
-        create(association)
+      # Associates the given hook domain object to the annotation.
+      #
+      # @param [Annotatable] hook the hook entity 
+      # @param [Annotation] annotation the annotation entity 
+      def associate(hook, annotation)
+        logger.debug { "Associating annotation #{annotation} to owner #{hook}..." }
+        emr = create_entity_map_record(hook, annotation)
+        create(emr)
       end
 
-      # Removes the existing association between the given anchor domain object to annotation.
-      def dissociate(anchor, annotation)
-        association = create_entity_map_record(anchor, annotation)
-        delete(association)
-      end
+#      # Removes the existing association between the given hook domain object to annotation.
+#      #
+#      # @param (see #associate)
+#      def dissociate(hook, annotation)
+#        assn = find_entity_map_record(hook, annotation) # TODO - implement
+#        delete(assn)
+#      end
 
       private
 
-      # Flag to work around caTissue and JRuby bugs
-      ENTITY_MAP_BUG = true
-
-      ## The cruft below is adapted from caTissue ClientDemo_SCG.java and cleaned up (but still obscure). ##
-
-      def create_entity_map_record(anchor, annotation)
-        record = EntityMapRecord.new
-        raise CaRuby::DatabaseError.new("Annotation entity map static entity does not have an identifier: #{anchor}") if anchor.identifier.nil?
-        record.static_entity_record_id = anchor.identifier
-        raise CaRuby::DatabaseError.new("Annotation entity map dynamic entity does not have an identifier: #{annotation}") if annotation.identifier.nil?
-        record.dynamic_entity_record_id = annotation.identifier
-        record.form_context = form_context(anchor, annotation)
-        record.form_context_id = record.form_context.identifier if record.form_context
-        record
-      end
-
-      # Returns the undocumented caTissue FormContext, which might be another bit of caTissue presentation
-      # flotsam polluting the data layer.
-      def form_context(anchor, annotation)
-        map = EntityMap.new
-        map.static_entity_id = anchor_entity_id(anchor)
-        return if ENTITY_MAP_BUG
-        # 2 bugs:
-        # * caTissue bug - bad container id query, cf. https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=19&t=421&sid=5252d951301e598eebf3e90036da43cb
-        # * jRuby bug? - query on map call to map.pp_s wipes out the map java_class! Can't step into pp_s with debugger so can't isolate cause without more work
-        # TODO - isolate and file both bugs
-        #map.container_id = entity_container_id(annotation)
-        map.form_context_collection.first if query(map)
-      end
+      #### The cruft below is adapted from caTissue ClientDemo_SCG.java and cleaned up (but still obscure). ####
 
-      def entity_container_id(annotation)
-        entity_id = annotation_entity_id(annotation)
-        container_id = @entity_manager.get_container_id_for_entity(entity_id)
-        raise CaRuby::DatabaseError.new("Dynamic extension container id not found for annotation #{annotation}") if container_id.nil?
-        logger.debug { "Dynamic extension container id for #{annotation}: #{container_id}" } and container_id
+      # Creates an entity map record with content (annotation entity id, annotation id, form context id).
+      # This record associates the static hook record to the annotation record qualified by the context.
+      #
+      # @param (see #associate)
+      # @return [EntityMapRecord] the new entity map record
+      def create_entity_map_record(hook, annotation)
+        # the entity map record with content (annotation entity id, annotation id, context id)
+        emr = EntityMapRecord.new
+        
+        # the hook id
+        if hook.identifier.nil? then
+          raise CaRuby::DatabaseError.new("Annotation entity map static entity does not have an identifier: #{hook}")
+        end
+        emr.static_entity_record_id = hook.identifier
+        
+        # the annotation id
+        if annotation.identifier.nil? then
+          raise CaRuby::DatabaseError.new("Annotation entity map dynamic entity does not have an identifier: #{annotation}")
+        end
+        emr.dynamic_entity_record_id = annotation.identifier
+        
+        # the form context
+        ctxt = form_context(hook, annotation)
+        if ctxt then
+          emr.form_context = ctxt
+          emr.form_context_id = ctxt.id
+        end
+        
+        emr
       end
 
-      # Returns the undocumented caTissue entity id for the given anchor entity's Java class name.
-      def anchor_entity_id(anchor)
-        entity_id_for_class_designator(anchor.class.java_class.name)
+      # @param (see #associate) 
+      # @return [FormContent] an undocumented bit of caTissue presentation flotsam polluting the data layer
+      def form_context(hook, annotation)
+        map = entity_map(hook, annotation)
+        
+        # the fetched form context
+        ctxts = map.form_context_collection
+        if ctxts.empty? then
+          logger.debug { "#{hook} entity map #{map.qp} does not have a form context." }
+        elsif ctxts.size > 1 then
+          ctxt_ids = ctxts.map { |ctxt| ctxt.id }
+          raise CaRuby::DatabaseError.new("More than one form context for #{hook} - form context ids: #{ctxt_ids.qp}")
+        else
+          ctxt = ctxts.first
+          logger.debug { "#{hook} has form context id #{ctxt.id}." }
+        end
+        
+        ctxt
       end
-
-      # Returns the undocumented caTissue entity id for the given annotation entity's demodulized Java class name.
+      
+      # caTissue alert - the entity map is associated with a domain class in the hook class hierarchy.
+      # The generic approach to determining the entity map for a given hook object and annotation object
+      # is to iterate over the hook class hierarchy until a matching ENTITY_MAP record is found for the
+      # hook class ancestor and the annotation container id.
       #
-      # caTissue alert - unlike #anchor_entity_id, {#annotation_entity_id} strips the leading package prefix from the annotation
-      # class name. caTissue DE API requires this undocumented inconsistency.
-      def annotation_entity_id(annotation)
-        entity_id_for_class_designator(annotation.class.java_class.name[/[^.]+$/])
+      # @param (see #associate) 
+      # @return [EntityMap] the entity map
+      def entity_map(hook, annotation)
+        klass = hook.class
+        while klass < CaTissue::AbstractDomainObject
+          map = entity_map_for_class(klass, annotation)
+          return map if map
+          klass = klass.superclass
+        end
+        nil
       end
-
-      def entity_id_for_class_designator(designator)
-        @entity_manager.get_entity_id(designator) or raise CaRuby::DatabaseError.new("Dynamic extension entity id not found for #{designator}")
+      
+      # @param [Class] klass the hook class
+      # @param annotation (see #entity_map) 
+      # @return (see #entity_map)
+      def entity_map_for_class(klass, annotation)
+        # A query template
+        tmpl = EntityMap.new
+        tmpl.static_entity_id = klass.effective_entity_id
+        # the container id
+        tmpl.container_id = annotation.class.container_id
+        # the database record matching the template
+        logger.debug { "Fetching the ENTITY_MAP record for #{klass.qp} entity id #{tmpl.static_entity_id} and container id #{tmpl.container_id}..." }
+        map = query(tmpl).first
+        if map then
+          logger.debug { "Entity map found for #{klass.qp} entity id #{tmpl.static_entity_id}, container id #{tmpl.container_id}: #{map.qp}." }
+        else
+          logger.debug { "ENTITY_MAP record not found for #{klass.qp} entity id #{tmpl.static_entity_id}, container id #{tmpl.container_id}." }
+        end
+        map
       end
     end
   end

data/lib/catissue/database/annotation/reference_writer.rb

@@ -0,0 +1,150 @@
+module CaTissue
+  module Annotation
+    # A ReferenceWriter saves annotations to the database. This is a helper class to work around
+    # caTissue DE API defects. This class infers a direct data mapping by navigating the caTissue
+    # DYEXT tables of the introspected Java annotation class properties.
+    class ReferenceWriter
+      # @param [Integer] eid the referencing annotation entity id
+      # @param [CaRuby::AttributeMetadata] attr_md the annotation attribute metadata of the attribute to save
+      # @param [Integer, nil] assn_eid the referenced annotation entity id
+      def initialize(eid, attr_md, assn_eid=nil)
+        logger.debug { "Mapping annotation #{attr_md.declarer.qp}.#{attr_md} role attributes to database columns..." }
+        efcd = EntityFacade.instance
+        # the referenced annotation entity id
+        assn_eid ||= associated_entity_id(eid, attr_md)
+        # the referenced entity database table
+        @table = efcd.annotation_table_for_entity_id(assn_eid)
+        # map the attribute => column
+        attr_col_hash = map_attributes(attr_md.type, assn_eid)
+        logger.debug { "Annotation #{attr_md.declarer.qp} #{attr_md} maps to #{@table} as #{attr_col_hash.qp}" }
+        # the mapped attributes and columns
+        @attrs, cols = attr_col_hash.to_a.transpose
+        # the SQL parameters clause
+        params = Array.new(cols.size, '?').join(', ')
+        # the create SQL
+        @cr_sql = CREATE_SQL % [@table, cols.join(', '), params]
+        # the update SQL
+        @upd_sql = UPDATE_SQL % [@table, cols.map { |col| "#{col} = ?" }.join(', ')]
+        # the superclass writer for annotations with superclass DE forms
+        @parent = obtain_parent_writer(eid, attr_md)
+      end
+      
+      # @param [Annotation] annotation the referenced annotation value
+      def save(annotation)
+        # select the SQL based on whether this is an update or a create
+        sql = annotation.identifier ? @upd_sql : @cr_sql
+        # allocate a new database identifier
+        annotation.identifier ||= next_identifier
+        # the values to bind to the SQL parameters
+        values = database_parameters(annotation)
+        logger.debug { "Saving #{annotation} to #{@table}..." }
+        # dispatch the SQL update or create statement
+        CaTissue::Database.instance.executor.execute do |dbh|
+          dbh.prepare(sql) { |sth| sth.execute(*values) }
+        end
+        if @parent then
+          logger.debug { "Saving #{annotation} parent entity attributes..." }
+          @parent.save(annotation)
+        end
+      end
+      
+      protected
+      
+      # @return [Integer] the identifier to use when creating a new annotation instance
+      def next_identifier
+        @parent ? @parent.next_identifier : EntityFacade.instance.next_identifier_for_table(@table)
+      end
+      
+      private
+      
+      # @param (see #initialize)
+      # @return [Integer] the entity id for the given attribute role
+      # @raise [AnnotationError] if the associated entity was not found
+      def associated_entity_id(eid, attr_md)
+        EntityFacade.instance.associated_entity_id(eid, attr_md.property_descriptor.name) or
+          raise AnnotationError.new("Associated entity not found for entity #{eid} attribute #{attr_md}")
+      end      
+      
+      # @param (see #initialize)
+      # @return [Integer, nil] the superclass associated entity id for the given attribute role, or nil if none
+      def obtain_parent_writer(eid, attr_md)
+        # the superclass entity id for annotations with superclass DE forms
+        peid = EntityFacade.instance.parent_entity_id(eid) || return
+        # the associated entity id
+        aeid = EntityFacade.instance.associated_entity_id(peid, attr_md.property_descriptor.name)
+        ReferenceWriter.new(peid, attr_md, aeid) if aeid
+      end
+      
+      # @param annotation (see #save)
+      # @return [Array] the save SQL call parameters 
+      def database_parameters(annotation)
+        @attrs.map do |attr|
+          value = annotation.send(attr)
+          Annotation === value ? value.identifier : value
+        end
+      end
+      
+      def map_attributes(klass, eid)
+        # the non-domain columns
+        hash = klass.nondomain_attributes.to_compact_hash do |attr|
+          nondomain_attribute_column(klass, attr, eid)
+        end
+        # the owner attribute column
+        ownr_attr = klass.owner_attribute
+        if ownr_attr then hash[ownr_attr] = owner_attribute_column(klass, ownr_attr, eid) end
+        hash
+      end
+      
+      def nondomain_attribute_column(klass, attribute, eid)
+        if attribute == :identifier then return IDENTIFIER_COL end
+        attr_md = klass.attribute_metadata(attribute)
+        # skip an attribute declared by the superclass
+        return unless attr_md.declarer == klass
+        xctr = CaTissue::Database.instance.executor
+        prop = attr_md.property_descriptor.name
+        logger.debug { "Finding #{klass.qp} #{attribute} column for entity id #{eid} and property #{prop}..." }
+        result = xctr.execute { |dbh| dbh.select_one(NONDOMAIN_COLUMN_SQL, prop, eid) }
+        col = result[0] if result
+        if col.nil? then raise AnnotationError.new("Column not found for #{klass.qp} #{attribute}") end
+        col
+      end
+      
+      def owner_attribute_column(klass, attribute, eid)
+        logger.debug { "Finding #{klass.qp} #{attribute} column in the context of entity id #{eid}..." }
+        result = CaTissue::Database.instance.executor.execute { |dbh| dbh.select_one(OWNER_COLUMN_SQL, eid) }
+        col = result[0] if result
+        if col.nil? then raise AnnotationError.new("Column not found for #{klass.qp} owner attribute #{attribute}") end
+        col
+      end
+      
+      IDENTIFIER_COL = 'IDENTIFIER'
+      
+      # Generic update template.
+      UPDATE_SQL = "update %s set ACTIVITY_STATUS = 'Active', %s"
+      
+      # Generic create template.
+      CREATE_SQL = "insert into %s(ACTIVITY_STATUS, %s)\nvalues ('Active', %s)"
+      
+      # SQL to get the primitive column name for a given annotation class entity id and Java property name
+      NONDOMAIN_COLUMN_SQL = <<EOS
+        select dbp.name
+        from DYEXTN_ABSTRACT_METADATA amd, DYEXTN_CONTROL ctl, DYEXTN_CONTAINER ctr, DYEXTN_DATABASE_PROPERTIES dbp, DYEXTN_COLUMN_PROPERTIES cp
+        where amd.NAME = ?
+        and ctl.CONTAINER_ID = ctr.IDENTIFIER
+        and amd.IDENTIFIER = ctl.BASE_ABST_ATR_ID
+        and ctl.BASE_ABST_ATR_ID = cp.PRIMITIVE_ATTRIBUTE_ID
+        and dbp.IDENTIFIER = cp.IDENTIFIER
+        and ctr.ABSTRACT_ENTITY_ID = ?
+EOS
+      
+      # SQL to get the annotation reference column name for a given annotation target entity id.
+      # The target entity id is obtained by calling {EntityFacade#associated_entity_id}.
+      OWNER_COLUMN_SQL = <<EOS
+        select cst.TARGET_ENTITY_KEY
+        from DYEXTN_CONSTRAINT_PROPERTIES cst, DYEXTN_ASSOCIATION assn
+        where cst.ASSOCIATION_ID = assn.IDENTIFIER
+        and assn.TARGET_ENTITY_ID = ?
+EOS
+    end
+  end
+end