caruby-tissue 1.2.1

data/lib/catissue/domain/container_position.rb

@@ -0,0 +1,21 @@
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.ContainerPosition')
+
+  class ContainerPosition
+    include Resource
+
+    add_mandatory_attributes(:parent_container)
+
+    add_attribute_aliases(:parent => :parent_container, :holder => :parent_container, :occupant => :occupied_container)
+
+    # Each ContainerPosition has a container and there is only one position per container.
+    set_secondary_key_attributes(:occupied_container)
+
+    set_attribute_inverse(:parent_container, :occupied_positions)
+
+    set_attribute_inverse(:occupied_container, :located_at_position)
+    
+    qualify_attribute(:parent_container, :fetched)
+  end
+end

data/lib/catissue/domain/container_type.rb

@@ -0,0 +1,131 @@
+require 'caruby/util/options'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.ContainerType')
+
+  # The caTissue ContainerType domain class wrapper.
+  # Each {ContainerType} subclass is required to implement the container_class method.
+  #
+  # caTissue alert - the ContainerType and Container class hierarchy is a confusing
+  # olio of entangled relationships. Conceptually, specimens are contained in boxes,
+  # vials and specimen arrays of various types. When specimens are frozen, these
+  # containers are placed on a rack in a freezer.
+  #
+  # This conceptual model is implemented in caTissue as follows:
+  # * The specimen collection container type, e.g. +Citrate Vacutainer+, is captured
+  #   as a {CaTissue::CollectionEventParameters#container} String. There is no separate
+  #   collection container instance or container type instance.
+  # * A tissue specimen storage box is captured as a {CaTissue::StorageContainer}
+  #   instance constrained to a {CaTissue::StorageType} instance. Boxes with different
+  #   types are instances of the same {CaTissue::StorageContainer} class but belong 
+  #   to different {CaTissue::StorageType} instances.
+  # * {CaTissue::SpecimenArray} is a {CaTissue::Container} but not a {CaTissue::StorageContainer}.
+  #   The specimen array class is {CaTissue::SpecimenArray}, but its type is a
+  #   {CaTissue::SpecimenArrayType} instance, which is a {CaTissue::ContainerType} but not
+  #   a {CaTissue::StorageType}.
+  # * A rack is a {CaTissue::StorageContainer} instance whose type is a {CaTissue::StorageType}
+  #   instance which can hold the box {CaTissue::StorageType}.
+  # * A freezer is a {CaTissue::StorageContainer} instance whose type is a {CaTissue::StorageType}
+  #   instance which can hold the rack {CaTissue::StorageType}.
+  # * Each {CaTissue::StorageContainer} belongs to a given {CaTissue::Site}. A child
+  #   {CaTissue::StorageContainer} site defaults to its parent container site.
+  #   Site consistency is not enforced by caTissue, i.e. it is possible to create
+  #   a rack whose site differs from that of its parent freezer and child boxes.
+  # * {CaTissue::SpecimenArray} is not associated to a site.
+  # * The container children are partitioned into three methods for the three different
+  #   types and pseudo-types of contained items: {CaTissue::StorageContainer},
+  #   {CaTissue::SpecimenArray} and {CaTissue::Specimen#class}.
+  # * {CaTissue::SpecimenArray} holds {CaTissue::SpecimenArrayContent} positions, which
+  #   are the functional equivalent of {CaTissue::SpecimenPosition} adapted for specimen
+  #   arrays, although {CaTissue::SpecimenArrayContent} is not a {CaTissue::SpecimenPosition}
+  #   or even an {CaTissue::AbstractPosition}. {CaTissue::SpecimenPosition} is functionally
+  #   a specimen position in a box, whereas {CaTissue::SpecimenArrayContent} is functionally
+  #   a specimen position in a specimen array.
+  #
+  # The ContainerType/Container mish-mash is partially alleviated in caRuby as follows:
+  # * {CaTissue::StorageType} and {CaTissue::StorageContainer} include the
+  #   {CaTissue::StorageTypeHolder} module, which unifies treatment of contained
+  #   types.
+  # * Similarly, {CaTissue::AbstractPosition} and {CaTissue::SpecimenArrayContent} include
+  #   the {CaTissue::Position} module, which unifies treatment of positions.
+  # * Contained child types are consolidated into {CaTissue::StorageTypeHolder#child_types}
+  # * Similarly, {CaTissue::StorageContainer} child items are consolidated into
+  #   {CaTissue::StorageContainer#child_types}
+  # * The various container and position classes are augmented with helper methods to
+  #   add, move and find specimens and subcontainers. These methods hide the mind-numbing
+  #   eccentricity of caTissue specimen storage interaction.
+  class ContainerType
+    include Resource
+
+    add_attribute_aliases(:column_label => :oneDimensionLabel, :row_label => :twoDimensionLabel)
+
+    add_attribute_defaults(:activity_status => 'Active')
+
+    set_secondary_key_attributes(:name)
+
+    add_mandatory_attributes(:activity_status, :capacity, :one_dimension_label, :two_dimension_label)
+
+    # caTissue alert - although capacity is not marked cascaded in Hibernate, it is created when the
+    # ContainerType is created.
+    add_dependent_attribute(:capacity)
+
+    # Override default {CaRuby::Resource#merge_attributes} to support the Capacity :rows and :columns
+    # pseudo-attributes.
+    #
+    # @param (see CaRuby::Resource#merge_attributes)
+    def merge_attributes(other, attributes=nil)
+      if Hash === other then
+        # partition the other hash into the Capacity attributes and ContainerType attributes
+        cp_hash, ct_hash = other.partition { |key, value| key == :rows or key == :columns }
+        self.capacity ||= Capacity.new(cp_hash).add_defaults unless cp_hash.empty?
+        super(ct_hash, attributes)
+      else
+        super(other, attributes)
+      end
+    end
+
+    # @param [CaTissue::Site] site the site where the candidate containers are located
+    # @param opts (see CaRuby::Writer#find)
+    # @option (see CaRuby::Writer#find)
+    # @return an available container of this ContainerType which is not
+    #   {CaTissue::Container#completely_full?}.
+    def find_available(site, opts=nil)
+      find_containers(:site => site).detect { |ctr| not ctr.completely_full? } or
+      (create_container(:site => site).create if Options.get(:create, opts))
+    end
+
+    # Fetches containers of this ContainerType from the database.
+    #
+    # @param [<Symbol => Object>] params the optional search attribute => value hash
+    # @return the containers of this type which satisfy the search parameters
+    def find_containers(params=nil)
+      tmpl = create_container(params)
+      logger.debug { "Finding #{name} containers..." }
+      tmpl.query
+    end
+
+    # Returns a new Container instance of this ContainerType with an optional attribute => value hash.
+    # The container_type of the new Container is this ContainerType.
+    #
+    # @param [{Symbol => Object}] vh the attribute => value hash
+    # @return [Container] the new container
+    def create_container(vh=nil)
+      vh ||= {}
+      vh[:container_type] = self
+      container_class.new(vh)
+    end
+
+    private
+
+    # Adds an empty capacity and default dimension labels, if necessary.
+    # The default {#one_dimension_label} is 'Column' if there is a non-zero dimension capacity, 'Unused' otherwise.
+    # The default {#two_dimension_label} is 'Row' if there is a non-zero dimension capacity, 'Unused' otherwise.
+    def add_defaults_local
+      super
+      self.capacity ||= Capacity.new.add_defaults
+      self.row_label ||= capacity.rows && capacity.rows > 0 ? 'Row' : 'Unused'
+      self.column_label ||= capacity.columns && capacity.columns > 0 ? 'Column' : 'Unused'
+    end
+  end
+end

