caruby-tissue 1.2.2 → 1.2.3

data/lib/catissue/annotation/annotation_module.rb

@@ -0,0 +1,77 @@
+require 'caruby/domain/resource_module'
+require 'catissue/annotation/annotation'
+require 'catissue/annotation/annotation_class'
+require 'catissue/annotation/proxy'
+require 'catissue/annotation/proxy_class'
+
+module CaTissue
+  module AnnotationModule
+    include CaRuby::ResourceModule
+
+    # @return [AnnotationClass] the annotation proxy class 
+    attr_accessor :proxy
+
+    def self.extend_module(mod, hook, opts)
+      mod.extend(self)
+      mod.initialize_annotation(hook, opts)
+    end
+    
+    def initialize_annotation(hook, opts)
+      extend(CaRuby::ResourceModule)
+      @java_package = opts[:package]
+      @svc_nm = opts[:service]
+      create_mixin
+      # 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.
+      @proxy = import_proxy(hook)
+      @proxy.extend(Annotation::ProxyClass)
+    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
+      @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
+    end
+    
+    def persistence_service
+      @ann_svc ||= Database.instance.annotator.create_annotation_service(@svc_nm)
+    end
+    
+    private
+    
+    def create_mixin
+      module_eval("module Resource; end")
+      @mixin = const_get('Resource')
+      mod = self
+      @mixin.module_eval do
+        include Annotation
+        
+        @domain_module = mod
+        def self.included(klass)
+          super
+          @domain_module.add_class(klass)
+          klass.extend(AnnotationClass)
+          logger.debug { "#{klass.qp} marked as an annotation class." }
+        end
+      end
+    end
+    
+    def import_proxy(hook)
+      # the annotation proxy Java class name
+      proxy_nm = hook.name.demodulize
+      logger.debug { "Importing #{hook.qp} annotation #{qp} hook proxy Java class..." }
+      begin
+        const_get(proxy_nm)
+      rescue CaRuby::JavaIncludeError
+        raise AnnotationError.new("#{hook.qp} annotation #{qp} does not have a hook proxy class - #{$!}")
+      end
+    end
+  end
+end

data/lib/catissue/annotation/hibernate_mapping.rb

@@ -0,0 +1,46 @@
+require 'xmlsimple'
+require 'caruby/util/inflector'
+require 'catissue/annotation/annotation'
+
+module CaTissue
+  module Annotation
+    # Annotation class Hibernate mapping encapsulation.
+    #
+    # caTissue alert - caTissue doesn't appear to use Hibernate for DEs. The mappings are incorrect
+    # and should not be used.
+    class HibernateMapping
+      
+      attr_accessor :table
+      
+      def initialize(klass)
+        hbm = hibernate_mapping(klass)
+        @table = hbm['table']
+        @attr_col_hash = {}
+        hbm['property'].each do |name, md|
+          @attr_col_hash[name.underscore.to_sym] = md['column']
+        end
+      end
+      
+      def column(attribute)
+        @attr_col_hash[attribute]
+      end
+    
+      private
+      
+      HBM_DIR = File.join(File.dirname(__FILE__), '..', '..', '..', 'conf', 'annotation')
+      
+      HBM_OPTS = { 'KeyAttr' => 'name' }
+      
+      def hibernate_mapping(klass)
+        file = hibernate_mapping_file(klass)
+        conf = XmlSimple.xml_in(file, HBM_OPTS)
+        conf['class'][klass.name.demodulize]
+      end
+      
+      def hibernate_mapping_file(klass)
+        dir = klass.java_class.name[/\w+/]
+        File.join(HBM_DIR, dir, "#{klass.name.demodulize}.hbm.xml")
+      end  
+    end
+  end
+end

data/lib/catissue/annotation/proxy.rb

@@ -0,0 +1,28 @@
+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
+      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
+      
+      # 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
+      end
+    end
+  end
+end

data/lib/catissue/annotation/proxy_class.rb

@@ -0,0 +1,68 @@
+require 'set'
+require 'catissue/annotation/annotation'
+require 'catissue/annotation/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 }
+      end
+      
+      def annotation_attributes
+        @ann_attrs ||= domain_attributes.compose { |attr_md| attr_md.type < Annotation }
+      end
+
+      # Sets this proxy's hook to the given class. 
+      # 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
+        # Make a new hook reference attribute.
+        attr_accessor(:hook)
+        # 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}." }
+      end
+      
+      # Adds each proxy => annotation reference as a dependent attribute.
+      def add_annotation_dependents
+        annotation_attributes.each_metadata do |attr_md|
+          attr_md.type.add_dependent_attributes
+          attr_md.type.proxy = self
+        end
+        annotation_attributes.each_metadata do |attr_md|
+          attr_md.type.add_dependent_attribute_closure
+        end
+      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)
+        # 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..." }
+        # Define the access methods: the reader creates a new set on demand to hold the annotations.
+        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)
+      end
+    end
+  end
+end

