caruby-tissue 1.5.4 → 1.5.5

data/lib/catissue/domain/storage_container.rb

@@ -47,9 +47,11 @@ module CaTissue
 
     set_attribute_type(:holds_storage_types, CaTissue::StorageType)
 
+    # @quirk caTissue Bug #64 - specimen positions is not initialized to an empty set
+    #    in the Java constructor. Initialize it to a +LinkedHashSet+ in caRuby.
     def initialize
       super
-      # @quirk JRuby specimen_positions is not recognized unless primed with respond_to? call
+      # @quirk JRuby specimen_positions is not recognized until respond_to? is called
       respond_to?(:specimen_positions)
       # work around caTissue Bug #64
       self.specimen_positions ||= Java::JavaUtil::LinkedHashSet.new
@@ -121,7 +123,8 @@ module CaTissue
     # {StorageTypeHolder#child_types} override allowed by caTissue.
     #
     # @param [Storable] (see #add)
-    # @return [Boolean] whether this container is not full and can hold the given item's storable type
+    # @return [Boolean] whether this container is not full and can hold the given item's
+    #   {CaTissue::StorableType}
     def can_hold_child?(storable)
       st = storable.storable_type
       not full? and child_types.any? { |ct| CaRuby::Resource.value_equal?(ct, st) }

data/lib/catissue/domain/storage_type.rb

@@ -58,7 +58,7 @@ module CaTissue
     #
     # @param other the object to compare
     # @return [Boolean] whether this StorageType has a non-nil name equal to the other name or
-    #   is the same as this StorageType
+    #   is {#equal?} to this StorageType
      def ==(other)
       equal?(other) or (StorageType === other and name and name == other.name)
     end

data/lib/catissue/domain/user.rb

@@ -9,7 +9,7 @@ module CaTissue
   # The User domain class.
   #
   # @quirk caTissue caTissue 1.2 User has an adminuser Java property, but caTissue throws an
-  #   UnsupportedOperationException if they are called.
+  #   +UnsupportedOperationException+ if they are called.
   # @quirk caTissue clinical study is unsupported by 1.1.x caTissue, removed in 1.2.
   # @quirk caTissue obscure GUI artifact User page_of attribute pollutes the data layer as a
   #   required attribute. Work-around is to simulate the GUI with a default value.
@@ -45,15 +45,18 @@ module CaTissue
       setRoleId(value_s)
     end
 
-    remove_attribute(:adminuser) if attribute_defined?(:adminuser)
+    # @quirk caTissue caTissue 1.2 User has an adminuser Java property, but caTissue throws an
+    #   UnsupportedOperationException if they are called.
+    if attribute_defined?(:adminuser) then remove_attribute(:adminuser) end
 
-    # Makes the convenience +CaRuby::Person::Name+ name a first-class attribute.
+    # make the convenience {, CaRuby::Person::Name} name a first-class attribute
     add_attribute(:name, CaRuby::Person::Name)
 
-    remove_attribute(:clinical_studies) if attribute_defined?(:clinical_studies)
+    # @quirk caTissue clinical study is unsupported by 1.1.x caTissue, removed in 1.2.
+    if attribute_defined?(:clinical_studies) then remove_attribute(:clinical_studies) end
 
-    # Clarify that collection_protocols is a coordinator -> protocol association.
-    # Make assigned protocol and site attribute names consistent.
+    # 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.
@@ -68,10 +71,16 @@ module CaTissue
     # * initial password is 'changeMe1'
     add_attribute_defaults(:activity_status => 'Active', :page_of => 'pageOfUserAdmin', :role_id => 7, :new_password => 'changeMe1')
 
+    # @quirk caTissue obscure GUI artifact User page_of attribute pollutes 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)
 
-    # Adding the :saved_fetch qualifier results in JRuby load_error. TODO - fix this.
+    # @quirk caTissue User address can be created but not updated in 1.2.
+    #
+    # @quirk caTissue User address is not fetched on create in 1.2.
+    #
+    # @quirk caRuby adding the :saved_fetch qualifier results in JRuby load_error. TODO - fix this.
     add_dependent_attribute(:address)
 
     # Password cannot be saved in 1.2.

data/lib/catissue/extract/command.rb

@@ -9,7 +9,7 @@ module CaTissue
     # 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.
+    # 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

data/lib/catissue/extract/delta.rb

@@ -10,12 +10,9 @@ module CaTissue
   class Delta
     include Enumerable
 
-    # Initializes this delta for objects of the given target type which changed
-    # at or after the since date and earlier than the before date.
-    #
-    # @param [Class] target the type for which the delta is determined
-    # @param [Date] since the delta start time
-    # @param [Date, nil] since the delta end time (default now)
+    # 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)
@@ -25,21 +22,17 @@ module CaTissue
 
     # 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 capturing
