caruby-tissue 1.4.2 → 1.5.1

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

@@ -43,11 +43,11 @@ module CaTissue
 
       # @param [Annotation] (see #create)
       def create_annotation(annotation)
-         # get the hook
+        # get the hook
         hook = annotation.hook
         # If no hook, then this is not a primary annotation. In that case, find a referenced
         # primary annotation.
-       # If no hook, then this is not a primary annotation. In that case, find a referenced
+        # If no hook, then this is not a primary annotation. In that case, find a referenced
         # primary annotation.
         if hook then
           create_primary_annotation(annotation, hook)
@@ -92,9 +92,9 @@ module CaTissue
         end
         # The next database identifier.
         annotation.identifier = EntityFacade.instance.next_identifier(annotation)
-        # Ensure that the proxy record is up-to-date.
-        annotation.ensure_proxy_reflects_hook
-        
+        # Ensure that there is a proxy hook.
+        pxy = annotation.proxy
+        if pxy then pxy.ensure_hook_exists end
         # Delegate to standard record create.
         app_service.create_object(annotation)
         logger.debug { "Created annotation object #{annotation}." }

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

@@ -18,8 +18,8 @@ module CaTissue
     # @param [String] name the service name
     # @return [Annotation::AnnotationService] the annotation service
     def create_annotation_service(mod, name)
-      intgr = Annotation::Integrator.new(mod)
-      Annotation::AnnotationService.new(@database, name, intgr)
+      @integrator = Annotation::Integrator.new(mod)
+      Annotation::AnnotationService.new(@database, name, @integrator)
     end
   end
 end

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

@@ -38,10 +38,10 @@ module CaTissue
         @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.
+      # @quirk caTissue 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.
+      # @quirk caTissue 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
@@ -70,9 +70,9 @@ module CaTissue
         eid
       end
       
-      # caTissue alert - call into caTissue to get entity id doesn't work for non-primary object.
-      # Furthermore, the SQL used for the #{#annotation_entity_id} doesn't work for associated annotation
-      # classes. Use alternative SQL instead.
+      # @quirk caTissue call into caTissue to get entity id doesn't work for non-primary object.
+      #   Furthermore, the SQL used for the #{#annotation_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
@@ -89,11 +89,11 @@ module CaTissue
         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.
+      # @quirk caTissue 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
@@ -116,17 +116,17 @@ module CaTissue
       
       # 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.
+      # @quirk caTissue 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.
       #
-      # caTissue alert - in 1.2, there are deprecated primary annotations with an entity id but no container id.
+      # @quirk caTissue in 1.2, there are deprecated primary annotations with an entity id but no container id.
       # 
       # @return [Integer] eid the primary entity id
       def container_id(eid)
@@ -170,8 +170,11 @@ module CaTissue
       # @param (see #nonrecursive_annotation_entity_id)
       # @return [(String, String)] the entity group name and the entity name 
       def split_annotation_entity_class_name(klass)
+        # the Java class full name
         jname = klass.java_class.name
+        # the Java package and base class name
         pkg, base = Java.split_class_name(jname)
+        # A wustl domain class is in the core group.
         if pkg =~ CORE_PKG_REGEX then
           [CORE_GROUP, jname]
         elsif pkg.nil? or pkg['.'] then

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

@@ -8,33 +8,33 @@ module CaTissue
         @executor = CaTissue::Database.instance.executor
       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.
+      # @quirk caTissue 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.
+      #   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.
+      #   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.
+      #   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.
+      #   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
@@ -47,11 +47,11 @@ module CaTissue
         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
+        next_id = max + 1
         # End of work-around
         
-        logger.debug { "Next #{table} identifier is #{identifier}." }
-        identifier
+        logger.debug { "Next #{table} identifier is #{next_id}." }
+        next_id
       end
       
       private

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

@@ -4,15 +4,13 @@ module CaTissue
   module Annotation
     # An IntegrationService fetches and saves CaTissue 1.1.x hook-annotation associations.
     class IntegrationService < CaRuby::PersistenceService
-      SERVICE_NAME = 'deintegration'
-
-      # The caTissue 
+      # Import the caTissue classes.
       java_import Java::deintegration.EntityMap
       java_import Java::deintegration.EntityMapRecord
       java_import Java::deintegration.FormContext
 
       def initialize
-        super(SERVICE_NAME, CaTissue::Database.instance.access_properties)
+        super(SVC_NAME, CaTissue::Database.instance.access_properties)
       end
 
       # Associates the given hook domain object to the annotation.
@@ -29,6 +27,8 @@ module CaTissue
       end
 
       private
+      
+      SVC_NAME = 'deintegration'
 
       #### The cruft below is adapted from caTissue 1.1.2 ClientDemo_SCG.java and cleaned up (but still obscure). ####
 
@@ -73,10 +73,10 @@ module CaTissue
         ctxt
       end
       
-      # 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.
+      # @quirk caTissue 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.
       #
       # @param (see #associate) 
       # @return [EntityMap] the entity map

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