data/lib/catissue/domain/department.rb

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

data/lib/catissue/domain/disposal_event_parameters.rb

@@ -0,0 +1,13 @@
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.DisposalEventParameters')
+
+  class DisposalEventParameters
+    include Resource
+
+    add_attribute_defaults(:activity_status => 'Closed')
+
+    # caTissue alert - DisposalEventParameters activity status is transient.
+    qualify_attribute(:activity_status, :unfetched)
+  end
+end

data/lib/catissue/domain/embedded_event_parameters.rb

@@ -0,0 +1,10 @@
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.EmbeddedEventParameters')
+
+  class EmbeddedEventParameters
+    include Resource
+
+    add_attribute_aliases(:medium => :embedding_medium)
+  end
+end

data/lib/catissue/domain/external_identifier.rb

@@ -0,0 +1,22 @@
+
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.ExternalIdentifier')
+
+  # The ExternalIdentifier domain class.
+  class ExternalIdentifier
+    include Resource
+
+    # Sets this ExternalIdentifier value to the given value.
+    # A Numeric value is converted to a String.
+    def value=(value)
+      value = value.to_s if value
+      setValue(value)
+    end
+
+    add_mandatory_attributes(:value)
+
+    set_secondary_key_attributes(:specimen, :name)
+  end
+end

