caruby-tissue 1.2.1

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

@@ -0,0 +1,25 @@
+require 'delegate'
+require 'caruby/database/persistence_service'
+
+module CaTissue
+  module Annotation
+    # An AnnotatableService queries and saves domain classes which hold annotation attributes.
+    class AnnotatableService < DelegateClass(CaRuby::PersistenceService)
+      def initialize(database, app_service, integration_service)
+        super(app_service)
+        @database = database
+        @integration_service = integration_service
+      end
+#
+#       def create(obj)
+#        super
+#        # TODO - refactor CaRuby::Database to remove Annotation cases; iterate over each annotation attribute here
+#      end
+#
+#      def update(obj)
+#        super
+#        # TODO - refactor CaRuby::Database to remove Annotation cases; iterate over each annotation attribute here
+#      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+require 'caruby/util/inflector'
+require 'caruby/database/persistence_service'
+require 'caruby/util/uniquifier'
+
+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))
+        @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)
+      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.
+      def create(annotation)
+        annotation.identifier ||= @id_generator.next_identifier(annotation)
+        super
+        owner = annotation.owner
+        @integration_service.associate(owner, annotation) if CaRuby::Annotatable === owner
+        annotation
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,10 @@
+require 'caruby/import/java'
+
+module CaTissue
+  module Annotation
+    # EntityManager dependencies
+    java_import('edu.wustl.common.security.exceptions.UserNotAuthorizedException')
+    # EntityManager is the caTissue singleton Winnebago object for persisting annotations.
+    java_import('edu.common.dynamicextensions.entitymanager.EntityManager')
+  end
+end

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

@@ -0,0 +1,87 @@
+require 'caruby/database/persistence_service'
+
+module CaTissue
+  module Annotation
+    # An IntegrationService fetches and saves CaTissue anchor-annotation associations.
+    class IntegrationService < CaRuby::PersistenceService
+      SERVICE_NAME = 'deintegration'
+
+      java_import('deintegration.EntityMap')
+      java_import('deintegration.EntityMapRecord')
+
+      def initialize(entity_manager)
+        super(SERVICE_NAME)
+        @entity_manager = entity_manager
+      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)
+      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
+
+      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
+
+      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
+      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)
+      end
+
+      # Returns the undocumented caTissue entity id for the given annotation entity's demodulized Java class name.
+      #
+      # 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[/[^.]+$/])
+      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}")
+      end
+    end
+  end
+end

data/lib/catissue/database/controlled_value_finder.rb

@@ -0,0 +1,43 @@
+require 'caruby/util/log'
+require 'catissue/database/controlled_values'
+
+module CaTissue
+  # Finds attribute controlled values.
+  class ControlledValueFinder
+    # Creates a new ControlledValueFinder for the given attribute.
+    # The optional YAML properties file name maps input values to controlled values.
+    def initialize(attribute, file=nil)
+      @attribute = attribute
+      @remap_hash = load_controlled_value_hash(file)
+    end
+
+    # Returns the CV value for the given source value.
+    # If the value is remapped, then that value is returned.
+    # Otherwise, if the value is a standard CV, then the CV value is returned.
+    # Otherwise, a warning message is printed to the log and this method returns nil.
+    def controlled_value(value)
+      return if value.blank?
+      remapped = remapped_controlled_value(value)
+      return remapped if remapped
+      cv = supported_controlled_value(value)
+      logger.warn("#{@attribute} value '#{value}' ignored since it is not a recognized controlled value.") if cv.nil?
+      cv.value if cv
+    end
+
+    private
+
+    def remapped_controlled_value(value)
+      @remap_hash[value]
+    end
+
+    def supported_controlled_value(value)
+      ControlledValues.instance.find(@attribute, value)
+    end
+
+    def load_controlled_value_hash(file)
+      return {} unless file and File.exists?(file)
+      logger.debug { "Loading controlled value map for #{@attribute} from #{file}..." }
+      YAML::load_file(file)
+    end
+  end
+end