@@ -12,6 +12,13 @@ module CaTissue
 
       # Associates the given hook domain object to the annotation.
       #
+      # @quirk caTissue The static hook entity is associated with the annotation
+      #   by creating a record entry hook proxy. Even though the record entry class
+      #   includes Java properties for each primary annotation in the annotation
+      #   Java package, the record entry instance only references a single annotation.
+      #   The record entry database table +dyextn_abstract_record_entry+ has foreign
+      #   key to a ABSTRACT_FORM_CONTEXT_ID  a separate record entry is created for each annotation.
+      #
       # @param [Annotatable] hook the hook entity 
       # @param [Annotation] annotation the annotation entity 
       def associate(hook, annotation)
@@ -25,12 +32,17 @@ module CaTissue
       # @return [Object] yet another association record which associates the hook to the
       #   annotation in the {REC_ENTRY_PKG}
       def create_record_entry(hook, annotation)
-        # the record entry object
-        re = @mod.record_entry_class.new
-        # the activity status must be set for the DE to show up
-        re.activity_status = 'Active'
+        # the DE integration record entry class
+        klass = hook.class.de_integration_proxy_class
+        if klass.nil? then
+          # Should not be nil by construction, but doesn't hurt to check.
+          raise AnnotationError.new("Cannot create a #{hook} annotation record entry, since #{hook.class.qp} does not have a DE Integration proxy class")
+        end
+        # the DE integration record entry object
+        re = klass.new
         # the form context
         re.form_context = form_context(hook, annotation)
+        # set the hook
         re.send(@mod.record_entry_hook_writer, hook)
         # dispatch to the application service
         toxic = hook.persistence_service.create(re)
@@ -49,13 +61,19 @@ module CaTissue
       # @return (see #form_context)
       def fetch_form_context(hook, annotation)
         tmpl = StudyFormContext.new
-        tmpl.container_id = annotation.class.container_id
+        ctr_id = annotation.class.container_id
+        if ctr_id.nil? then
+          raise AnnotationError.new("#{hook.class.qp} annotation #{annotation.class} doesn't have the required container id")
+        end
+        tmpl.container_id = ctr_id
         ctxts = hook.persistence_service.query(tmpl)
-        case ctxts.size
+        ctxt = case ctxts.size
           when 0 then raise AnnotationError.new("Form context not found for annotation class #{annotation.class.qp}")
           when 1 then ctxts.first
           else raise AnnotationError.new("Multiple form contexts found for annotation class #{annotation.class.qp}")
         end
+        logger.debug { "#{annotation.qp} form context is #{ctxt}." }
+        ctxt
       end
     end
   end

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

@@ -5,7 +5,7 @@ module 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 [CaRuby::Domain::Attribute] 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..." }
@@ -89,9 +89,10 @@ module CaTissue
         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
+        # the owner attribute columns
+        klass.owner_attributes.each do |oattr|
+          hash[oattr] = owner_attribute_column(klass, oattr, eid)
+        end
         hash
       end
       
@@ -109,10 +110,23 @@ module CaTissue
         col
       end
       
+      # @quirk caTissue The caTissue 1.1.2 DYNEXT_ROLE table omits the target name for seven annotations,
+      #   e.g. SCG RadicalProstatectomyMargin. Work-around is to try the query with a null role name.
+      #
+      # @param [AnnotationClass] klass the annotation class
+      # @param [Symbol] attribute the owner attribute
+      # @param [Integer] eid the annotation entity id
+      # @return [String] the owner reference SQL column name
       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) }
+        # The referenced class name (confusingly called a source role in the caTissue schema).
+        tgt_nm = klass.attribute_metadata(attribute).type.name.demodulize
+        result = CaTissue::Database.instance.executor.execute { |dbh| dbh.select_one(OWNER_COLUMN_SQL, eid, tgt_nm) }
         col = result[0] if result
+        if col.nil? then
+          result = CaTissue::Database.instance.executor.execute { |dbh| dbh.select_one(ALT_1_1_OWNER_COLUMN_SQL, eid) }
+          col = result[0] if result
+        end
         if col.nil? then raise AnnotationError.new("Column not found for #{klass.qp} owner attribute #{attribute}") end
         col
       end
@@ -141,9 +155,22 @@ EOS
       # 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
+        from DYEXTN_CONSTRAINT_PROPERTIES cst, DYEXTN_ASSOCIATION assn, dyextn_role role
+        where cst.ASSOCIATION_ID = assn.IDENTIFIER
+        and assn.SOURCE_ROLE_ID = role.IDENTIFIER
+        and assn.TARGET_ENTITY_ID = ?
+        and role.name = ?
+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}.
+      ALT_1_1_OWNER_COLUMN_SQL = <<EOS
+        select cst.TARGET_ENTITY_KEY
+        from DYEXTN_CONSTRAINT_PROPERTIES cst, DYEXTN_ASSOCIATION assn, dyextn_role role
         where cst.ASSOCIATION_ID = assn.IDENTIFIER
