caruby-tissue 1.2.1

data/lib/catissue/domain/abstract_domain_object.rb

@@ -0,0 +1,8 @@
+module CaTissue
+  # explicitly import AbstractDomainObject, since it is not in the default CaTissue package and therefore can't be auto-imported
+  java_import('edu.wustl.common.domain.AbstractDomainObject')
+
+  class AbstractDomainObject
+    include Resource
+  end
+end

data/lib/catissue/domain/abstract_position.rb

@@ -0,0 +1,22 @@
+require 'catissue/util/position'
+
+module CaTissue
+  java_import('edu.wustl.catissuecore.domain.AbstractPosition')
+
+  # The +caTissue+ AbstractPosition class is augmented with a comparison operator and the
+  # zero-based +row+ and +column+ methods wrapping the corresponding one-based dimension
+  # attributes. Each AbstractPosition is required to implement the +holder+ and +occupant+
+  #�methods.
+  class AbstractPosition
+    include Position, Resource
+
+    add_mandatory_attributes(:position_dimension_one, :position_dimension_two)
+
+    # Column and row are the zero-offset counterparts of position_dimension_one and
+    # position_dimension_two, resp.
+    offset_attribute(:column => :position_dimension_one, :row => :position_dimension_two)
+
+    # add the synthetic {#location} attribute
+    add_attribute(:location)
+  end
+end

data/lib/catissue/domain/abstract_specimen.rb