data/lib/catissue/cli/migrate.rb

@@ -13,13 +13,13 @@ module CaTissue
       # objects. This is used for testing a migration dry run. It is recommended that the trial run
       # protocol is set to a test protocol as well.
       SPECS = [
-        [:input, "input", "Source file to migrate"],
+        [:input, "-i", "input", "Source file to migrate"],
         [:target, "-t", "--target CLASS", "Migration target class"],
         [:mapping, "-m", "--mapping FILE", "The input field => caTissue attribute mapping file"],
         [:shims, "-s", "--shims FILE[,FILE...]", Array, "Migration customization shim files to load"],
         [:bad, "-b", "--bad FILE", "Write each invalid record to the given file and continue migration"],
         [:unique, "-u", "--unique", "Make the migrated objects unique for testing"],
-        [:offset, "--offset N", Integer, "Number of input records to skip before starting the migration"]
+        [:offset, "-o", "--offset N", Integer, "Number of input records to skip before starting the migration"]
       ]
   
       # Creates a {CaTissue::CLI::Migrate} command with the given standard command line specifications

data/lib/catissue/cli/smoke.rb

@@ -11,7 +11,9 @@ module CaTissue
       
       private
       
-      DB_MSG = "Verifying database access by searching for the pre-defined #{CaTissue::Site::DEF_SITE_NAME} Site..."
+      DEF_SITE = CaTissue::Site.default_site
+      
+      DB_MSG = "Verifying database access by searching for the pre-defined #{DEF_SITE.name} Site..."
       
       # Runs the smoke test.
       def execute
@@ -23,7 +25,7 @@ module CaTissue
       
       def find_in_transit_site
         begin
-          site = CaTissue::Site.new(:name => CaTissue::Site::DEF_SITE_NAME).find
+          site = DEF_SITE.find
         rescue Exception => e
           logger.error("caTissue database access was unsuccessful - #{e}:\n#{e.backtrace.qp}")
           puts "caTissue database access was unsuccessful - #{e}."
@@ -31,11 +33,11 @@ module CaTissue
         end
         
         if site then
-          puts "The #{CaTissue::Site::DEF_SITE_NAME} Site was found with identifier #{site.identifier}."
+          puts "The #{DEF_SITE.name} Site was found with identifier #{site.identifier}."
           puts "Smoke test successful."
           exit 0
         else
-          puts "The #{CaTissue::Site::DEF_SITE_NAME} Site was not found."
+          puts "The #{DEF_SITE.name} Site was not found."
           puts "Smoke test unsuccessful."
           exit 69 # service unavailable error status
         end

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

@@ -1,79 +1,93 @@
 require 'caruby/util/inflector'
+require 'caruby/database/sql_executor'
 require 'caruby/database/persistence_service'
-require 'caruby/util/uniquifier'
+require 'catissue/annotation/annotatable'
 
 module CaTissue
   module Annotation
     # An AnnotationService queries and saves CaTissue annotations.
     class AnnotationService < CaRuby::PersistenceService
-      # The IdGenerator calls the caTissue entity manager to create a new identifier for
-      # an annotation.
-      class IdGenerator
-        # Creates a new IdGenerator with the given caTissue entity_manager.
-        def initialize(entity_manager)
-          super()
-          @entity_manager = entity_manager
-        end
-
-        # Returns a new identifier for the given annotation object.
-        def next_identifier(annotation)
-          logger.debug { "Generating identifier for annotation #{annotation}..." }
-          id = @entity_manager.get_next_identifier_for_entity(annotation.class.qp).to_i
-          # work-around caTissue bug - use a high number that won't conflict with the autogenerated range
-          # cf. https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=19&t=404&sid=786325c9c46503529a2b64f0b66fed0a
-          if id.nil? or id.zero? then
-            id = Uniquifier.qualifier
-            logger.warn("Entity manager did not create annotation identifier; using id #{id}.")
-          end
-          id
-        end
-      end
-
       # Creates an AnnotationService for the given CaTissue::Database, service name and options.
       #
-      # Supported options include the following:
-      # * :anchor - the required anchor class
-      # * :integration_service - the required IntegrationService
-      # * :entity_manager - the required EntityManager
-      # * +version+ - the optional caTissue version identifier
-      def initialize(database, service_name, options)
-        super(service_name, Options.get(:version, options))
+      # @param [CaTissue::Database] database the database
+      # @param [String] name the caTissue DE service name
+      # @param (see CaRuby::PersistenceService#initialize)
+      # @option opts :hook the required hook class
+      # @option opts :integration_service the required IntegrationService
+      # @option opts (see CaRuby::PersistenceService#initialize)
+      def initialize(database, name, opts)
+        super(name, opts)
         @database = database