data/lib/catissue/domain/frozen_event_parameters.rb

@@ -0,0 +1,10 @@
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.FrozenEventParameters')
+
+  class FrozenEventParameters
+    include Resource
+
+    add_attribute_aliases(:freeze_method => :frozen_event_parameters_method)
+  end
+end

data/lib/catissue/domain/institution.rb

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

data/lib/catissue/domain/new_specimen_array_order_item.rb

@@ -0,0 +1,35 @@
+require 'catissue/resource'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.NewSpecimenArrayOrderItem')
+
+  # The NewSpecimenArrayOrderItem domain class.
+  class NewSpecimenArrayOrderItem
+    include Resource
+    
+    # caTissue alert - Bug #64: Some domain collection properties not initialized.
+    # Initialize order_items if necessary. 
+    #
+    # @return [Java::JavaUtil::Set] the items
+    def order_items
+      getOrderItemCollection or (self.order_items = Java::JavaUtil::LinkedHashSet.new)
+    end
+    
+    # caTissue alert - Bug #64: Some domain collection properties not initialized.
+    # Initialize distributions if necessary. 
+    def distributions
+      getDistributionCollection or (self.distributions = Java::JavaUtil::LinkedHashSet.new)
+    end
+
+    def initialize(params=nil)
+      super
+      # jRuby bug? - Java methods not acceesible until respond_to? called; TODO - reconfirm this
+      respond_to?(:order_items)
+      respond_to?(:distributions)
+      # work around caTissue Bug #64
+      self.order_items ||= Java::JavaUtil::LinkedHashSet.new
+      self.distributions ||= Java::JavaUtil::LinkedHashSet.new
+    end
+  end
+end

data/lib/catissue/domain/order_details.rb

@@ -0,0 +1,25 @@
+
+
+module CaTissue
+  java_import('edu.wustl.catissuecore.domain.OrderDetails')
+
+  # The OrderDetails domain class.
+  class OrderDetails
+    include Resource
+    
+    # caTissue alert - Bug #64: Some domain collection properties not initialized.
+    # Initialize order_items if necessary. 
+    #
+    # @return [Java::JavaUtil::Set] the items
+    def order_items
+      getOrderItemCollection or (self.order_items = Java::JavaUtil::LinkedHashSet.new)
+    end
+    
+    def initialize(params=nil)
+      super
+      respond_to?(:order_items)
+      # caTissue alert - work around caTissue Bug #64
+      self.order_items ||= Java::JavaUtil::LinkedHashSet.new
+    end
+  end
+end

data/lib/catissue/domain/participant.rb