data/lib/catissue/database/controlled_values.rb

@@ -0,0 +1,162 @@
+require 'singleton'
+require 'caruby/util/log'
+require 'caruby/util/collection'
+require 'caruby/util/options'
+require 'caruby/util/visitor'
+require 'catissue/resource'
+require 'caruby/database/sql_executor'
+require 'catissue/util/controlled_value'
+require 'caruby/util/transitive_closure'
+require 'caruby/domain/properties'
+
+module CaTissue
+  # This ControlledValues class loads caTissue permissible values from the database.
+  # Use of this class requires the +dbi+ gem and the following caTissue database access
+  # properties are defined in the
+  # home directory .catissue.yaml file:
+  # * :database_host - the database host
+  # * :database - the database name
+  # * :database_user - the database username (not the caTissue login name)
+  # * :database_password - the database password (not the caTissue login password)
+  #
+  # The default :database_host is the application :host property value, which in turn
+  # defaults to +localhost+.
+  #
+  # The optional :database_port property overrides the default MySQL port.
+  #
+  # ControlledValues is an auxiliary utility class and is not used by the CaTissue Ruby API.
+  class ControlledValues
+    include Singleton
+
+    PUBLIC_ID_ROOTS_STMT = "select identifier, value from catissue_permissible_value where public_id = ? and parent_identifier is null or parent_identifier = 0"
+
+    CHILDREN_STMT = "select identifier, value from catissue_permissible_value where parent_identifier = ?"
+
+    INSERT_STMT = "insert into catissue_permissible_value (identifier, parent_identifier, public_id, value) values (?, ?, ?, ?)"
+
+    DELETE_STMT = "delete from catissue_permissible_value where identifier = ?"
+
+    MAX_ID_STMT = "select max(identifier) from catissue_permissible_value"
+
+    SEARCH_STMT = "select identifier from catissue_permissible_value where value collate latin1_bin = ?"
+
+    def initialize
+      # the default database name, used for direct database access
+      CaTissue.access_properties[:database] ||= CaTissue::Database::DEF_DATABASE_NAME
+      @executor = CaRuby::SQLExecutor.new(CaTissue.access_properties)
+      @pid_loaded_hash = LazyHash.new { |pid| load_pid_cvs(pid) }
+      @pid_value_cv_hash = LazyHash.new do |pid|
+        CaseInsensitiveHash.new { |hash, value| hash[value] = load_cv(pid, value) unless value.nil? }
+      end
+    end
+
+    # Returns the transitive closure of each CV with the given public id and its children.
+    # The CVs are loaded from the database if necessary.
+    #
+    # The following public id aliases are supported:
+    # * :tissue_site
+    # * :clinical_diagnosis
+    #
+    #@param [String,Symbol] public_id_or_alias the caTissue public id or an alias defined above
+    # @return [<ControlledValue>] instances for the given public_id_or_alias
+    def for_public_id(public_id_or_alias)
+      pid = ControlledValue.standard_public_id(public_id_or_alias)
+      @pid_loaded_hash[pid].values
+    end
+
+    # Returns the ControlledValue with the given public_id_or_alias and value.
+    # Loads the CV if necessary from the database. The loaded CV does not have a parent or children.
+    #
+    #@param [String,Symbol] public_id_or_alias the supported for_public_id alias
+    # @see #for_public_id load the CV hierarchy with supported aliases
+    def find(public_id_or_alias, value)
+      pid = ControlledValue.standard_public_id(public_id_or_alias)
+      @pid_value_cv_hash[pid][value]
+    end
+
+    # Creates a new controlled value record in the database from the given ControlledValue cv.
+    # The default identifier is the next identifier in the permissible values table.
+    #
+    # @param [ControlledValue] cv the controlled value to create
+    # @return cv
+    def create(cv)
+      cv.identifier ||= next_id
+      raise ArgumentError.new("Controlled value create is missing a public id") if cv.public_id.nil?
+      raise ArgumentError.new("Controlled value create is missing a value") if cv.value.nil?
+      logger.debug { "Creating controlled value #{cv} in the database..." }
+      @executor.execute { |dbh| dbh.prepare(INSERT_STMT).execute(cv.identifier, cv.parent_identifier, cv.public_id, cv.value) }
+      logger.debug { "Controlled value #{cv.public_id} #{cv.value} created with identifier #{cv.identifier}" }
+      @pid_value_cv_hash[cv.public_id][cv.value] = cv
+    end
+
+    # Deletes the given ControlledValue record in the database. Recursively deletes the
+    # transitive closure of children as well.
+    #
+    # @param [ControlledValue] cv the controlled value to delete
+    def delete(cv)
+      @executor.execute { |dbh| delete_recursive(cv, dbh.prepare(DELETE_STMT)) }
+    end
+
+    private
+
+    def load_pid_cvs(pid)
+      fetch_cvs_with_public_id(pid, @pid_value_cv_hash[pid])
+    end
+
+    def load_cv(public_id, value)
+      logger.debug { "Loading controlled value #{public_id} #{value} from the database..." }
+      row = @executor.execute { |dbh| dbh.select_one(SEARCH_STMT, value) }
+      logger.debug { "Controlled value #{public_id} #{value} not found." } and return if row.nil?
+      identifier = row[0]
+      logger.debug { "Controlled value #{public_id} #{value} loaded with identifier #{identifier}." }
+      make_controlled_value(:identifier => identifier, :public_id => public_id, :value => value)
+    end
+
+    def next_id
+      @executor.execute { |dbh| dbh.select_one(MAX_ID_STMT)[0].to_i } + 1
+    end
+
+    def delete_recursive(cv, sth)
+      raise ArgumentError.new("Controlled value to delete is missing an identifier") if cv.identifier.nil?
+      logger.debug { "Deleting controlled value #{cv} from the database..." }
+      logger.debug { "Deleting controlled value #{cv} children: #{cv.children.pp_s}..." } unless cv.children.empty?
+      cv.children.each { |child| delete_recursive(child, sth) }
+      sth.execute(cv.identifier)
+      @pid_value_cv_hash[cv.public_id].delete(cv.value)
+      logger.debug { "Controlled value #{cv} deleted." }
+    end
+
+    def fetch_cvs_with_public_id(pid, value_cv_hash)
+      id_cv_hash = {}
+      logger.debug { "Loading #{pid} controlled values from the database..." }
+      cvs = []
+      @executor.execute do |dbh|
+        dbh.select_all(PUBLIC_ID_ROOTS_STMT, pid) do |row|
+          identifier, value = row
+          cvs << value_cv_hash[value] ||= make_controlled_value(:identifier => identifier, :public_id => pid, :value => value)
+        end
+        # load the root CVs children
+        cvs.each { |cv| fetch_descendants(cv, dbh, value_cv_hash) }
+      end
+      value_cv_hash
+    end
+
+    def fetch_descendants(cv, dbh, value_cv_hash)
+      children = []
+      dbh.select_all(CHILDREN_STMT, cv.identifier) do |row|
+         identifier, value = row
+         children << value_cv_hash[value] = make_controlled_value(:identifier => identifier, :public_id => pid, :parent => cv, :value => value)
+      end
+      # recurse to chidren
+      children.each { |cv| fetch_descendants(cv, dbh, value_cv_hash) }
+    end
+    
+    # Returns a new ControlledValue with attributes set by the given attribute => value hash.
+    def make_controlled_value(value_hash)
+      cv = ControlledValue.new(value_hash[:value], value_hash[:parent])
+      cv.identifier = value_hash[:identifier]
+      cv.public_id = value_hash[:public_id]
+      cv
+    end
+  end
+end