-    # the result if necessary for a subsequent iteration.
-    #
-    # @yield [identifier] filters the Resources changed in the delta window
-    # @yieldparam [Integer] identifier the Resource database id
+    # 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
 
-    # The parameterized SQL for determining
     SQL_FILE = File.join(File.dirname(__FILE__), '..', '..', '..', 'sql', 'delta.sql')
 
-    # @return [<Resource>] the result of running the delta SQL on the target CaTissue domain class
+    # 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}" }
@@ -51,8 +44,7 @@ module CaTissue
       end
     end
 
-    # @param [Class] the target domain class
-    # @return [RegularExpression, nil] the table match RE for the given target class, if any
+    # 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.

data/lib/catissue/migration/migratable.rb

@@ -1,20 +1,118 @@
-require 'caruby/migration/migratable'
+require 'caruby/migration/migrator'
+require 'catissue/annotation/proxy'
 
 module CaTissue
-  module CollectibleEventParameters
-    
+  shims SpecimenCollectionGroup, CollectionProtocolRegistration, SpecimenCharacteristics,
+    SpecimenEventParameters, CollectionEventParameters, ReceivedEventParameters
+
+  class SpecimenCollectionGroup
+    @@diagnosis_cv_finder = nil
+
+    # Sets this SpecimenCollectionGroup diagnosis ControlledValueFinder.
+    def self.diagnosis_cv_finder=(finder)
+      @@diagnosis_cv_finder = finder
+    end
+
+    # Returns the diagnosis controlled value as follows:
+    # * If CV lookup is disabled, then this method returns value.
+    # * Otherwise, if the value is remapped via a configuration remap file,
+    #   then this method returns the remapped CV.
+    # * Otherwise, if the value is a valid CV, then this method returns value.
+    # * Otherwise, this method returns nil.
+    #
+    # @param [String] value the input diagnosis
+    # @return [String] the mapped CV
+    def self.diagnosis_controlled_value(value)
+      @@diagnosis_cv_finder.nil? ? value : @@diagnosis_cv_finder.controlled_value(value)
+    end
+
+    # @return [String] the {diagnosis_controlled_value}
+    def migrate_clinical_diagnosis(value, row)
+      SpecimenCollectionGroup.diagnosis_controlled_value(value)
+    end
+  end
+
+  class SpecimenCharacteristics
+    @@tissue_site_cv_finder = nil
+
+    # Sets this SpecimenCharacteristics tissue site ControlledValueFinder.
+    def self.tissue_site_cv_finder=(finder)
+      @@tissue_site_cv_finder = finder
+    end
+
+    # Returns the tissue site controlled value as follows:
+    # * If CV lookup is disabled, then this method returns value.
+    # * Otherwise, if the value is remapped via a configuration remap file,
+    #   then this method returns the remapped CV.
+    # * Otherwise, if the value is a valid CV, then this method returns value.
+    # * Otherwise, this method returns nil.
+    #
+    # @return [String] the caTissue tissue site permissible value
+    def self.tissue_site_controlled_value(value)
+      @@tissue_site_cv_finder.nil? ? value : @@tissue_site_cv_finder.controlled_value(value)
+    end
+
+    # @return [String] the {tissue_site_controlled_value}
+    def migrate_tissue_site(value, row)
+      standard_cv_tissue_site(value) or variant_cv_tissue_site(value)
+    end
+
     private
+
+    # Returns the {tissue_site_controlled_value}.
+    #
+    # @return the caTissue tissue site permissible value
+    def standard_cv_tissue_site(value)
+      SpecimenCharacteristics.tissue_site_controlled_value(value)
+    end
+
+    # Returns the {tissue_site_controlled_value} which adds the 'NOS' suffix to a value
+    # without one or removes 'NOS' from a value with the suffix.
+    #
+    # @return the caTissue tissue site permissible value
+    def variant_cv_tissue_site(value)
+      # try an NOS suffix variation
+      variation = value =~ /, NOS$/ ? value[0...-', NOS'.length] : value + ', NOS'
+      cv = SpecimenCharacteristics.tissue_site_controlled_value(variation)
+      logger.warn("Migrator substituted tissue site #{cv} for #{value}.") if cv
+      cv
+    end
+  end
+
+  class SpecimenEventParameters
+    # Returns nil by default, since only CollectibleEventParameters have a SCG owner.
+    # {CollectibleEventParameters#migrate_specimen_collection_group} overrides this method.
+    #
+    # @return nil
+    def migrate_specimen_collection_group(scg, row)
+      nil
+    end
+  end
+
+  module CollectibleEventParameters
+    #@param [SpecimenCollectionGroup] scg the migrated owner SCG
+    # @return [SpecimenCollectionGroup] scg
+    # @see SpecimenEventParameters#migrate_specimen_collection_group
+    def migrate_specimen_collection_group(scg, row)
+      # unset the specimen parent if necessary
+      self.specimen = nil if specimen and scg
+      scg
+    end
     
