caruby-tissue 1.2.1

data/lib/catissue/domain/storage_type.rb

@@ -0,0 +1,82 @@
+require 'caruby/util/collection'
+require 'caruby/util/partial_order'
+require 'catissue/util/storage_type_holder'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.StorageType')
+
+  # The StorageType domain class.
+  class StorageType
+    include StorageTypeHolder, PartialOrder, Resource
+
+    add_attribute_aliases(:default_temperature => :default_temprature_in_centigrade)
+
+    qualify_attribute(:holds_storage_types, :fetched)
+
+    qualify_attribute(:holds_specimen_array_types, :fetched)
+
+    set_attribute_type(:holds_specimen_array_types, CaTissue::SpecimenArrayType)
+
+    set_attribute_type(:holds_specimen_classes, String)
+
+    set_attribute_type(:holds_storage_types, CaTissue::StorageType)
+
+    # @return StorageContainer
+    def container_class
+      CaTissue::StorageContainer
+    end
+    
+    alias :add_child :add_child_type
+    
+    alias :add :add_child_type
+    
+    alias :<< :add_child_type
+
+    # @return whether this StorageType can hold a child of the given Storable storable type
+    def can_hold_child?(storable)
+      child_types.include?(storable.storable_type)
+    end
+
+    # Returns a StorageType array from this StorageType to a descendant StorageType which can
+    # hold the given storable, or nil if no such path exists.
+    def path_to(storable)
+     return [self] if can_hold_child?(storable)
+      path = holds_storage_types.detect_value { |child| child.path_to(storable) }
+      return path.unshift(self) if path
+    end
+
+    # @return the closure of ContainerTypes held by this ContainerType, including self
+    def closure
+      cts = [self]
+      child_types.each { |ct| cts.concat(ct.closure) if StorageType === ct }
+      cts
+    end
+
+    # @return whether this StorageType has a non-nil name equal to the other name or is {#equal?} to this StorageType
+    #
+    # This method is a work-around for caTissue Bug #70: StorageType and non-StorageType are equal.
+    def ==(other)
+      equal?(other) or (StorageType === other and name and name == other.name)
+    end
+
+    alias :eql? :==
+
+    # Returns -1, 0, or 1 if self is contained in, contains or the same as the other
+    # StorageType, resp.
+    def <=>(other)
+      raise TypeError.new("Can't compare #{qp} to #{other}") unless StorageType === self
+      return 0 if eql?(other)
+      return 1 if holds_storage_types.detect { |child| child >= other }
+      -1 if other > self
+    end
+
+    # Overrides the Java StorageType hashCode to make the hash insensitive to identifier assignment.
+    #
+    # @see #==
+    def hash
+      # caTissue alert - bad caTissue API hashCode leads to ugly cascading errors when using a CP in a Set
+      (object_id * 31) + 17
+    end
+  end
+end

data/lib/catissue/domain/transfer_event_parameters.rb

@@ -0,0 +1,53 @@
+require 'caruby/util/validation'
+require 'catissue/util/location'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.TransferEventParameters')
+
+  # The +caTissue+ TransferEventParameters class is augmented with zero-based
+  # +from_row+, +from_column+, +to_row+ and +to_column+ methods wrapping the corresponding one-based dimension attributes.
+  class TransferEventParameters
+    include Resource
+
+    add_attribute_aliases(:from_container => :from_storage_container, :to_container => :to_storage_container)
+
+    # column and row are the zero-offset counterparts of position_dimension_one and position_dimension_two, resp.
+    offset_attribute(:from_column => :from_position_dimension_one, :from_row => :from_position_dimension_two,
+      :to_column => :to_position_dimension_one, :to_row => :to_position_dimension_two)
+
+    add_mandatory_attributes(:to_container, :to_position_dimension_one, :to_position_dimension_two)
+    
+    # Returns the from Location.
+    def from
+      Location.new(:in => from_container, :at => [from_column, from_row]) if from_container
+    end
+
+    # Sets the from Location.
+    def from=(location)
+      if location then
+        self.from_container = location.container
+        self.from_row = location.row
+        self.from_column = location.column
+      end
+      location
+    end
+
+    add_attribute(:from)
+
+    # Returns the to Location.
+    def to
+      Location.new(:in => to_container, :at => [to_column, to_row]) if to_container
+    end
+
+    # Sets the to Location.
+    def to=(location)
+      if location.nil? then raise ArgumentError.new("Specimen cannot be moved to an empty location") end
+      self.to_container = location.container
+      self.to_row = location.row
+      self.to_column = location.column
+    end
+
+    add_attribute(:to)
+  end
+end