-        @anchor_class = Options.get(:anchor, options)
-        @integration_service = Options.get(:integration_service, options)
-        entity_manager = Options.get(:entity_manager, options)
-        @id_generator = IdGenerator.new(entity_manager)
-      end
-
-      # Query the given domain object obj with the given attribute path. The query result is
-      # an array of CaRuby::Annotation objects. Overrides {CaRuby::PersistenceService#query} to
-      # delegate to the caTissue integration service when the penultimate search class is this
-      # AnnotationService anchor class, e.g.:
-      #   query(CaTissue::SpecimenCollectionGroup.new(:name => 'Biobank_1_5'), :base_pathology_annotation)
-      # or
-      #   query(CaTissue::ReceivedEventParameters.new(:user => user), :specimen_collection_group, :base_pathology_annotation)
-      def query(obj, *path)
-        # delegate path[0...-1] to database unless path.length < 2
-        return @database.query(obj, *path[0...-1]).map { |fetched| query(fetched, path[-1]) }.flatten unless path.length < 2
-        return super unless @anchor_class === obj.class
-        # fetch the anchor objects if necessary
-        return @database.query(obj).map { |fetched| query(fetched, *path) }.flatten if obj.identifier.nil?
-        # obj is an anchor with an identifier; make a template
-        template = obj.copy(:identifier)
-        # delegate to the integration service to find the anchor annotations
-        @integration_service.query(template, *path)
+        @database.add_persistence_service(self)
+        @int_svc = opts[:integration_service]
       end
 
-      # Augments the CaRuby::PersistenceService create method to handle caTissue annotation service peculiarities,
-      # e.g. assigning an identifier since assignment is not done automatically as is the case with the default
-      # application service.
+      # Augments the {CaRuby::PersistenceService} create method to handle caTissue annotation
+      # service peculiarities, e.g.:
+      # * assigns the identifier, since assignment is not done automatically as is the case with the
+      #   default application service
+      # * associate the annotation to the hook object
+      # * Save all referenced annotation objects
+      #
+      # This method can only be called on primary annotation objects. A _primary_ annotation
+      # is a top-level annotation which has a reference to the {Annotation#hook} which is
+      # being annotated.
+      # 
+      # @param [Annotation] annotation the annotation object to create
+      # @return [Annotation] the annotation
       def create(annotation)
-        annotation.identifier ||= @id_generator.next_identifier(annotation)
-        super
-        owner = annotation.owner
-        @integration_service.associate(owner, annotation) if CaRuby::Annotatable === owner
+        logger.debug { "Creating annotation #{annotation.qp}..." }
+        # 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 hook then
+          time { create_primary_annotation(annotation, hook) }
+        else
+          create_secondary_annotation(annotation)
+        end
+        logger.debug { "Created annotation #{annotation}." }
         annotation
       end
+      
+      private
+      
+      # @param annotation (see #create)
+      # @param [Annotable] the annotatable object referenced by this annotation
+      def create_primary_annotation(annotation, hook)
+        # write the annotation records
+        create_annotation_object(annotation)
+        # Create the "cascaded" references.
+        annotation.class.save_dependent_attributes(annotation)
+        # If the annotation references a hook, then delegate to the integration service to associate
+        # the hook to the annotation.
+        @int_svc.associate(hook, annotation)
+      end
+      
+      def create_secondary_annotation(annotation)
+        # the owner annotation
+        ownr = annotation.owner
+        if ownr.nil? then
+          raise AnnotationError.new("Cannot create secondary annotation #{annotation.qp} since it does not have an owner")
+        end
+        # creating the owner creates this secondary
+        create(ownr)
+      end
+      
+      # @see #create
+      def create_annotation_object(annotation)
+        # can't create a proxy
+        if Proxy === annotation then
+          raise AnnotationError.new("#{annotation} annotation proxy create is not supported")
+        end
+        # The sequence generator next id.
+        annotation.identifier = EntityFacade.instance.next_identifier(annotation)
+        # Ensure that the proxy record is up-to-date.
+        annotation.ensure_proxy_reflects_hook
+        
+        # Delegate to standard record create.
+        app_service.create_object(annotation)
+      end
     end
   end
 end

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

@@ -1,84 +1,25 @@
-require 'caruby/util/properties'
 require 'catissue/database/annotation/integration_service'
-require 'catissue/database/annotation/annotatable_service'
 require 'catissue/database/annotation/annotation_service'