-    # Overrides +CaRuby::Migratable.migratable__target_value+ to confer precedence to
+    # Returns the given Specimen spc unless this CollectibleEventParameters already has a SCG owner.
+    # A CollectibleEventParameters is preferentially set to a migrated SCG rather than a migrated
+    # Specimen.
+    #
+    # Overrides {CaRuby::Migratable#migratable__target_value} to confer precedence to
     # a SCG over a Specimen when setting this event parameters' owner. If the migrated
     # collection includes both a Specimen and a SCG, then this event parameters
     # +specimen+ reference is ambiguous, but the +specimen_collection_group+ reference
     # is not.
     #
-    # @param (see CaRuby::Migratable#migratable__target_value)
-    # @return (see CaRuby::Migratable#migratable__target_value)
-    def migratable__ambiguous_owner?(attr_md, migrated)
-      super and attr_md.to_sym != :specimen_collection_group
+    #@param [Specimen] spc the migrated owner specimen
+    # @return [Specimen, nil] spc unless there is already a SCG owner
+    def migrate_specimen(spc, row)
+      spc unless specimen_collection_group
     end
   end
 end

data/lib/catissue/migration/migrator.rb

@@ -1,6 +1,5 @@
 require 'caruby/util/properties'
 require 'caruby/migration/migrator'
-require 'catissue/migration/migratable'
 require 'catissue/resource'
 require 'catissue/database/controlled_values'
 require 'catissue/database/controlled_value_finder'
@@ -11,12 +10,6 @@ module CaTissue
   # 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'
-
-    # 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.
@@ -25,7 +18,9 @@ module CaTissue
     # database or the migration must build a Participant and a CollectionProtocol.
     # 
     # @option (see CaRuby::Migrator#initialize)
-    # @option opts [String] :database target application database
+    # @option opts [String] :tissue_sites the tissue site mapping file
+    # @option opts [String] :diagnoses the diagnosis mapping file
+    # @option opts [String] :database target application {CaRuby::Database}
     # @option opts [String] :target required target domain class
     # @option opts [String] :input required source file to migrate
     # @option opts [String] :shims optional array of shim files to load
@@ -48,9 +43,15 @@ module CaTissue
       # tailor the options
       opts[:name] ||= NAME
       opts[:database] ||= CaTissue::Database.instance
-      # prepend this migrator's shims
+      
+      # the shims file(s)
+      opts[:shims] ||= []
       shims = opts[:shims] ||= []
-      shims.unshift(SHIM_FILE)
+      # make a single shims file into an array
+      shims = opts[:shims] = [shims] unless shims.collection?
+      # prepend this migrator's shims
+      shims.unshift(MIGRATABLE_SHIM)
+
       # If the unique option is set, then append the CaTissue-specific uniquifier shim.
       if opts[:unique] then
         # add the uniquify shim
@@ -79,12 +80,19 @@ module CaTissue
     end
 
     private
+    # The default name of this migrator.
+    NAME = 'caTissue Migrator'
+
+    # The built-in caTissue migration shims.
+    MIGRATABLE_SHIM = File.join(File.dirname(__FILE__), 'migratable.rb')
     
     UNIQUIFY_SHIM = File.join(File.dirname(__FILE__), 'uniquify')
         
     # The context module is determined as follows:
-    # * for an {Annotation} target class, the context module is the annotated class's {ResourceClass#domain_module}
-    # * otherwise, delegate to +CaRuby::Migrator+.
+    # * For an {Annotation} target class, the context module is the annotated class's domain_module.
+    # * Otherwise, delegate to +CaRuby::Migrator+.
+    # * For an {Annotation} target class, the context module is the annotated class's {ResourceClass#domain_module}.
+    # * Otherwise, delegate to {CaRuby::Migrator}.
     #
     # @return (see CaRuby::Migrator#context_module)
     def context_module

data/lib/catissue/migration/shims.rb

@@ -25,7 +25,7 @@ module CaTissue
       @@diagnosis_cv_finder.nil? ? value : @@diagnosis_cv_finder.controlled_value(value)
     end
 
-    # @return [String] the {diagnosis_controlled_value}
+    # @return [String] the {#diagnosis_controlled_value}
     def migrate_clinical_diagnosis(value, row)
       SpecimenCollectionGroup.diagnosis_controlled_value(value)
     end