@@ -0,0 +1,138 @@
+require 'caruby/util/validation'
+require 'catissue/resource'
+require 'catissue/util/person'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.Participant')
+
+  # The Participant domain class.
+  class Participant
+    include Resource, Person
+
+    # The convenience Person name aggregate is not a Java property but is added as a transient attribute
+    # which is reflected in the saved Java property name subfields.
+    add_attribute(:name)
+
+    # caTissue alert - clinical study is unsupported by caTissue.
+    remove_attribute(:clinical_study_registrations)
+
+    add_attribute_aliases(:collection_registrations => :collection_protocol_registrations,
+    :registrations => :collection_protocol_registrations,
+    :medical_identifiers => :participant_medical_identifiers)
+
+    set_secondary_key_attributes(:social_security_number)
+
+    # Clarification on defaults:
+    # * 'Unknown': value is unknown by anybody
+    # * 'Unspecified': value is known by somebody, but the data was not communicated to the bank
+    # cf. https://cabig-kc.nci.nih.gov/Biospecimen/forums/viewtopic.php?f=16&t=672&p=2343&e=2343
+    add_attribute_defaults(:activity_status => 'Active', :ethnicity => 'Unknown', :gender => 'Unspecified',
+      :sex_genotype => 'Unknown', :vital_status => 'Unknown')
+
+    # caTissue alert - Bug #154: Participant gender is specified by caTissue as optional, but if it is not set then
+    # it appears as Female in the GUI even though it is null in the database.
+    add_mandatory_attributes(:activity_status, :gender)
+
+    add_dependent_attribute(:collection_protocol_registrations, :logical)
+
+    add_dependent_attribute(:races)
+
+    # PMI is not cascaded, but insert is done in the bizlogic.
+    add_dependent_attribute(:participant_medical_identifiers)
+
+    # SSN is a key, if present, but is not required.
+    qualify_attribute(:social_security_number, :optional)
+
+    qualify_attribute(:collection_protocol_registrations, :fetched)
+
+    qualify_attribute(:participant_medical_identifiers, :fetched)
+
+    def merge_attribute_value(attribute, oldval, newval)
+      # caTissue alert - remove the autogenerated blank PMI.
+      # TODO - file bug
+      # @see CaTissue::Database#query_safe
+      if attribute == :participant_medical_identifiers and newval then
+        CaTissue::Participant.remove_empty_medical_identifier(newval)
+      end
+      super
+    end
+
+    # Returns the SSN if it exists, otherwise the first ParticipantMedicalIdentifier, if any, otherwise nil.
+    def key
+      super or medical_identifiers.first
+    end
+
+    # Returns a new ParticipantMedicalIdentifier which adds this Participant to the given site
+    # with Medical Record Number mrn.
+    def add_mrn(site, mrn)
+      CaTissue::ParticipantMedicalIdentifier.new(:participant => self, :site => site, :medical_record_number => mrn)
+    end
+
+    # Returns this Participant's medical record numbers. Each medical record number is Site-specific.
+    # @see the medical_identifiers attribute for MRN-site associations
+    def medical_record_numbers
+      medical_identifiers.map { |pmi| pmi.medicalRecordNumber }
+    end
+
+    # Returns all specimens collected from this Participant.
+    def specimens
+      Flattener.new(registrations.specimens.map { |cpr| cpr.specimens })
+    end
+
+    # Returns this Participant's CollectionProtocolRegistration protocols.
+    def collection_protocols
+      collection_registrations.map { |reg| reg.protocol }.uniq
+    end
+
+    # Returns the MRN for this participant. If this Participant does not have exactly one
+    # MRN, then this method returns nil. This method is a convenience for the common situation
+    # where a participant is enrolled at one site.
+    def medical_record_number
+      return medical_identifiers.first.medical_record_number if medical_identifiers.size == 1
+    end
+
+    # Returns the collection site for which this participant has a MRN. If there is not exactly one
+    # such site, then this method returns nil. This method is a convenience for the common situation
+    # where a participant is enrolled at one site.
+    def collection_site
+      return unless medical_identifiers.size == 1
+      site = medical_identifiers.first.site
+      return if site.nil?
+      site.site_type == Site::SiteType::COLLECTION ? site : nil
+    end
+
+    protected
+
+    def self.remove_empty_medical_identifier(mids)
+      bogus = mids.detect { |mid| mid.medical_record_number.nil? }
+      if bogus then
+        logger.debug { "Work around caTissue bug by removing empty fetched #{bogus.participant.qp} #{bogus.qp}..." }
+        # dissociate the participant
+        bogus.participant = nil
+        # remove the bogus medical identifier
+        mids.delete(bogus)
+      end
+      mids
+    end
+
+    private
+
+    # Returns the first Medical Record Number qualified by the MRN site, if this exists.
+    def alternate_key
+      return if medical_identifiers.empty?
+      pmi = medical_identifiers.first
+      pmi.key if pmi
+    end
+
+    # Adds a default Unknown Race, if necessary. Although Race is not strictly mandatory in the caTissue
+    # API, setting this default emulates the caTissue UI Add Participant page.
+    def add_defaults_local
+      super
+      # Make a new default Race which references this Participant, if necessary. Setting the Race
+      # participant to self automatically adds the Race to this Participant's races collection.
+      # The Race name defaults to Unknown.
+      if races.empty? then CaTissue::Race.new(:participant => self).add_defaults end
+    end
+  end
+end