data/lib/catissue/domain/user.rb

@@ -0,0 +1,100 @@
+require 'caruby/util/validation'
+require 'catissue/resource'
+require 'catissue/util/person'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.User')
+
+  # The User domain class.
+  class User
+    include Person, Resource
+
+    # caTissue alert - work-around for caTissue Bug #66 - Client missing CSException class et al.
+    # caTissue User class initializes roleId to "", which triggers a client exception on subsequent
+    # getRoleId call. Use a private variable instead and bypass getRoleId.
+    def role_id
+      # TODO - uncomment following and get rid of @role_id i.v. when bug is fixed.
+      #value = send(old_method)
+      #return if value == ''
+      #value.to_i
+      @role_id
+    end
+
+    # Sets the role id to the given value, which can be either a String or an Integer.
+    # An empty or zero value is converted to nil.
+    #
+    # caTissue alert - caTissue API roleId is a String although the intended value domain is the
+    # integer csm_role.identifier.
+    def role_id=(value)
+      # value as an integer (nil is zero)
+      value_i = value.to_i
+      # set the Bug #66 work-around i.v.
+      @role_id = value_i.zero? ? nil : value_i
+      # value as a String (if non-nil)
+      value_s = @role_id.to_s if @role_id
+      # call Java with a String
+      setRoleId(value_s)
+    end
+
+    # make the convenience Person name a first-class attribute
+    add_attribute(:name)
+
+    # caTissue alert - clinical study is unsupported by caTissue.
+    remove_attribute(:clinical_studies)
+
+    # clarify that collection_protocols is a coordinator -> protocol association.
+    # make assigned protocol and site attribute names consistent.
+    add_attribute_aliases(:coordinated_protocols => :collection_protocols, :protocols => :assigned_protocols, :assigned_sites => :sites)
+
+    # login_name is a database unique key.
+    set_secondary_key_attributes(:login_name)
+
+    # email_address is expected to be unique, and is enforced by the caTissue business logic.
+    set_alternate_key_attributes(:email_address)
+
+    # Set defaults as follows:
+    # * page_of is the value set when creating a User in the GUI
+    # * role id is 7 = Scientist (public)
+    # * initial password is 'changeMe1'
+    add_attribute_defaults(:activity_status => 'Active', :page_of => 'pageOfUserAdmin', :role_id => 7, :new_password => 'changeMe1')
+
+    # caTissue alert - obscure GUI artifact User page_of attribute is insinuated into the data
+    # layer as a required attribute. Work-around is to simulate the GUI with a default value.
+    add_mandatory_attributes(:activity_status, :address, :cancer_research_group, :department,
+      :email_address, :first_name, :institution, :last_name, :page_of, :role_id)
+
+    add_dependent_attribute(:address)
+
+    add_dependent_attribute(:passwords)
+
+    set_attribute_inverse(:protocols, :assigned_protocol_users)
+
+    set_attribute_inverse(:sites, :assigned_site_users)
+
+    qualify_attribute(:cancer_research_group, :fetched)
+
+    qualify_attribute(:department, :fetched)
+
+    qualify_attribute(:institution, :fetched)
+
+    qualify_attribute(:protocols, :saved, :fetched)
+
+    qualify_attribute(:sites, :saved)
+
+    qualify_attribute(:page_of, :unfetched)
+
+    qualify_attribute(:new_password, :unfetched)
+
+    qualify_attribute(:role_id, :unfetched)
+
+    private
+
+    # By default, the emailAddress is the same as the loginName.
+    def add_defaults_local
+      super
+      self.login_name ||= email_address
+      self.email_address ||= login_name
+    end
+  end
+end