@@ -0,0 +1,288 @@
+require 'set'
+require 'caruby/util/inflector'
+
+module CaTissue
+  java_import('edu.wustl.catissuecore.domain.AbstractSpecimen')
+
+  class AbstractSpecimen
+    include Resource
+
+    # Sets the specimen type to the specified value. The value can be a permissible caTissue String value or
+    # the shortcut symbols :fresh, :fixed and :frozen.
+    def specimen_type=(value)
+      value = value.to_s.capitalize_first + ' Tissue' if Symbol === value
+      setSpecimenType(value)
+    end
+
+    add_attribute_aliases(:parent => :parent_specimen,
+     :children => :child_specimens,
+     :events => :specimen_events,
+     :specimen_event_parameters => :specimen_events,
+     :event_parameters => :specimen_events,
+     :characteristics => :specimen_characteristics)
+
+    # caTissue alert - initial_quantity must be set (cf. Bug #160)
+    add_attribute_defaults(:initial_quantity => 0.0, :pathological_status => 'Not Specified', :specimen_type => 'Not Specified')
+
+    add_mandatory_attributes(:lineage, :pathological_status, :specimen_class, :specimen_type)
+
+    # Specimen characteristics are auto-generated but SpecimenRequirement characteristics are not.
+    # It is safe to set the :autogenerated flag for both AbstractSpecimen subclasses. This results
+    # in an unnecessary SpecimenRequirement create database query, but SpecimenRequirement create
+    # is rare and there is no harm.
+    #
+    # caTissue alert - Bug 166: API update Specimen ignores characteristics with different id.
+    # Guard against updating a Specimen with a SpecimenCharacteristics whose id differs from
+    # the existing id.
+    #
+    # The :no_cascade_update_to_create flag is set since characteristics have cascade style 'all'.
+    add_dependent_attribute(:specimen_characteristics, :autogenerated, :no_cascade_update_to_create)
+
+    add_dependent_attribute(:specimen_events, :create_only, :disjoint, :no_cascade_update_to_create)
+    
+    set_attribute_inverse(:parent_specimen, :child_specimens)
+    
+    # caTissue alert - SCG specimens query result does not set the Specimen children and parent, even though they are
+    # guaranteed to be in the SCG specimens result set. The children and parent must be fetched separately, resulting
+    # in multiple copies of the same Specimen and additional fetches.
+    qualify_attribute(:parent_specimen)
+    qualify_attribute(:child_specimens, :no_cascade_update_to_create)
+
+    class SpecimenClass
+      TISSUE = 'Tissue'
+      FLUID = 'Fluid'
+      MOLECULAR = 'Molecular'
+      CELL = 'Cell'
+
+      EXTENT = Set.new([TISSUE, FLUID, MOLECULAR, CELL])
+
+      UNIT_HASH = {TISSUE => 'gm', FLUID => 'ml', MOLECULAR => 'ug'}
+
+      # @return whether the value is an accepted tissue class value
+      def self.include?(value)
+        EXTENT.include?(value)
+      end
+    end
+
+    def initialize(params=nil)
+      super
+      self.specimen_class ||= infer_specimen_class(self.class)
+    end
+
+    # @return whether this specimen is derived from a parent specimen
+    def derived?
+      not parent.nil?
+    end
+
+    # @return whether this specimen is an aliquot
+    def aliquot?
+      lineage ||= default_lineage
+      lineage == 'Aliquot'
+    end
+
+    # @return this specimen's aliquots
+    def aliquots
+      children.filter { |child| child.aliquot? }
+    end
+
+    # @return whether this specimen's type is 'Fresh Tissue'
+    def fresh?
+      specimen_type == 'Fresh Tissue'
+    end
+
+    # @return whether this specimen's type starts with 'Fixed'
+    def fixed?
+      specimen_type =~ /^Fixed/
+    end
+
+    # @return whether this specimen's type starts with 'Frozen'
+    def frozen?
+      specimen_type =~ /^Frozen/
+    end
+
+    # @return <AbstractSpecimen> the transitive closure consisting of this AbstractSpecimen
+    # and all AbstractSpecimen in the derivation hierarcy.
+    def closure
+      children.inject([self]) { |coll, spc| coll.concat(spc.closure) }
+    end
+
+    # Returns the standard unit for this specimen
+    def standard_unit
+      self.specimen_class ||= infer_specimen_class(self.class)
+      SpecimenClass::UNIT_HASH[self.specimen_class]
+    end
+
+    # Derives a specimen from this specimen. The params are described in {Specimen#create_specimen},
+    # with one addition: an optional :count, the optional number of specimens to derive.
+    #
+    # If the :count parameter is greater than one and the :specimen_class,
+    # :specimen_type and :specimen_characteristics parameters are not set to values
+    # which differ from the respective values for this Specimen, then the specimen is
+    # aliquoted, otherwise the derived specimens are created independently, e.g.:
+    #   spc = Specimen.create_specimen(:specimen_class => :tissue, :specimen_type => :frozen)
+    #   spc.derive(:count => 1) #=> not aliquoted
+    #   spc.derive(:count => 2) #=> aliquoted
+    #   spc.derive(:specimen_type => 'Frozen Specimen') #=> two aliquots
+    #
+    # The default derived _initial_quantity_ is the parent specimen _available_quantity_
+    # divided by _count_ for aliquots, zero otherwise. If the child _specimen_class_
+    # is the same as this Specimen class, then this parent Specimen's _available_quantity_
+    # is decremented by the child _initial_quantity_, e.g.:
+    #   spc.available_quantity #=> 4
+    #   spc.derive(:initial_quantity => 1)
+    #   spc.available_quantity #=> 3
+    #   spc.derive(:count => 2, :specimen_type => 'Frozen Tissue')
+    #   spc.derive(:count => 2) #=> two aliquots with quantity 1 each
+    #   spc.available_quantity #=> 0
+    #
+    # The default derived specimen label is _label_+_+_n_, where _label_ is this specimen's
+    # label and _n_ is this specimen's child count after including the new derived specimen,
+    # e.g. 3090_3 for the third child in parent specimen with label 3090.
+    #
+    # @return the new derived specimen if _count_ is one, otherwise an Array of _count_ derived specimens
+    #
+    # Raises ValidationError if an aliquoted parent _available_quantity_ is not greater than zero
+    # or the derived specimen quantities exceed the parent _available_quantity_.
+    def derive(params={})
+      # add defaults
+      add_defaults if specimen_class.nil?
+      # copy the parameters
+      params = params.dup
+      # standardize the requirement param, if any
+      rqmt = params.delete(:requirement)
+      params[:specimen_requirement] ||= rqmt if rqmt
+      # the default specimen parameters
+      unless params.has_key?(:specimen_requirement) then
+        params[:specimen_class] ||= self.specimen_class ||= infer_specimen_class
+        params[:specimen_type] ||= self.specimen_type
+      end
+      unless Class === params[:specimen_class] then
+        params[:specimen_class] = infer_class(params)
+      end
+      count = params.delete(:count)
+      count ||= 1
+      aliquot_flag = false
+      if count > 1 and params[:specimen_class] == self.class and params[:specimen_type] == self.specimen_type then
+        # aliquots share the specimen_characteristics
+        child_chr = params[:specimen_characteristics] ||= self.specimen_characteristics
+        aliquot_flag = child_chr == self.specimen_characteristics
+      end
+      # set aliquot parameters if necessary
+      if aliquot_flag then set_aliquot_parameters(params, count) end
+      # make the derived specimens
+      count == 1 ? create_derived(params) : Array.new(count) { create_derived(params) }
+    end
+
+    # Returns whether this AbstractSpecimen is minimally consistent with the other specimen.
+    # This method augments the {CaRuby::Resource#minimal_match?} with an additional restriction
+    # that the other specimen is the same type as this specimen and
+    # is a tolerant match on specimen class, specimen type and pathological status.
+    # A _tolerant_ match condition holds if the other attribute value is equal to this
+    # AbstractSpecimen's attribute value or the other value is the default 'Not Specified'.
+    #
+    # @param (see CaRuby::Resource#minimal_match?)
+    # @return (see CaRuby::Resource#minimal_match?)
+    def minimal_match?(other)
+      super and tolerant_match?(other, TOLERANT_MATCH_ATTRS)
+    end
+    
+    private
+    
+    TOLERANT_MATCH_ATTRS = [:specimen_class, :specimen_type, :pathological_status]
+
+    # The attributes which can be merged as defaults from a parent into a derived child Specimen.
+    DERIVED_MERGEABLE_ATTRS = [:activity_status, :pathological_status, :specimen_class, :specimen_type]
+
+    # Sets special aliquot parameters for the given count of aliquots.
+    # This default implementation is a no-op. Subclasses can override.
+    def set_aliquot_parameters(params, count); end
+
+    def add_defaults_local
+      super
+      # parent pathological status is preferred over the configuration defaults
+      self.pathological_status ||= parent.pathological_status if parent
+      # the configuration defaults
+      # set the required but redundant tissue class and lineage values
+      self.specimen_class ||= infer_specimen_class(self.class)
+      self.lineage ||= default_lineage
+      # copy the parent characteristics or add empty characteristics
+      self.characteristics ||= default_characteristics
+    end
+
+    # Returns the Class from the given params hash.If the :specimen_class parameter
+    # is set to a Class, then this method returns that Class. Otherwise, if the parameter is a
+    # String or Symbol, then the Class is formed from the parameter as a prefix and 'Specimen' or
+    # 'SpecimenRequirement' depending on this AbstractSpecimen's subclass. If the
+    # :specimen_class parameter is missing and there is a :specimen_requirement parameter,
+    # then the specimen requirement specimen_class attribute value is used.
+    def infer_class(params)
+      opt = params[:specimen_class]
+      if opt.nil? then
+        rqmt = params[:specimen_requirement]
+        opt = rqmt.specimen_class if rqmt
+      end
+      raise ArgumentError.new("Specimen class is missing from the create parameters") if opt.nil?
+      return opt if Class === opt
+      # infer the specimen domain class from the specimen_class prefix and Specimen or SpecimenRequirement suffix
+      cls_nm = opt.to_s.capitalize_first + 'Specimen'
+      cls_nm += 'Requirement' if CaTissue::SpecimenRequirement === self
+      CaTissue.domain_type_with_name(cls_nm)
+    end
+
+    def create_derived(params)
+      # Merge the non-domain attribute values from this specimen, unless there is a requirement.
+      # Precedence order is given params highest, requirements next, this specimen lowest
+      params = value_hash(DERIVED_MERGEABLE_ATTRS).merge!(params) unless params.has_key?(:specimen_requirement)
+      # copy this specimen's characteristics if not already given in the derived specimen params
+      params[:specimen_characteristics] ||= default_derived_characteristics
+      # make the new specimen
+      spc = Specimen.create_specimen(params)
+      # set the parent
+      spc.parent = self
+      spc
+    end
+
+    # @return a copy of this Specimen's specimen_characteristics, or nil if none
+    # The new SpecimenCharacteristics does not have an identifier.
+    def default_derived_characteristics
+      chrs = specimen_characteristics || return
+      attrs = chrs.class.nondomain_attributes.reject { |attr| attr == :identifier }
+      chrs.copy(attrs)
+    end
+
+    # @return a copy of the parent characteristics, if any, or a new SpecimenCharacteristics otherwise
+    def default_characteristics
+      if parent and parent.characteristics then
+        parent.characteristics.copy
+      else
+        CaTissue::SpecimenCharacteristics.new
+      end
+    end
+
+    # Returns the the default lineage value computed as follows:
+    # * if there is no parent specimen, then 'New'
+    # * otherwise, if this Specimen's specimen_characteristics object is identical to that of
+    #   the parent, then 'Aliquot'
+    # * otherwise, 'Derived'
+    # The aliquot condition requires that the specimen_characteristics is the same object,
+    # not just the same content. This odd condition is a caTissue artifact. A more sensible
+    # criterion is whether this Specimen and its parent share the same tissue_class and
+    # tissue_type, but so it goes.
+    def default_lineage
+      if parent.nil? then
+        'New'
+      elsif specimen_characteristics.equal?(parent.specimen_characteristics) then
+        'Aliquot'
+      else
+        'Derived'
+      end
+    end
+
+    # Infers the specimen class from the first word on the specified klass Ruby class name.
+    # For example:
+    #   infer_specimen_class(CaTissue::TissueRequirement) #=> "Tissue"
+    def infer_specimen_class(klass=self.class)
+      klass.to_s[/(\w+?)(Specimen(Requirement)?)$/, 1] if klass
+    end
+  end
+end

