caruby-tissue 1.4.2 → 1.5.1

data/examples/pcbin/conf/biopsy_fields.yaml

@@ -1,4 +1,4 @@
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 Patient: CollectionProtocolRegistration.protocol_participant_identifier
 Specimen Type: TissueSpecimen.specimen_type
 Year of Diagnosis: Participant::Clinical::NewDiagnosisHealthAnnotation.date_of_examination

data/examples/pcbin/conf/patient_fields.yaml

@@ -1,4 +1,4 @@
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 Patient: CollectionProtocolRegistration.protocol_participant_identifier
 Race: Race.name
 Ethnicity: Participant.ethnicity

data/examples/pcbin/conf/surgery_fields.yaml

@@ -1,4 +1,4 @@
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 Patient: CollectionProtocolRegistration.protocol_participant_identifier
 Specimen Type: TissueSpecimen.specimen_type
 Year of Surgery: Participant::Clinical::Duration.start_date

data/examples/pcbin/conf/t_stage_fields.yaml

@@ -1,4 +1,4 @@
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 Patient: CollectionProtocolRegistration.protocol_participant_identifier
 Clinical Staging System: Participant::Clinical::LabAnnotation.other_lab_test_name
 Clinical T Stage: Participant::Clinical::LabAnnotation.result

data/examples/pcbin/conf/therapy_fields.yaml

@@ -1,4 +1,4 @@
-Protocol: CollectionProtocol.short_title
+Protocol: CollectionProtocol.title
 Patient: CollectionProtocolRegistration.protocol_participant_identifier
 Agent: Participant::Clinical::TreatmentAnnotation.agent
 Dose: Participant::Clinical::TreatmentAnnotation.dose

data/lib/catissue.rb

@@ -10,7 +10,7 @@ rescue LoadError
 end
 
 require 'caruby/util/log'
-require 'catissue/resource'
+require 'catissue/domain'
 require 'catissue/database'
 
 # CaTissue wraps the caTissue Java API.

data/lib/catissue/annotation/annotatable.rb

@@ -13,32 +13,22 @@ module CaTissue
         self.class.annotation_attribute?(attr) ? send(mth, *args) : super
       rescue AnnotationError
         raise
-      rescue Exception
-        raise
+      rescue NoMethodError
         super
       end
     end
     
-    # Creates a {Annotation::Proxy} whose hook reference is set to this annotatable object.
-    #
-    # @param [Class] the proxy class
-    # @return [Resource] the new proxy
-    def create_proxy(klass)
-      # make the proxy instance
-      pxy = klass.new
-      # set the proxy hook reference to this hook instance
-      pxy.hook = self
-      logger.debug { "Created #{qp} #{klass.domain_module.qp} annotation proxy #{pxy}." }
-      pxy
-    end
-    
-    # @param [Symbol] attribute the hook -> annotation attribute
-    # @return [Annotation] the hook -> proxy attribute
-    # @raise (see AnnotatableClass#annotation_proxy_attribute)
-    def annotation_proxy(attribute)
-      pxy_attr = self.class.annotation_proxy_attribute(attribute)
-      # the hook -> proxy attribute value
-      send(pxy_attr)
+    # @param [Symbol] attribute the hook => proxy attribute
+    # @param [Annotation] the annotation
+    # @return [Proxy] the hook proxy for the given annotation
+    def proxy_for(attribute, annotation)
+      @ann_pxy_hash ||= LazyHash.new do |ann|
+        pxy = self.class.attribute_metadata(attribute).type.new
+        pxy.hook = self
+        send(attribute) << pxy
+        pxy
+      end
+      @ann_pxy_hash[annotation]
     end
   end
 end

data/lib/catissue/annotation/annotatable_class.rb

@@ -1,6 +1,7 @@
-require 'forwardable'
 require 'caruby/util/inflector'
+require 'caruby/domain/metadata'
 require 'catissue/annotation/annotation_module'
+require 'catissue/annotation/de_integration'
 
 module CaTissue
   # Mix-in for extending a caTissue domain class with annotations.
@@ -9,32 +10,47 @@ module CaTissue
     # @return [Integer, nil] the the hook class designator that is used by caTissue to persist primary
     #   annotation objects, or nil if this is not a primary annotation class
     attr_reader :entity_id
+      
+    # @return [Class] the {DEIntegration} proxy class (nil for 1.1 caTissue)
+    def de_integration_proxy_class
+      @de_integration_proxy_class or (superclass.de_integration_proxy_class if superclass < Annotatable)
+    end
+    
+    # Adds {CaRuby::Domain::Metadata} and {AnnotatableClass} functionality to the given class.
+    #
+    # @param [Class] the domain class to extend
+    def self.extend_class(klass)
+      # Enable the class meta-data.
+      klass.extend(CaRuby::Domain::Metadata)
+      klass.extend(self)
+    end
     
     def self.extended(klass)
       super
