caruby-tissue 1.2.1

data/lib/catissue/domain/specimen_array.rb

@@ -0,0 +1,47 @@
+
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.SpecimenArray')
+
+  class SpecimenArray
+    include Resource
+    
+    # caTissue alert - the superclass Container occupied_positions does not apply to SpecimenArray.
+    remove_attribute(:occupied_positions)
+    
+    add_attribute_aliases(:container_type => :specimen_array_type, :contents => :specimen_array_contents)
+
+    set_attribute_type(:new_specimen_array_order_items, CaTissue::SpecimenArrayOrderItem)
+
+    add_dependent_attribute(:new_specimen_array_order_items)
+
+    add_dependent_attribute(:specimen_array_contents)
+
+    # Raises NotImplementedError since caTissue SpecimenArray is broken in important ways
+    # described below.
+    #
+    # caTissue alert - SpecimenArray is a subclass of Container but is a mismatch for Container
+    # in two critical ways:
+    # * SpecimenArray does not hold subcontainers in Container occupied_positions
+    # * the Specimen position cannot be a SpecimenArrayContent
+    # * SpecimenArrayContent is not an AbstractPosition, although it should be
+    #
+    # Thus, SpecimenArray extends Container although it shouldn't and SpecimenArrayContent
+    # doesn't extend AbstractPosition although it should.
+    def add(storable, coordinate=nil, attribute=nil)
+      raise NotImplementedError.new("Adding specimens to a SpecimenArray is not yet supported")
+    end
+    
+    alias :<< :add
+
+    alias :all_occupied_positions :specimen_array_contents
+    
+    protected
+    
+    # Returns the contents if storable is a Specimen, nil otherwise.
+    def content_collection_for(storable)
+      contents if CaTissue::Specimen === storable
+    end
+  end
+end

data/lib/catissue/domain/specimen_array_content.rb

@@ -0,0 +1,19 @@
+require 'catissue/util/position'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.SpecimenArrayContent')
+
+  # caTissue alert - #{CaTissue::SpecimenArrayContent} should be derived from
+  # {CaTissue::AbstractPosition} but isn't (cf. {CaTissue::ContainerType}).
+  # Partially rectify this by including the {Position} mix-in in common with
+  # {CaTissue::AbstractPosition}.
+  class SpecimenArrayContent
+    include Position, Resource
+
+    add_attribute_aliases(:holder => :specimen_array, :occupant => :specimen)
+
+    # Each SpecimenArrayContent has a specimen and there is only one such slot per specimen.
+    set_secondary_key_attributes(:specimen)
+  end
+end

data/lib/catissue/domain/specimen_array_type.rb

@@ -0,0 +1,20 @@
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.SpecimenArrayType')
+
+  class SpecimenArrayType
+    include Resource
+
+    add_mandatory_attributes(:specimen_class, :specimen_types)
+
+    # Returns SpecimenArray.
+    def container_class
+      CaTissue::SpecimenArray
+    end
+
+    # Returns true if Storable is a Specimen and supported by this SpecimenArrayType.
+    def can_hold_child?(storable)
+      Specimen === storable and storable.specimen_class == specimen_class and specimen_types.include?(storable.specimen_type)
+    end
+  end
+end

data/lib/catissue/domain/specimen_characteristics.rb

@@ -0,0 +1,20 @@
+
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.SpecimenCharacteristics')
+
+  class SpecimenCharacteristics
+    include Resource
+
+    add_attribute_defaults(:tissue_side => 'Not Specified', :tissue_site => 'Not Specified')
+
+    add_mandatory_attributes(:tissue_site, :tissue_side)
+
+    # The tissue_side constants.
+    class TissueSide
+      LEFT = 'Left'
+      RIGHT = 'Right'
+    end
+  end
+end

data/lib/catissue/domain/specimen_collection_group.rb