@@ -46,12 +46,12 @@ module CaTissue
     # * Otherwise, if the value is a valid CV, then this method returns value.
     # * Otherwise, this method returns nil.
     #
-    # @return [String] the caTissue tissue site permissible value
+    # @return the caTissue tissue site permissible value
     def self.tissue_site_controlled_value(value)
       @@tissue_site_cv_finder.nil? ? value : @@tissue_site_cv_finder.controlled_value(value)
     end
 
-    # @return [String] the {tissue_site_controlled_value}
+    # Returns the {#tissue_site_controlled_value}.
     def migrate_tissue_site(value, row)
       standard_cv_tissue_site(value) or variant_cv_tissue_site(value)
     end

data/lib/catissue/util/collectible.rb

@@ -1,7 +1,7 @@
 require 'caruby/util/validation'
 
 module CaTissue
-  # A Collectible mix-in instance can hold a #{ReceivedEventParameters} and a #{CollectionEventParameters}.
+  # A Collectible mix-in instance can hold a #{ReceivedEventParameters} and a #{CollectedEventParameters}.
   module Collectible
     # Builds this collectible domain object's SpecimenEventParameters from atomic parameters.
     #
@@ -71,7 +71,7 @@ module CaTissue
     
     private
    
-    #  Overrides +CaRuby::Resource.each_defaults_dependent+ to visit the {ReceivedEventParameters}.
+    #  Overrides {CaRuby::Resource#each_defaults_dependent} to visit the {CaTissue::ReceivedEventParameters}.
     #
     # @yield (see CaRuby::Resource#each_defaults_dependent)
     def each_defaults_dependent

data/lib/catissue/util/collectible_event_parameters.rb

@@ -4,7 +4,7 @@ module CaTissue
   # or receival at the tissue bank.
   module CollectibleEventParameters
     # Returns the SpecimenEventParameters in others which matches this CollectibleEventParameters in the scope of an owner Specimen or SCG.
-    # This method relaxes +CaRuby::Resource.match_in_owner_scope+ for a CollectibleEventParameters that matches any SpecimenEventParameters
+    # This method relaxes {CaRuby::Resource#match_in_owner_scope} for a CollectibleEventParameters that matches any SpecimenEventParameters
     # in others of the same class, since there can be at most one CollectibleEventParameters of a given class for a given SCG.
     def match_in_owner_scope(others)
       others.detect { |other| minimal_match?(other) }
@@ -44,7 +44,7 @@ module CaTissue
       end
     end
     
-    # Overrides +CaRuby::Migratable.migratable__migrate_owner+ to give owner preference to a migrated SCG
+    # Overrides {CaRuby::Migratable#migratable__migrate_owner} to give owner preference to a migrated SCG
     # over a migrated Specimen.
     #
     # @param (see CaRuby::Migratable#migratable__migrate_owner)

data/lib/catissue/util/position.rb

@@ -15,12 +15,12 @@ module CaTissue
       self.class === other and occupant == other.occupant and location == other.location
     end
 
-    # @return [Coordinate] the read-only coordinate with this position's row and column.
+    # @return [Coordinate] the read-only coordinate with this AbstractPosition's #row and {#column}.
     def coordinate
       location.coordinate
     end
     
-    # @return [Location] the location of this position
+    # @return [Location] the location of this Position
     def location
       @location ||= Location.new
       # always ensure that the location is consistent with the Java state
@@ -43,7 +43,7 @@ module CaTissue
       column.nil? or row.nil?
     end
 
-    # @return [(Integer, Integer)] this Position's zero-based (column, row) tuple.
+    # @return [(Integer, Integer)] this Position's zero-based ({#column}, {#row}) tuple.
     def to_a
       [column, row]
     end

data/lib/catissue/version.rb

@@ -1,6 +1,6 @@
 module CaTissue
   # The version of this caRuby Tissue release.
-  VERSION = "1.5.4"
+  VERSION = "1.5.5"
   
   # The supported caTissue release versions.
   CATISSUE_VERSIONS = "1.1.2-1.2"

data/test/lib/catissue/domain/address_test.rb

@@ -21,11 +21,12 @@ class AddressTest < Test::Unit::TestCase
   end
 
   def test_save
-    assert_raises(CaRuby::DatabaseError, "Address save without owner incorrectly saved") { @addr.save }
-    @addr.user = @user
+    # Create the address.
     verify_save(@addr)
+    # Modify the address.
     expected = @addr.street = "#{Uniquifier.qualifier} Elm"
     verify_save(@addr)
+    # Find the address.
     fetched = @addr.copy(:identifier).find
     assert_equal(expected, fetched.street, "Address street not saved")
   end