-      # the annotation name => spec hash 
+      # Initialize the class annotation hashes.
       klass.class_eval do
-        extend Forwardable
+        # Enable the class meta-data.
+        # the annotation name => spec hash
         @ann_spec_hash = {}
-        @local_ann_attrs = []
+        # the annotation module => proxy hash
+        @ann_mod_pxy_hash = {}
       end
     end
-    
+
     # @return [Integer, nil] this class's entity id, if it exists, otherwise the superclass effective entity id
     #   if the superclass is an annotation class
     def effective_entity_id
       @entity_id or parent_entity_id
     end
- 
+
     # Loads the annotations defined for this class if necessary.
     def ensure_annotations_loaded
       # referencing the annotations loads them
       annotation_modules
     end
-   
-    # If there is an existing annotation whose proxy accessor is the
-    # given symbol, then return true. Otherwise, attempt to import
-    # an annotation and return whether the import was successful.
+
+    # If there is an existing annotation whose proxy accessor is the given symbol, then return true.
+    # Otherwise, attempt to import an annotation and return whether the import was successful.
     #
     # @param [Symbol] symbol the potential accessor attribute
     # @return [Boolean] whether there is a corresponding annotation
@@ -45,34 +61,19 @@ module CaTissue
       annotation_defined?(symbol)
     end
 
-    # Refines the {CaRuby::ResourceAttributes#toxic_attributes} to exclude annotation attributes.
+    # Refines the {CaRuby::Domain::Attributes#toxic_attributes} to exclude annotation attributes.
     #
     # @return [<Symbol>] the non-annotation unfetched attributes
     def toxic_attributes
       @anntbl_toxic_attrs ||= unfetched_attributes.compose { |attr_md| not attr_md.type < Annotation } 
     end
-    
-    def annotation_proxy_attribute(attribute)
-      annotatable_class_hierarchy.detect_value { |klass| klass.local_annotation_proxy_attribute(attribute) }
-    end
 
-    # Makes a new attribute in this hook class for the given annotation proxy domain attribute.
-    # The hook annotation reference attribute delegates to the proxy. This method is intended for
-    # the exclusive use of {Annotation::ProxyClass}.
-    #
     # @param [AnnotationModule] mod the annotation module
-    # @param [Symbol] attribute the proxy => annotation reference 
-    def create_annotation_attribute(mod, attribute)
-      pxy = mod.proxy
-      pxy_attr = @ann_mod_pxy_hash[mod]
-      ann_attr_md = pxy.attribute_metadata(attribute)
-      # the type referenced by the annotation proxy
-      klass = ann_attr_md.type
-      # create annotation accessors which delegate to the proxy
-      def_delegators(pxy_attr, *ann_attr_md.accessors)
-      logger.debug { "Created #{qp}.#{attribute} which delegates to the annotation proxy #{pxy_attr}." }
-      # add the attribute
-      add_annotation_attribute(attribute, klass)
+    # @return [Symbol] the corresponding annotation proxy reference attribute
+    def annotation_proxy_attribute(mod)
+      @ann_mod_pxy_hash[mod] or
+        (superclass.annotation_proxy_attribute(mod) if superclass < Annotatable) or
+        raise AnnotationError.new("#{qp} #{mod} proxy attribute not found.")
     end
     
     # Loads the annotations, if necessary, and tries to get the constant again.
@@ -88,6 +89,14 @@ module CaTissue
         const_get(symbol)
       end
     end
+
+    # Filters {CaRuby::Domain::Attributes#loadable_attributes} to exclude the {#annotation_attributes}
+    # since annotation lazy-loading is not supported.
+    #
+    # @return (see CaRuby::Domain::Attributes#loadable_attributes)
+    def loadable_attributes
+      @antbl_ld_attrs ||= super.compose { |attr_md| not attr_md.type < Annotation }
+    end
     
     def printable_attributes
       @prbl_attrs ||= super.union(annotation_attributes)
@@ -106,7 +115,7 @@ module CaTissue
     end
     
     def annotation_attributes
-      @ann_attrs ||= append_ancestor_enum(@local_ann_attrs) do |sc|
+      @ann_attrs ||= append_ancestor_enum(@ann_mod_pxy_hash.enum_values) do |sc|
         sc.annotation_attributes if sc < Annotatable
       end
     end
@@ -118,21 +127,23 @@ module CaTissue
       @ann_mods ||= load_annotations
     end
     