+        and assn.SOURCE_ROLE_ID = role.IDENTIFIER
         and assn.TARGET_ENTITY_ID = ?
+        and role.name IS NULL
 EOS
     end
   end

data/lib/catissue/domain.rb

@@ -0,0 +1,26 @@
+require 'caruby/domain'
+require 'catissue/resource'
+require 'catissue/annotation/annotatable_class'
+require 'catissue/wustl/logger'
+
+module CaTissue
+  
+  private
+  
+  # The required Java package name.
+  PKG = 'edu.wustl.catissuecore.domain'
+  
+  # The domain class definitions.
+  SRC_DIR = File.join(File.dirname(__FILE__), 'domain')
+
+  # Enable the resource metadata aspect.
+  md_proc = Proc.new { |klass| AnnotatableClass.extend_class(klass) }
+  CaRuby::Domain.extend_module(self, :mixin => Resource, :metadata => md_proc, :package => PKG)
+  
+  # Set up the caTissue client logger before loading the class definitions.
+  Wustl::Logger.configure
+  
+  # Load the class definitions.
+  load_dir(SRC_DIR)
+end
+

data/lib/catissue/domain/abstract_position.rb

@@ -17,6 +17,6 @@ module CaTissue
     offset_attribute(:column => :position_dimension_one, :row => :position_dimension_two)
 
     # add the synthetic {#location} attribute
-    add_attribute(:location)
+    add_attribute(:location, Location)
   end
 end

data/lib/catissue/domain/abstract_specimen.rb

@@ -22,28 +22,28 @@ module CaTissue
      :event_parameters => :specimen_events,
      :characteristics => :specimen_characteristics)
 
-    # caTissue alert - initial_quantity must be set (cf. Bug #160)
+    # @quirk caTissue initial_quantity must be set (cf. Bug #160)
     add_attribute_defaults(:initial_quantity => 0.0, :pathological_status => 'Not Specified', :specimen_type => 'Not Specified')
 
     add_mandatory_attributes(:lineage, :pathological_status, :specimen_class, :specimen_type, :specimen_characteristics)
 
-    # caTissue alert - Specimen characteristics are auto-generated but SpecimenRequirement
-    # characteristics are not. It is safe to set the :autogenerated flag for both
-    # AbstractSpecimen subclasses. This results in an unnecessary SpecimenRequirement
-    # create database query, but SpecimenRequirement create is rare and there is no harm.
+    # @quirk caTissue Specimen characteristics are auto-generated but SpecimenRequirement
+    #   characteristics are not. It is safe to set the :autogenerated flag for both
+    #   AbstractSpecimen subclasses. This results in an unnecessary SpecimenRequirement
+    #   create database query, but SpecimenRequirement create is rare and there is no harm.
     #
-    # caTissue alert - Specimen characteristics is cascaded but is not an exclusive dependent,
-    # since it is shared by aliquots.
+    # @quirk caTissue Specimen characteristics is cascaded but is not an exclusive dependent,
+    #   since it is shared by aliquots.
     #
-    # caTissue alert - Bug 166: API update Specimen ignores a SpecimenCharacteristics with a
-    # different id. Guard against updating a Specimen with a SpecimenCharacteristics whose id
-    # differs from the existing id.
+    # @quirk caTissue Bug 166: API update Specimen ignores a SpecimenCharacteristics with a
+    #   different id. Guard against updating a Specimen with a SpecimenCharacteristics whose id
+    #   differs from the existing id.
     #
-    # caTissue alert - Unlike other dependents, AbstractSpecimen characteristics, events and child
-    # specimens have cascade style 'all'. This implies that an AbstractSpecimen update does not
-    # create a referenced dependent. AbstractSpecimen create cascades to create and AbstractSpecimen
-    # update cascades to update, but AbstractSpecimen update does not cascade to create.
-    # The :no_cascade_update_to_create flag is set to handle this feature of cascade style 'all'.
+    # @quirk caTissue Unlike other dependents, AbstractSpecimen characteristics, events and child
+    #   specimens have cascade style 'all'. This implies that an AbstractSpecimen update does not
+    #   create a referenced dependent. AbstractSpecimen create cascades to create and AbstractSpecimen
+    #   update cascades to update, but AbstractSpecimen update does not cascade to create.
+    #   The :no_cascade_update_to_create flag is set to handle this feature of cascade style 'all'.
     qualify_attribute(:specimen_characteristics, :cascaded, :fetched, :autogenerated, :no_cascade_update_to_create)
 
     # The :no_cascade_update_to_create flag is set since events has cascade style 'all'.
@@ -248,7 +248,7 @@ module CaTissue
       # infer the specimen domain class from the specimen_class prefix and Specimen or SpecimenRequirement suffix
       cls_nm = opt.to_s.capitalize_first + 'Specimen'
       cls_nm += 'Requirement' if CaTissue::SpecimenRequirement === self
-      CaTissue.domain_type_with_name(cls_nm)
+      CaTissue.const_get(cls_nm)
     end
 
     # Creates a derived specimen.