data/lib/catissue/extract/command.rb

@@ -0,0 +1,31 @@
+require 'catissue/cli/command'
+require 'catissue/extract/delta'
+require 'catissue/extract/extractor'
+
+module CaTissue
+  # ExtractCommand extracts target CaTissue domain class objects whose modification date is
+  # within a time interval to a CSV file based on a CSV mapping file.
+  class ExtractCommand < CaTissue::Command
+    # Creates a new ExtractCommand.
+    # The delta range is given by the required :since option and optional :before option.
+    # The default before value is the current DateTime. These are used to build a Delta
+    # which is passed to {CaRuby::Command#initialize} as the :ids option.
+    # The :log option specifies a log file.
+    # Other supported options are described in {Extractor#initialize}.
+    def initialize
+      # prep the options
+      since = opts.delete(:since)
+      raise ArgumentError.new("Missing required beginning of date selection range option") unless since
+      before = opts.delete(:before) || DateTime.now
+       # the data acquirer
+      opts[:ids] = Delta.new(@target, since, before)
+      # make the command
+      super(opts)
+    end
+
+    # Starts an Extractor with the command-line options.
+    def run
+      super { |opts| Extractor.new(opts) }
+    end
+  end
+end

data/lib/catissue/extract/delta.rb

@@ -0,0 +1,62 @@
+require 'date'
+require 'caruby/csv/csvio'
+require 'caruby/util/log'
+require 'caruby/util/collection'
+require 'caruby/util/pretty_print'
+require 'caruby/database/sql_executor'
+
+module CaTissue
+  # Delta determines caTissue objects which changed within a time interval.
+  class Delta
+    include Enumerable
+
+    private
+
+    SQL_FILE = File.join(File.dirname(__FILE__), '..', '..', '..', 'sql', 'delta.sql')
+
+    public
+
+    # Creates a new Delta for objects of the given target type which changed
+    # at or after the since Date and earlier but not at the before Date.
+    # The default before Date is now.
+    def initialize(target, since, before=nil)
+      # convert the required target to a CaTissue class if necessary
+      @matcher = create_table_regex(target)
+      @since = since
+      @before = before || DateTime.now
+    end
+
+    # Calls the given block on each caTissue identifier satisfying the delta condition.
+    # This method submits the delta SQL and filters the result on the target class.
+    # This method always submits the query; the caller is responsible for preserving
+    # the result if necessary using {#to_a}.
+    def each(&block)
+      execute_query(&block)
+    end
+
+    private
+
+    # Returns the result of running the delta SQL on the target CaTissue domain class.
+    def execute_query
+      sql = File.open(SQL_FILE) { |file| file.read }
+      logger.debug { "Executing identifier change set selection range #{@since} - #{@before}, SQL:\n#{sql}" }
+      CaRuby::SQLExecutor.new(CaTissue.access_properties).execute do |dbh|
+        dbh.select_all(sql, @since, @before) do |row|
+          table, identifier = row
+          yield identifier.to_i if table =~ @matcher
+        end
+      end
+    end
+
+    # Returns the table match REs for the given target class.
+    def create_table_regex(target)
+      # The class => table RE hash. Make this hash rather than defining a constant in order to enable
+      # logging before touching a domain class.
+      @cls_tbl_hash ||= {
+        CaTissue::Specimen => /catissue_[[:alpha:]]+_specimen/i,
+        CaTissue::SpecimenCollectionGroup => /catissue_specimen_coll_group/i
+      }
+      @cls_tbl_hash.detect_value { |klass, table| table if target <= klass }
+    end
+  end
+end