data/lib/catissue/domain/abstract_specimen_collection_group.rb

@@ -0,0 +1,25 @@
+module CaTissue
+  java_import('edu.wustl.catissuecore.domain.AbstractSpecimenCollectionGroup')
+
+  class AbstractSpecimenCollectionGroup
+    include Resource
+
+    add_attribute_aliases(:site => :specimen_collection_site, :collection_site => :specimen_collection_site, :diagnosis => :clinical_diagnosis)
+
+    add_attribute_defaults(:activity_status => 'Active', :clinical_status => 'Not Specified', :clinical_diagnosis => 'Not Specified')
+
+    add_mandatory_attributes(:activity_status)
+    
+    qualify_attribute(:collection_site, :fetched)
+
+    # Overrides {CaRuby::Resource#each_dependent} to exclude Specimens or SpecimenRequirements with a parent,
+    # since parent is the immediate Specimen or SpecimenRequirement owner.
+    #
+    # @yield (see CaRuby::Resource#each_dependent)
+    # @yieldparam (see CaRuby::Resource#each_dependent)
+    def each_dependent
+      super { |dep| yield dep unless AbstractSpecimen === dep and dep.parent }
+    end
+
+  end
+end

data/lib/catissue/domain/address.rb

@@ -0,0 +1,13 @@
+module CaTissue
+  java_import('edu.wustl.catissuecore.domain.Address')
+
+  class Address
+    include Resource
+
+    # Sets this Address's zip_code to value. The value argument can be nil, a String or an Integer.
+    def zip_code=(value)
+      value = value.to_s if Integer === value
+      setZipCode(value)
+    end
+  end
+end