-    # @param [Symbol] attribute the annotation attribute
-    # @return [Symbol] the annotation proxy attribute
-    # @raise [TypeError] if the given attribute is not an annotation attribute
-    def local_annotation_proxy_attribute(attribute)
-      unless annotation_attribute?(attribute) then
-        raise TypeError.new("#{qp} #{attribute} is not an annotation attribute")
-      end
-      # the annotation class
-      klass = attribute_metadata(attribute).type
-      mod = klass.domain_module
-      @ann_mod_pxy_hash[mod]
-    end    
-    
     private
     
+    # @param [String] name the proxy record entry class name
+    def annotation_proxy_class_name=(name)
+      @de_integration_proxy_class = Annotation::DEIntegration.proxy(name)
+      if @de_integration_proxy_class then
+        # hide the internal caTissue proxy collection attribute
+        attr = detect_attribute_with_type(@de_integration_proxy_class)
+        if attr then
+          remove_attribute(attr)
+          logger.debug { "Hid the internal caTissue #{qp} annotation record-keeping attribute #{attr}." }
+        end
+      else
+        logger.debug { "Ignored the missing caTissue #{qp} proxy class name #{name}, presumably unsupported in this caTissue release." }
+      end
+    end
+    
     # Loads the annotation modules in the class hierarchy.
     #
     # @return [<AnnotationModule>] an Enumerable on the loaded annotation modules
@@ -175,16 +186,17 @@ module CaTissue
     #
     # @return [<AnnotationModule>] the loaded annotation modules
     def load_local_annotations
-      # the annotation module => proxy hash
-      @ann_mod_pxy_hash = {}
       # an annotated class has a hook entity id
-      unless @ann_spec_hash.empty? then
-        @entity_id = Annotation::EntityFacade.instance.hook_entity_id(self) 
-      end
+      unless @ann_spec_hash.empty? then initialize_annotation_holder end
       # build the annotations
       @ann_spec_hash.map { |name, opts| import_annotation(name, opts) }
+    end    
+    
+    # Determines this annotated class's {#entity_id} and {#de_integration_proxy_class}.
+    def initialize_annotation_holder
+      @entity_id = Annotation::EntityFacade.instance.hook_entity_id(self)
     end
-   
+    
     # @param [Symbol] attribute the annotation accessor
     # @return [Module] the annotation module which implements the attribute
     def annotation_attribute_module(attribute)
@@ -199,20 +211,19 @@ module CaTissue
     # @raise [AnnotationError] if there is no annotation proxy class
     def import_annotation(name, opts)
       logger.debug { "Importing #{qp} annotation #{name}..." }
-      # make the annotation module scoped by this Annotatable class
-      class_eval("module #{name}; end")
-      mod = const_get(name)
-      # append the AnnotationModule methods
-      AnnotationModule.extend_module(mod, self, opts)
-      # make the proxy attribute
-      create_proxy_attribute(mod)
-      # make the annotation dependent attributes
-      create_annotation_attributes(mod)
-      # add proxy references
-      mod.ensure_proxy_attributes_are_defined
-      mod.add_annotation_dependents
-      logger.debug { "Imported #{qp} annotation #{name}." }
-      mod
+      # Make the annotation module scoped by this Annotatable class.
+      class_eval("class #{name}; end")
+      klass = const_get(name)
+      # Append the AnnotationModule methods.
+      AnnotationModule.extend_module(klass, self, opts)
+      # Make the proxy attribute.
+      attr = create_proxy_attribute(klass)
+      # The proxy is a logical dependent.
+      add_dependent_attribute(attr, :logical)
+      logger.debug { "Created #{qp} annotation proxy logical dependent reference attribute #{attr}." }
+      # Fill out the dependency hierarchy.
+      klass.proxy.build_annotation_dependency_hierarchy
+      klass
     end
 
     # Returns whether this class has an annotation whose proxy accessor is the
@@ -229,59 +240,21 @@ module CaTissue
     # The attribute reader creates an {Annotation::Proxy} instance of the method
     # receiver {Annotatable} instance on demand.
     # 
-    # @param [AnnotationModule] mod the subject annotation module
+    # @param [AnnotationModule] klass the subject annotation
     # @return [Symbol] the proxy attribute
-    def create_proxy_attribute(mod)
+    def create_proxy_attribute(klass)
       # the proxy class