data/lib/catissue/extract/extractor.rb

@@ -0,0 +1,99 @@
+require 'caruby/util/properties'
+require 'caruby/csv/csv_mapper'
+require 'caruby/csv/csvio'
+
+module CaTissue
+  # Extracts caTissue objects.
+  class Extractor
+    include Enumerable
+
+    # The default name of this migrator.
+    DEF_NAME = 'caTissue Extractor'
+
+    # The extract output file
+    attr_reader :output
+
+    # Creates a new Extractor with the given options.
+    #
+    # @option options [String] :file the extract configuration file name
+    # @option options [String] :name name of this Migrator (default is +caTissue Migrator+)
+    # @option options [String] :output optional output CSV file name
+    # @option options [String] :target required target domain class or class name
+    # @option options [String] :ids the database identifiers of the target objects to extract
+    # @option options [String] :log log file (default +log/extract.log+)
+    def initialize(options={})
+      conf_file = options.delete(:file)
+      if conf_file then
+        CaRuby::Properties.new(conf_file, :array => [:shims]).each { |key, value| options[key.to_sym] ||= value }
+      end
+      # tailor the options
+      name = options[:name] || DEF_NAME
+      super(name)
+      @ids = options[:ids]
+      raise ArgumentError.new("Missing required ids option") unless @ids
+      # convert the required target to a CaTissue class if necessary
+      @target = target_class_from_option(options[:target])
+      @target ||= CaTissue::Specimen
+      # the CSV output file
+      @output = options[:output]
+      raise ArgumentError.new("Missing required extract output file option") unless @output
+      # the field mapping configuration
+      fld_conf = options[:mapping]
+      mapper = CaRuby::CsvMapper.new(fld_conf, @target, @output, :mode => "w")
+      @csvio = mapper.csvio
+      @fld_path_hash = {}
+      mapper.paths.each do |path|
+        fld = mapper.header(path)
+        # the path node is either an attribute symbol or attribute metadata;
+        # if metadata, then use the reader method.
+        @fld_path_hash[fld] = path.map { |attr_or_md| CaRuby::AttributeMetadata === attr_or_md ? attr_or_md.reader : attr_or_md }
+      end
+      logger.debug { "Extract field => path map: #{@fld_path_hash.transform { |path| path.join('.') }.pp_s}" }
+    end
+
+    # Exports the selected target records from the database to the output file.
+    def run
+      begin
+        extract { |obj| write(obj) }
+      ensure
+        @csvio.close
+      end
+    end
+
+    # Executes this extractor CSV file and calls the block given to this method on each target domain object.
+    def extract
+      logger.debug { "Found #{@ids.size} extract targets." }
+      CaTissue::Database.instance.open do
+        @ids.each do |identifier|
+          obj = @target.new(:identifier => identifier)
+          logger.debug { "Finding extract target #{obj}..." }
+          if obj.find then
+            logger.debug { "Extractor fetched #{obj}." }
+            yield obj
+          else
+            logger.debug { "Extract target #{obj} not found." }
+          end
+        end
+      end
+    end
+
+    alias :each :extract
+
+    private
+
+    def write(obj)
+      # collect the field values in order by resolving the path on obj
+      rec = @csvio.headers.map do |fld|
+        obj.path_value(@fld_path_hash[fld])
+      end
+      @csvio << rec
+      logger.debug { "Extractor wrote #{obj} to CSV output file." }
+    end
+
+    def target_class_from_option(option)
+      return if option.nil?
+      return option if Class === option
+      CaTissue.const_get(option)
+    end
+  end
+end

data/lib/catissue/migration/migrator.rb