@@ -0,0 +1,412 @@
+require 'caruby/util/transitive_closure'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.SpecimenCollectionGroup')
+
+  # The SpecimenCollectionGroup domain class.
+  #
+  # _Note_: the SpecimenCollectionGroup name attribute is auto-generated on create in caTissue 1.1 API and should not
+  # be set by API clients when creating a new SpecimenCollectionGroup in the database.
+  class SpecimenCollectionGroup
+    include Resource
+    
+    # caTissue alert - Bug #64: Some domain collection properties not initialized.
+    # Initialize consent_tier_statuses if necessary.
+    #
+    # @return [Java::JavaUtil::Set] the statuses
+    def consent_tier_statuses
+      getConsentTierStatusCollection or (self.consent_tier_statuses = Java::JavaUtil::LinkedHashSet.new)
+    end
+
+    # Sets the collection status for this SCG.
+    # If the SCG status is set to +Complete+, then the status of each of the SCG Specimens with
+    # status +Pending+ is reset to +Collected+.
+    #
+    # @param [String] value a permissible SCG status
+    def collection_status=(value)
+      if value == 'Complete' then
+        specimens.each { |spc| spc.collection_status = 'Collected' if spc.pending? }
+      end
+      setCollectionStatus(value)
+    end
+
+    # Converts an Integer SPN value to a String.
+    #
+    # @param [Numeric, String] value the SPN value
+    def surgical_pathology_number=(value)
+      value = value.to_s if Numeric === value
+      setSurgicalPathologyNumber(value)
+    end
+
+    add_attribute_aliases(:collection_event => :collection_protocol_event,
+      :event_parameters => :specimen_event_parameters,
+      :events => :specimen_event_parameters,
+      :registration => :collection_protocol_registration)
+
+    add_mandatory_attributes(:specimen_event_parameters, :specimen_collection_site, :clinical_diagnosis, :collection_status)
+
+    set_secondary_key_attributes(:name)
+
+    set_alternate_key_attributes(:surgical_pathology_number, :collection_protocol_registration)
+
+    # caTissue alert - An auto-generated SCG in turn auto-generates a ConsentTierStatus
+    # for each ConsentTierResponse defined in the SCG owner CPR.
+    #
+    # caTissue alert - SCG consent_tier_statuses is cascaded but not fetched.
+    add_dependent_attribute(:consent_tier_statuses, :autogenerated, :unfetched)
+
+    # SCG event parameters are disjoint, since they are owned by either a SCG or a Specimen.
+    # An auto-generated SCG also auto-generates the Collection and Received SEPs.
+    # A SCG SEP is only created as a dependent when the SCG is created. A SCG SEP
+    # cannot be created for an existing SCG. By contrast, a Specimen SEP can only be
+    # created, not updated.
+    #
+    # caTissue alert - SpecimenCollectionGroup auto-generated update ignores the referenced
+    # specimen_event_parameters and instead creates new parameters. This occurs only on the
+    # first update, and an SEP cannot be added to an existing, updated SCG. Work-around is
+    # to update the SCG template without the parameters, then update the parameters separately.
+    add_dependent_attribute(:specimen_event_parameters, :autogenerated, :disjoint)
+
+    # SCG Specimens are auto-generated from SpecimenRequirement templates when the SCG is created.
+    # The Specimens are not cascaded.
+    add_dependent_attribute(:specimens, :logical, :autogenerated)
+
+    # The CPE-SCG association is bi-directional.
+    set_attribute_inverse(:collection_protocol_event, :specimen_collection_groups)
+
+    # CPE is fetched but not cascaded.
+    qualify_attribute(:collection_protocol_event, :fetched)
+
+    # caTissue alert - Augment the cascaded reference attributes to work around a CaTissue bug that requires that a
+    # SpecimenCollectionGroup update object references a CollectionProtocolRegistration with a Participant reference.
+    # The CPR identifier should be sufficient for a SCG update, but caTissue bizlogic requires an extraneous
+    # CPR -> Participant reference.
+    # TODO - file a bug and reference it here
+    qualify_attribute(:collection_protocol_registration, :cascaded)
+
+    # caTissue alert - Bug #65: Although SCG name uniquely identifies a SCG, the SCG name is auto-generated on create
+    # and cannnot be set by the client. Therefore, name is marked as update_only.
+    qualify_attribute(:name, :autogenerated, :update_only)
+
+    # caTissue alert - Bug #64: Initialize the SCG consent_tier_statuses to an empty set.
+    def initialize(params=nil)
+      super
+      # work around caTissue Bug #64
+      self.consent_tier_statuses ||= Java::JavaUtil::LinkedHashSet.new
+    end
+
+     # @return [CollectionProtocol] the SCG CPE CP
+   def collection_protocol
+      collection_protocol_event.collection_protocol if collection_protocol_event
+    end
+
+    # @return [Double, nil] the SCG CPE event point
+    def event_point
+      collection_protocol_event and collection_protocol_event.study_calendar_event_point
+    end
+
+    # @return [<SpecimenRequirement>] the SCG CPE requirements
+    def requirements
+      collection_protocol_event.nil? ? Array::EMPTY_ARRAY : collection_protocol_event.requirements
+    end
+    
+    # @return [Boolean] whether this SCG collection status is one of the +Pending+ statuses.
+    def pending?
+      collection_status =~ /^Pending/
+    end
+
+    # Returns the number of specimens in this SpecimenCollectionGroup.
+    def size
+      specimens.size
+    end
+
+    # Removes associations to this registration.
+    def delete
+      registration.specimen_collection_groups.delete(self) if registration
+    end
+
+    # Merges the other object into this SpecimenCollectionGroup. This method overrides the
+    # standard {CaRuby::Resource#merge_attributes} method as follows:
+    # * Builds the SpecimenEventParameter objects from atomic parameters, e.g.:
+    #     SpecimenCollectionGroup.create(:name = > name, ..., :collector => collector, :receiver => receiver)
+    #   The supported event parameters are described in {#collect}.
+    # * Adds the transitive closure of each non-derived Specimen in other.
+    def merge_attributes(other, attributes=nil)
+      if Hash === other then
+        # extract the event parameters
+        other[:specimen_event_parameters] = extract_event_params(other)
+        # take the transitive closure of the specimens
+        spcs = other.delete(:specimens)
+        if spcs then
+          spcs = [spcs] if CaTissue::Specimen === spcs
+          # take the transitive closure of the root specimens in the hierarchy
+          other[:specimens] = spcs.select { |spc| spc.parent.nil? }.transitive_closure(:children)
+        end
+      end
+      # delegate to super for standard attribute value merge
+      super
+    end
+
+    # Collects and receives this SCG with the given params option => value hash.
+    # The SCG collection status is set to 'Completed'.
+    #
+    # Supported parameters are as follows:
+    # * receiver - the required User who received the specimens
+    # * received_date - the optional receival date (default is now)
+    # * collector - the optional User who collected the specimens (default is receiver)
+    # * collection_date - the optional collection date (default is received_date)
+    #
+    # If there is at least a receiver, then no additional event parameters are added.
+    #
+    # Raises ValidationError if this SCG has already been received.
+    def collect(params)
+      raise ValidationError.new("SCG is already collected") if received?
+      specimen_event_parameters.merge!(extract_event_params(params))
+    end
+
+    def protocol
+      collection_event.protocol if collection_event
+    end
+
+    # Returns whether this SCG has a collected event.
+    def collected?
+      collection_event_parameters
+    end
+
+    # Returns the User who collected this SCG.
+    def collector
+      ep = collection_event_parameters
+      ep.user if ep
+    end
+
+    # @return [Date] the date this SCG was donated by the participant.
+    def collection_timestamp
+      ep = collection_event_parameters
+      ep.timestamp if ep
+    end
+
+    # Returns the CollectionEventParameters for this specimen group.
+    def collection_event_parameters
+      event_parameters.detect { |ep| CaTissue::CollectionEventParameters === ep }
+    end
+
+    # Returns whether this SCG has a received event.
+    def received?
+      received_event_parameters
+    end
+
+    # Returns the User who received this specimen group.
+    def receiver
+      ep = received_event_parameters
+      ep.user if ep
+    end
+
+    # Returns the ReceivedEventParameters for this specimen group.
+    def received_event_parameters
+      event_parameters.detect { |ep| CaTissue::ReceivedEventParameters === ep }
+    end
+
+    # Returns whether this SCG is the same as the other SCG in the scope of an existing parent CPR.
+    # This method returns whether the other SCG status is Pending and the event point is the
+    # same as the other event point.
+    def minimal_match?(other)
+      super and event_point == other.event_point
+    end
+
+    # Overrides {CaRuby::Resource#direct_dependents} in the case of the _specimens_ attribute to select
+    # only top-level Specimens not derived from another Specimen.
+    def direct_dependents(attribute)
+      if attribute == :specimens then
+        super.reject { |spc| spc.parent }
+      else
+        super
+      end
+    end
+
+    def validate
+      super
+      validate_consent
+      validate_event_parameters
+    end
+
+    # Restricts the {CaRuby::Persistable#fetch_saved?} condition for a SCG as follows:
+    #
+    # If the SCG status was created or was updated from +Pending+ to +Collected+,
+    # then fetch the saved SCG. Otherwise, forego fetching the saved SCG.
+    # 
+    # @return (see CaRuby::Persistable#fetch_saved)
+    def fetch_saved?
+      super and status_changed_to_complete?
+    end
+
+    private
+     
+    SAVED_FETCH_MSG = "Saved #{qp} %s be fetched from the database to reflect the current database state, since it was %s."
+
+    # @see #fetch_saved
+    def status_changed_to_complete?
+      if identifier.nil? then
+        logger.debug { format_saved_fetch_message(true, "created") }
+        true
+      elsif collected? and (snapshot.nil? or snapshot[:collection_status] == 'Pending') then
+        logger.debug { format_saved_fetch_message(true, "updated to status Complete") }
+        true
+      else
+        logger.debug { format_saved_fetch_message(false, "not updated from pending to complete") }
+        false
+      end
+    end
+    
+    def format_saved_fetch_message(fetch, reason)
+      args = fetch ? [qp, 'must', reason] : [qp, 'does not need to', reason]
+      SAVED_FETCH_MSG % args
+    end
+   
+    def each_defaults_dependent
+      # visit ReceivedEventParameters first
+      rep = received_event_parameters
+      yield rep if rep
+      # add other dependent defaults
+      each_dependent { |dep| yield dep unless ReceivedEventParameters === dep }
+    end
+
+    # The default In Transit collection site.
+    DEF_SITE = Site.new(:name => 'In Transit')
+
+    # Adds defaults as follows:
+    # * the default collection event is the first event in the protocol registered with this SCG.
+    # * the default collection status is 'Complete' if there is a received event, 'Pending' otherwise.
+    # * the default collection site is the CP site, if this SCG is {#received?} and there is only CP one,
+    #   otherwise the 'In Transit' site.
+    # * the default conset tier status is 'Complete' if there is a received event, 'Pending' otherwise.
+    # * a default ReceivedEventParameters is added to this SCG if the collection status is
+    #   'Complete' and there is no other ReceivedEventParameters. The receiver is an arbitrary
+    #   protocol coordinator.
+    #
+    # Raises ValidationError if the default ReceivedEventParameters could not be created because
+    # there is no protocol or protocol coordinator.
+    #
+    # @see CollectionProtocol#first_event
+    def add_defaults_local
+      super
+      # the default event
+      self.collection_protocol_event ||= default_collection_event
+
+      # the default collection status and received parameters
+      if received? then
+        self.collection_status ||= 'Complete'
+      elsif collection_status == 'Complete' then
+        create_default_received_event_parameters
+      else
+        self.collection_status ||= 'Pending'
+      end
+      # the default collection event
+      if received? and not collected? then
+        create_default_collection_event_parameters
+      end
+
+      # the default site
+      self.collection_site ||= default_site
+      
+      # the default CT statuses
+      make_default_consent_tier_statuses
+    end
+    
+    # Makes a consent status for each registration consent.
+    #
+    # caTissue alert - Bug #156: SCG without consent status displays error.
+    # A SCG consent tier status is required for each consent tier in the SCG registration.
+    def make_default_consent_tier_statuses
+      return if registration.nil? or registration.consent_tier_responses.empty?
+      
+      # the consent tiers
+      ctses = consent_tier_statuses.map { |cts| cts.consent_tier }
+      # ensure that there is a CT status for each consent tier
+      registration.consent_tier_responses.each do |ctr|
+        ct = ctr.consent_tier
+        next if ctses.include?(ct)
+        cts = CaTissue::ConsentTierStatus.new(:consent_tier => ct).add_defaults
+        consent_tier_statuses << cts
+        logger.debug { "Made default #{qp} #{cts.qp} for consent tier #{ct.qp}." }
+      end
+    end
+
+    def default_site
+      cp = collection_event.protocol if collection_event
+      cp && cp.sites.size == 1 ? cp.sites.first : DEF_SITE
+    end
+
+    # Returns the first event in the protocol registered with this SCG.
+    def default_collection_event
+      return if registration.nil?
+      pcl = registration.protocol || return
+      # if no protocol event, then add the default event
+      pcl.add_defaults if pcl.events.empty?
+      pcl.first_event
+    end
+
+    def create_default_received_event_parameters
+      cp = collection_protocol
+      if cp.nil? then
+        raise ValidationError.new("SCG with status Complete default CollectionEventParameters could not be created since there is no collection protocol: #{self}")
+      end
+      rcvr = cp.coordinators.first
+      if rcvr.nil? then
+        raise ValidationError.new("SCG with status Complete default CollectionEventParameters could not be created since there is no collection protocol coordinator: #{self}")
+      end
+      # make the REP
+      CaTissue::SpecimenEventParameters.create_parameters(:received, self, :user => rcvr)
+    end
+
+    def create_default_collection_event_parameters
+      rep = received_event_parameters || return
+      # make the CEP from the REP
+      CaTissue::SpecimenEventParameters.create_parameters(:collection, self, :user => rep.user, :timestamp => rep.timestamp)
+    end
+
+    # Verifies that each registration consent tier response has a corresponding SCG consent tier status.
+    def validate_consent
+      return unless registration
+      # the default consent statuses
+      ctses = consent_tier_statuses.map { |cts| cts.consent_tier }
+      registration.consent_tier_responses.each do |ctr|
+        ct = ctr.consent_tier
+        unless ctses.include?(ct) then
+          raise ValidationError.new("#{self} is missing a ConsentTierStatus for consent statement #{ct.statement}")
+        end
+      end
+    end
+
+    # Verifies that a SCG create with collection status 'Pending' does not have event parameters.
+    def validate_event_parameters
+      if identifier.nil? and collection_status == 'Pending' and not event_parameters.empty? then
+        raise ValidationError.new("#{self} create with status Pending cannot include event parameters #{event_parameters.to_series}")
+      end
+    end
+
+    # Returns SpecimenEventParameters built from the params associations.
+    # The params used to build the SpecimenEventParameters are removed, since they are
+    # redundant.
+    #
+    # Raises ValidationError if the required collector or receiver features are missing.
+    def extract_event_params(params)
+      # Check if there is an attribute association
+      event_params = params.delete(:specimen_event_parameters) || []
+      # collect additional parameter associations
+      scg_receiver = params.delete(:receiver)
+      scg_collector = params.delete(:collector)
+      scg_collector ||= scg_receiver
+      # if there is not at least a collector, then don't continue parsing
+      return event_params if scg_collector.nil?
+      received_date = params.delete(:received_date)
+      received_date ||= DateTime.now
+      event_params << CaTissue::SpecimenEventParameters.create_parameters(:received, self, :user => scg_receiver, :timestamp => received_date)
+      collection_date = params.delete(:collection_date)
+      collection_date ||= received_date
+      event_params << CaTissue::SpecimenEventParameters.create_parameters(:collection, self, :user => scg_collector, :timestamp => collection_date)
+      logger.debug { "SCG #{self} event parameters: #{event_params.pp_s(:single_line)}" }
+      event_params
+    end
+  end
+end