-      pxy = mod.proxy
-      # the proxy attribute
-      attr = mod.name.demodulize.underscore.to_sym
-      # define the proxy attribute
-      attr_create_on_demand_accessor(attr) { |obj| obj.create_proxy(pxy) }
-      # add it as a standard (but unpersisted) attribute
-      add_attribute(attr, pxy, :unsaved)
-      # create the proxy => hook inverse
-      pxy.set_hook(self, attr)
-      logger.debug { "Added #{qp} #{mod.qp} annotation proxy attribute #{attr}." }
+      pxy = klass.proxy
+      # the proxy attribute symbol
+      attr = klass.name.demodulize.underscore.to_sym
+      # Define the proxy attribute.
+      attr_create_on_demand_accessor(attr) { Set.new }
+      # Register the attribute.
+      add_attribute(attr, pxy, :collection, :saved)
+      logger.debug { "Added #{qp} #{klass.qp} annotation proxy attribute #{attr} of type #{pxy}." }
       # the annotation module => proxy attribute association
-      @ann_mod_pxy_hash[mod] = attr
+      @ann_mod_pxy_hash[klass] = attr
       attr
     end
-
-    # Makes a new attribute in this hook class for each of the given annotation module's
-    # proxy domain attributes. The hook annotation reference attribute delegates to the
-    # proxy.
-    #
-    # @param [AnnotationModule] mod the subject annotation module
-    # @param [Symbol] proxy_attribute the hook => proxy reference 
-    def create_annotation_attributes(mod)
-      # create annotation attributes which delegate to the proxy
-      mod.proxy.annotation_attributes.each do |attr|
-        create_annotation_attribute(mod, attr)
-      end
-    end
-
-    # Adds the given annotation attribute as a dependent collection attribute with meta-data.
-    #
-    # @param [Symbol] attribute the annotation accessor
-    # @param [Class] type the attribute domain type
-    def add_annotation_attribute(attribute, type)
-      logger.debug { "Adding #{qp} #{type.qp} annotation attribute #{attribute}..." }
-      # Mark the attribute as a collection.
-      add_attribute(attribute, type, :collection)
-      
-      # the camel-case attribute is a potential alias
-      jattr = attribute.to_s.camelize(:lower).to_sym
-      unless attribute == jattr then
-        add_attribute_aliases(jattr => attribute)
-      end
-      
-      # the annotation is a dependent
-      add_dependent_attribute(attribute, :logical)
-      # add the attribute to the local collection
-      @local_ann_attrs << attribute
-      
-      attribute
-    end
   end
 end

data/lib/catissue/annotation/annotation.rb

@@ -1,58 +1,23 @@
 require 'caruby/resource'
 require 'caruby/domain/id_alias'
+require 'catissue/domain/hash_code'
 
 module CaTissue
   # Annotation acceess error class.
   class AnnotationError < StandardError; end
   
-  # Annotation class mix-in.
+  # Annotation is the caTissue dynamic extension class mix-in.
+  #
+  # @quirk caTissue Annotation RecordEntry proxy classes implements hashCode with the identifier.
+  #   Consequently, a set member is not found after identifier assignment.
+  #   The work-around is to include the HashCode mixin, which reimplements the hash and equality
+  #   test methods to be invariant with respect to identifier assignment.
   module Annotation
-    include CaRuby::Resource, CaRuby::IdAlias
+    include CaRuby::Resource, CaRuby::IdAlias, HashCode
 
-    # Returns the CaTissue::Database which stores this object.
+    # @return [Database] the database which stores this object
     def database
       CaTissue::Database.instance
     end
-    
-    # Updates the annotation proxy to reflect the hook, if necessary.
-    #
-    # @see Proxy#ensure_identifier_reflects_hook
-    def ensure_proxy_reflects_hook
-      pxy = proxy || return
-      pxy.ensure_identifier_reflects_hook
-    end
-    
-    # @return [Annotatable, nil] the hook object which owns this annotation, or nil if this annotation
-    #   is not directly owned by a hook entity
-    def hook
-      pxy_attr_md = self.class.proxy_attribute_metadata
-      send(pxy_attr_md.reader) if pxy_attr_md
-    end
-    
-    # If there is no conventional owner, then try the hook.
-    #
-    # caTissue alert - DE annotations have a physical dependency ownership model that is at odds
-    # with the logical model. An annotation does not directly reference its static hook owner
-    # instance. Rather, it references the hook proxy which stands in for the hook entity in the
-    # annotation package. 
-    #
-    # @return the {CaRuby::Resource#owner} or the {#hook}
-    def owner
-      super or hook
-    end
-    
-    # @return [Proxy, nil] the proxy which references this annotation, or nil if this is not a
-    #   primary annotation
-    def proxy
-      # the annotation owner hook instance 
-      ownr = hook || return
-      # the hook -> annotation reference attribute
-      attr = self.class.hook_proxy_attribute
-      if attr.nil? then
-        raise AnnotationError.new("Primary annotation #{qp} references hook #{hook} but doesn't have a hook proxy attribute")
-      end
-      # the owner proxy for the attribute
-      ownr.annotation_proxy(attr)
-    end
   end
 end