@@ -0,0 +1,101 @@
+require 'caruby/util/properties'
+require 'caruby/migration/migrator'
+require 'catissue/resource'
+require 'catissue/database/controlled_values'
+require 'catissue/database/controlled_value_finder'
+
+module CaTissue
+  # Even though Migratable is included in CaRuby::Resource, the Migratable methods
+  # are not appended to a CaTissue Resource class since the class already includes
+  # CaRuby::Resource. In Ruby, A include B followed by B include C does not imply
+  # that A includes C. Therefore, notify CaTissue that its mixin has changed and each
+  # loaded class must reinclude the mixin.
+  CaTissue.mixin_changed
+  
+  # Migrates a CSV extract to caTissue. See the {#initialize} documentation for usage options.
+  #
+  # See the Galena Cancer Center Tissue Bank Migration Example for further information
+  # about how the options tailor migration, esp. the use of the field mappings and shims.
+  class Migrator < CaRuby::Migrator
+    # The default name of this migrator.
+    NAME = 'caTissue Migrator'
+
+    DEF_CONF_FILE = File.join('conf', 'migration.yaml')
+
+    # The built-in caTissue migration shims.
+    SHIM_FILE = File.join(File.dirname(__FILE__), 'shims.rb')
+
+    # Creates a new Migrator with the given options.
+    #
+    # This migrator must include sufficient information to build a well-formed migration target object.
+    # For example, if the target object is a new SpecimenCollectionGroup, then the migration must also be
+    # able to build that SCG's CollectionProtocolRegistration. The CPR in turn must either exist in the
+    # database or the migration must build a Participant and a CollectionProtocol.
+    # 
+    # @option (see CaRuby::Migrator#initialize)
+    def initialize(opts={})
+      # if there is a configuration file, then add config options into the parameter options
+      conf_file = opts.delete(:file)
+      if conf_file then
+        conf = CaRuby::Properties.new(conf_file, :array => [:shims])
+        # add config options but don't override the parameter options
+        opts.merge!(conf, :deep) { |key, oldval, newval| oldval }
+      end
+      
+      
+      # TODO - move opt parsing to CaTissue::CLI::Migrate and call that from test cases
+      # Migrate then calls this Migrator with parsed options
+      
+      
+      # open the log file before building structure
+      log_file = opts[:log]
+      CaRuby::Log.instance.open(log_file, :debug => opts[:debug]) if log_file
+
+      # tailor the options
+      opts[:name] ||= NAME
+      opts[:database] ||= CaTissue::Database.instance
+      # prepend this migrator's shims
+      shims = opts[:shims] ||= []
+      shims.unshift(SHIM_FILE)
+
+      # call the CaRuby::Migrator initializer with the augmented options
+      super
+
+      # the options specific to this CaTissue::Migrator subclass
+      tissue_sites = opts[:tissue_sites]
+      if tissue_sites then
+        CaTissue::SpecimenCharacteristics.tissue_site_cv_finder = ControlledValueFinder.new(:tissue_site, tissue_sites)
+        logger.info("Migrator enabled controlled value lookup.")
+      end
+      diagnoses = opts[:diagnoses]
+      if diagnoses then
+        CaTissue::SpecimenCollectionGroup.diagnosis_cv_finder = ControlledValueFinder.new(:clinical_diagnosis, diagnoses)
+        logger.info("Migrator enabled controlled value lookup.")
+      end
+    end
+
+    private
+    
+    # Clears the migration protocol CPR and SCG references.
+    # This action frees up memory for the next iteration, thereby ensuring that migration is an
+    # O(1) rather than O(n) operation.
+    def clear(target)
+      pcl = target_protocol(target) || return
+      logger.debug { "Clearing #{pcl.qp} CPR and SCG references..." }
+      pcl.suspend_lazy_loader do
+        pcl.registrations.clear
+        pcl.events.each { |event| event.suspend_lazy_loader { event.specimen_collection_groups.clear } }
+      end
+    end
+    
+    def target_protocol(target)
+      case target
+      when CaTissue::SpecimenCollectionGroup then
+        cpe = target.collection_protocol_event
+        cpe.collection_protocol if cpe
+      when CaTissue::Specimen then
+        target_protocol(target.specimen_collection_group)
+      end
+    end
+  end
+end