data/lib/catissue/domain/cancer_research_group.rb

@@ -0,0 +1,11 @@
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.CancerResearchGroup')
+
+  # The CancerResearchGroup domain class.
+  class CancerResearchGroup
+    include Resource
+
+    set_secondary_key_attributes(:name)
+  end
+end

data/lib/catissue/domain/capacity.rb

@@ -0,0 +1,34 @@
+require 'caruby/util/coordinate'
+
+module CaTissue
+  java_import('edu.wustl.catissuecore.domain.Capacity')
+
+  class Capacity
+    include Resource
+
+    # Sets the first dimension to the specified value. If value is nil, then the dimension is set to default one.
+    def one_dimension_capacity=(value)
+       # update the bounds as well
+      bounds.x = value ||= 1
+      setOneDimensionCapacity(value)
+    end
+
+    # Sets the second dimension to the specified value. If value is nil, then the dimension is set to default one.
+    def two_dimension_capacity=(value)
+       # update the bounds as well
+      bounds.y = value ||= 1
+      setTwoDimensionCapacity(value)
+    end
+
+    add_attribute_aliases(:columns => :one_dimension_capacity, :rows => :two_dimension_capacity)
+
+    add_attribute_defaults(:one_dimension_capacity => 1, :two_dimension_capacity => 1)
+
+    add_mandatory_attributes(:one_dimension_capacity, :two_dimension_capacity)
+
+    # Returns the read-only Coordinate with this Capacity's #rows and {#columns}.
+    def bounds
+      @bounds ||= Coordinate.new(columns, rows)
+    end
+  end
+end

data/lib/catissue/domain/check_in_check_out_event_parameter.rb

@@ -0,0 +1,19 @@
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.CheckInCheckOutEventParameter')
+
+  class CheckInCheckOutEventParameter
+    include Resource
+
+    # The check-in/check-out status permissible values.
+    module Status
+      CHECKED_OUT = 'CHECK OUT'
+      CHECKED_IN = 'CHECK IN'
+    end
+
+    add_attribute_aliases(:status => :storage_status, :state => :storage_status)
+
+    add_mandatory_attributes(:storage_status)
+
+  end
+end

data/lib/catissue/domain/collection_event_parameters.rb

@@ -0,0 +1,13 @@
+require 'catissue/domain/scg_event_parameters'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.CollectionEventParameters')
+
+  class CollectionEventParameters
+    include Resource, SCGEventParameters
+
+    add_attribute_defaults(:collection_procedure => 'Not Specified', :container => 'Not Specified')
+
+  end
+end