-require 'catissue/database/annotation/entity_manager'
+require 'catissue/database/annotation/entity_facade'
 
 module CaTissue
-  module Annotation
-    # An Annotator creates annotation services for annotatable and annotation classes.
-    class Annotator
-      def initialize(database)
-        @database = database
-        #the sole DE integration service, used by the annotation services
-        @entity_manager = Annotation::EntityManager.instance
-        @integration_service = Annotation::IntegrationService.new(@entity_manager)
-        @anchor_svc_hash = {}
-        @ann_mod_svc_hash = {}
-      end
-
-      # Returns the CaRuby::PersistenceService for the given klass, or nil if klass is neither
-      # annotatable nor an annotation.
-      def service(klass)
-        annotatable_service(klass) or annotation_service(klass)
-      end
-
-      private
-
-      # Returns the Annotation::AnnotatableService for the given klass, or nil if klass is not annotatable.
-      def annotatable_service(klass)
-        return @anchor_svc_hash[klass] ||= create_annotatable_service(klass) if JavaImport::AnnotatableClass === klass
-        annotatable_service(klass.superclass) if klass.superclass
-      end
-
-      # Returns the Annotation::AnnotatorService for the given klass, or nil if klass is not an annotation.
-      def annotation_service(klass)
-        return @ann_mod_svc_hash[klass.annotation_module] ||= create_annotation_service(klass.annotation_module) if JavaImport::AnnotationClass === klass
-        annotation_service(klass.superclass) if klass.superclass
-      end
-
-      def create_annotatable_service(klass)
-        Annotation::AnnotatableService.new(@database, @database.persistence_service, @integration_service)
-      end
-
-      def create_annotation_service(mod)
-        Annotation::AnnotationService.new(@database, mod.service, :anchor => mod.anchor_class, 
-          :integration_service => @integration_service, :entity_manager => @entity_manager)
-      end
+  # An Annotator creates annotation services for annotatable and annotation classes.
+  class Annotator
+    attr_reader :integration_service
+    
+    # Initializes a new Annotator for the given database.
+    #
+    # @param [CaTissue::Database] the database
+    def initialize(database)
+      @database = database
+      #the sole DE integration service, used by the annotation services
+      @integration_service = Annotation::IntegrationService.new
+    end
 
-      # TODO - delete if obsolete
-      # Returns the class => annotator hash from the given database's properties.
-      def create_service_hashes(database)
-        @anchor_svc_hash = {}
-        @pkg_svc_hash = {}
-        #the sole DE integration service, used by the annotation services
-        integration_service = Annotation::IntegrationService.new
-        entity_manager = Annotation::EntityManager.instance
-        # the anchor class => { package => { attribute => type } } hash
-        anchor_pkg_attrs_hash = CaTissue.access_properties[CaRuby::Domain::Properties::ANNOTATIONS_PROP]
-        return {} if anchor_pkg_attrs_hash.nil?
-        # the package => service name hash
-        pkg_svc_nm_hash = CaTissue.access_properties[CaRuby::Domain::Properties::ANN_SVCS_PROP]
-        if pkg_svc_nm_hash.nil? then
-          raise CaRuby::ConfigurationError.new("Annotation service property missing: #{CaRuby::Domain::Properties::ANN_SVCS_PROP}")
-        end
-        # build the anchor => service and package => service hashes
-        anchor_service = Annotation::AnnotatableService.new(database, database.persistence_service, integration_service)
-        # make an annotatable service for each anchor and an annotator service for each package
-        anchor_pkg_attrs_hash.each do |anchor_cls_nm, pkg_signatures_hash|
-          anchor_class = CaTissue.const_get(anchor_cls_nm)
-          @anchor_svc_hash[anchor_class] = anchor_service
-          pkg_signatures_hash.each do |pkg, signatures|
-            svc_nm = pkg_svc_nm_hash[pkg]
-            if svc_nm.nil? then
-              raise CaRuby::DatabaseError.new("Annotation service property value missing for package #{pkg} in property #{CaRuby::Domain::Properties::ANN_SVCS_PROP}")
-            end
-            @pkg_svc_hash[pkg] = Annotation::AnnotationService.new(database, svc_nm, :anchor => anchor_class, 
-              :integration_service => integration_service, :entity_manager => entity_manager)
-            logger.debug { "Annotator service #{anchor_class.qp} #{svc_nm} created for attributes #{signatures.pp_s(:single_line)}" }
-          end
-        end
-      end
+    # @param [String] name the service name
+    # @return [Annotation::AnnotationService] the annotation service
+    def create_annotation_service(name)
+      Annotation::AnnotationService.new(@database, name, :integration_service => @integration_service)
     end
   end
 end