caruby-tissue 1.2.1

data/lib/catissue/domain/specimen_event_parameters.rb

@@ -0,0 +1,111 @@
+require 'caruby/util/validation'
+require 'caruby/util/inflector'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.SpecimenEventParameters')
+
+  class SpecimenEventParameters
+    include Resource
+    
+    # date is a synonym for the more accurately titled timestamp attribute.
+    add_attribute_aliases(:date => :timestamp)
+
+    add_mandatory_attributes(:timestamp, :user)
+
+    # specimen is abstract but unfetched.
+    qualify_attribute(:specimen, :unfetched)
+
+    private
+
+    def self.allocate
+      raise NotImplementedError.new("SpecimenEventParameters is abstract; use the create method to make a new instance")
+    end
+
+    public
+
+    # Creates a SpecimenEventParameters of the specified subclass type. The type is a
+    # SpecimenEventParameters subclass name without the +EventParameters+ suffix, e.g.
+    # +Collection+. Lower-case, underscore symbols are supported and preferred, e.g. the
+    # :collection type creates a CollectionEventParameters.
+    #
+    # The required scg_or_specimen argument is either a SpecimenCollectionGroup or
+    # a Specimen.
+    #
+    # The optional params argument are attribute => value associations, e.g.
+    #   SpecimenEventParameters.create_parameters(:collection, scg, :user => collector, :timestamp => DateTime.now)
+    def self.create_parameters(type, scg_or_specimen, params=Hash::EMPTY_HASH)
+      # make the class name by joining the camel-cased type prefix to the subclass suffix.
+      # classify converts a lower_case, underscore type to a valid class name, e.g. :check_in_check_out
+      # becomes CheckInCheckOut.
+      class_name = type.to_s.classify + SUBCLASS_SUFFIX
+      begin
+        klass = CaTissue.const_get(class_name.to_sym)
+      rescue
+        raise ArgumentError.new("Unsupported event parameters type: #{type}; #{class_name} must be a subtype of #{self}")
+      end
+      event_params = klass.new(params)
+      case scg_or_specimen
+      when SpecimenCollectionGroup then
+        event_params.specimen_collection_group = scg_or_specimen
+      when Specimen then
+        event_params.specimen = scg_or_specimen
+      when nil then
+        raise ArgumentError.new("Missing SpecimenEventParameters scg_or_specimen factory argument")
+      else
+        raise ArgumentError.new("Unsupported SpecimenEventParameters factory argument - expected SpecimenCollectionGroup or Specimen, found #{scg_or_specimen.class}")
+      end
+      event_params
+    end
+
+    # Returns the Specimen or SpecimenCollectionGroup to which this event is attached.
+    def subject
+      specimen.nil? ? specimen_collection_group : specimen
+    end
+
+    # Sets the scg_or_specimen subject to which this event is attached.
+    def subject=(scg_or_specimen)
+      spc_subject = scg_or_specimen if Specimen === scg_or_specimen
+      scg_subject = scg_or_specimen if SpecimenCollectionGroup === scg_or_specimen
+      specimen = spc_subject
+      specimen_collection_group = scg_subject
+      scg_or_specimen
+    end
+
+    def collection_protocol
+      specimen_collection_group.collection_protocol if specimen_collection_group
+    end
+
+    def validate
+      super
+      if subject.nil? then
+        raise ValidationError.new("Both specimen_collection_group and specimen are missing in SpecimenEventParameters #{self}")
+      end
+    end
+
+    private
+
+    SUBCLASS_SUFFIX = 'EventParameters'
+
+    # Sets each missing value to a default as follows:
+    # * default user is the SCG receiver
+    # * default timestamp is now
+    def add_defaults_local
+      super
+      self.timestamp ||= Java.now
+      self.user ||= default_user
+    end
+
+    # Returns whether the given value is either nil, empty or equals other.
+    def missing_or_match?(attribute, other)
+      value = send(attr)
+      value.nil_or_empty? or value == other.send(attr)
+    end
+
+    def default_user
+      scg = specimen_collection_group
+      scg ||= specimen.specimen_collection_group if specimen
+      scg.receiver if scg
+    end
+  end
+end

data/lib/catissue/domain/specimen_position.rb

@@ -0,0 +1,38 @@
+
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.SpecimenPosition')
+
+  class SpecimenPosition
+    include Resource
+
+    add_mandatory_attributes(:storage_container)
+
+    add_attribute_aliases(:holder => :storage_container, :container => :storage_container, :occupant => :specimen)
+
+    # Each SpecimenPosition has a specimen and there is only one position per specimen.
+    set_secondary_key_attributes(:specimen)
+
+    set_attribute_inverse(:storage_container, :specimen_positions)
+
+    set_attribute_inverse(:specimen, :specimen_position)
+    
+    qualify_attribute(:storage_container, :fetched)
+
+    # Returns a TransferEventParameters which serves as a proxy for saving this SpecimenPosition.
+    #
+    # caTissue alert - caTissue does not allow saving a SpecimenPosition directly in the database.
+    # Creating a TransferEventParameters sets the SpecimenPosition as a side-effect. Therefore,
+    # SpecimenPosition save is accomplished by creating a proxy TransferEventParameters instead.
+    def saver_proxy
+      xfr = CaTissue::TransferEventParameters.new(:specimen => specimen, :to => location)
+      if snapshot and changed? then
+        xfr.from_storage_container = snapshot[:storage_container]
+        xfr.from_position_dimension_one = snapshot[:position_dimension_one]
+        xfr.from_position_dimension_two = snapshot[:position_dimension_two]
+      end
+      xfr
+    end
+  end
+end

data/lib/catissue/domain/specimen_protocol.rb

@@ -0,0 +1,34 @@
+require 'date'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.SpecimenProtocol')
+
+  # The SpecimenProtocol domain class.
+  class SpecimenProtocol
+    include Resource
+
+    set_secondary_key_attributes(:short_title)
+
+    # caTissue alert - Bug #155: enrollment is incorrectly defined in SpecimenProtocol rather
+    # than CollectionProtocol. It is defaulted here until this defect is fixed.
+    add_attribute_defaults(:activity_status => 'Active', :enrollment => 0)
+
+    add_mandatory_attributes(:principal_investigator, :activity_status, :start_date, :title)
+
+    # caTissue alert - Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    # Create CollectionProtocol in API ignores startDate.
+    qualify_attribute(:start_date, :update_only)
+
+    private
+
+    # Sets the defaults if necessary. The start date is set to now. The title is
+    # set to the short title.
+    def add_defaults_local
+      super
+      self.title ||= short_title
+      self.short_title ||= title
+      self.start_date ||= Java::JavaUtil::Date.new
+    end
+  end
+end

data/lib/catissue/domain/specimen_requirement.rb

@@ -0,0 +1,143 @@
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.SpecimenRequirement')
+
+  # The SpecimenRequirement domain class.
+  class SpecimenRequirement
+    include Resource
+    
+    # caTissue alert - Bug #64: Some domain collection properties not initialized.
+    # Initialize specimens if necessary. 
+     #
+    # @return [Java::JavaUtil::Set] the specimens
+   def specimens
+      getSpecimenCollection or (self.specimens = Java::JavaUtil::LinkedHashSet.new)
+    end
+
+    add_attribute_aliases(:collection_event => :collection_protocol_event)
+
+    add_attribute_defaults(:initial_quantity => 0.0, :pathological_status => 'Not Specified', :specimen_type => 'Not Specified', :storage_type => 'Not Specified')
+
+    add_mandatory_attributes(:collection_protocol_event, :storage_type)
+
+    # SpecimenRequirement children are constrained to SpecimenRequirement.
+    set_attribute_type(:child_specimens, SpecimenRequirement)
+
+    # SpecimenRequirement parent is constrained to SpecimenRequirement.
+    set_attribute_type(:parent_specimen, SpecimenRequirement)
+
+    # As with Specimen, even though the inverse is declared in AbstractSpecimen, do so
+    # again here to ensure that there is no order dependency of the dependent declaration
+    # below on AbstractSpecimen metadata initialization.
+    set_attribute_inverse(:parent_specimen, :child_specimens)
+
+    # Unlike Specimen, a child SpecimenRequirement is not cascaded by caTissue.
+    # It is not auto-generated, i.e. it is not created from a template when the
+    # parent CPE is created.
+    add_dependent_attribute(:child_specimens, :logical)
+    
+    # Overrides {Resource#owner} to return the parent_specimen, if it exists, or the collection_protocol_event otherwise.
+    def owner
+      parent_specimen or collection_protocol_event
+    end
+    
+    # Returns the SpecimenRequirement in others which matches this SpecimenRequirement in the scope of an owner CollectionProtocolEvent.
+    # This method relaxes {CaRuby::Resource#match_in_owner_scope} for a SpecimenRequirement that matches any SpecimenRequirement
+    # in others with the same class, specimen type, pathological_status and characteristics.
+    def match_in_owner_scope(others)
+      others.detect do |other|
+        self.class === other and specimen_type == other.specimen_type and pathological_status == other.pathological_status and
+         characteristics and characteristics.match?(other.characteristics)
+      end
+    end
+
+    private
+    
+    # Returns whether this SpecimenRequirement characteristics matches the other SpecimenRequirement characteristics
+    # on the tissue site and tissue side.
+    def match_characteristics(other)
+      chr = characteristics
+      ochr = other.characteristics
+      chr and ochr and chr.tissue_side == ochr.tissue_side and chr.tissue_site == ochr.tissue_site
+    end
+
+    # Raises NotImplementedError, since SpecimenRequirement is abstract.
+    def self.allocate
+      raise NotImplementedError.new("SpecimenRequirement is abstract; use the create method to make a new instance")
+    end
+
+    public
+
+    def initialize(params=nil)
+      super
+      respond_to?(:specimens)
+      # work around caTissue Bug #64
+      self.specimens ||= Java::JavaUtil::LinkedHashSet.new
+    end
+
+    # Augments {CaRuby::Resource#validate} to verify that this SpecimenRequirement does not have multiple non-aliquot
+    # derivatives, which is disallowed by caTissue.
+    #
+    # caTissue alert - multiple SpecimenRequirement non-aliquot derivatives is accepted by caTissue but results
+    # in obscure downstream errors (cf. Bug #151).
+    #
+    # Raises ValidationError if this SpecimenRequirement has multiple non-aliquot derivatives.
+    def validate
+      super
+      if multiple_derivatives? then raise ValidationError.new("Multiple derivatives not supported by caTissue") end
+    end
+
+    # Creates a SpecimenRequirement of the given subclass type for the given CollectionProtocolEvent event.
+    # The type is a SpecimenRequirement subclass name without the +SpecimenRequirement+ suffix, e.g.
+    # +Tissue+. Lower-case, underscore symbols are supported and preferred, e.g. the
+    # :tissue type creates a TissueSpecimenRequirement.
+    #
+    # The optional params argument are attribute => value associations, e.g.
+    #   SpecimenRequirement.create_requirement(:tissue, event, :specimen_type => 'RNA')
+    def self.create_requirement(type, event, params=Hash::EMPTY_HASH)
+      # make the class name by joining the camel-cased type prefix to the subclass suffix
+      class_name = type.to_s.classify + self.qp
+      begin
+        klass = CaTissue.const_get(class_name)
+      rescue
+        raise ArgumentError.new("Unsupported requirement type: #{type}; #{class_name} must be a subtype of #{self}")
+      end
+      klass.new(params.merge(:collection_protocol_event => event))
+    end
+
+    # Returns the {#collection_event} protocol, if any.
+    def collection_protocol
+      collection_event.protocol if collection_event
+    end
+
+    protected
+
+    # Returns the required attributes which are nil for this domain object.
+    # Overrides the CaRuby::Resource method to handle caTissue Bug #67 - SpecimenRequirement activityStatus cannot be set.
+    def missing_mandatory_attributes
+      invalid = super
+      # caTissue alert - Special case: work around caTissue Bug #67
+      if invalid.include?(:activity_status) then
+        invalid.delete(:activity_status)
+      end
+      # end of workaround
+      invalid
+    end
+
+    private
+
+    # Returns whether this SpecimenRequirement has multiple non-aliquot derivatives.
+    def multiple_derivatives?
+      children.size > 1 and children.any? { |drv| not drv.aliquot? }
+    end
+
+    # Adds the following default values, if necessary:
+    # * a generic SpecimenCharacteristics
+    # * the parent collection_event, if this SpecimenRequirement is derived
+    def add_defaults_local
+      super
+      self.collection_event ||= parent.collection_event if parent
+      self.specimen_characteristics ||= CaTissue::SpecimenCharacteristics.new
+    end
+  end
+end

data/lib/catissue/domain/storage_container.rb

@@ -0,0 +1,204 @@
+require 'enumerator'
+require 'caruby/util/partial_order'
+require 'catissue/util/storage_type_holder'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.StorageContainer')
+
+  # The +caTissue+ +StorageContainer+ domain class wrapper.
+  class StorageContainer
+    include StorageTypeHolder, Resource
+    
+    # caTissue alert - Bug #64: Some domain collection properties not initialized.
+    # Initialize specimen_positions if necessary. 
+    #
+    # @return [Java::JavaUtil::Set] the positions
+    def specimen_positions
+      getSpecimenPositionCollection or (self.specimen_positions = Java::JavaUtil::LinkedHashSet.new)
+    end
+
+    # Sets the storage type to the given value. Each empty holds collection is initialized
+    # from the corresponding StorageType holds collection.
+    def storage_type=(value)
+      if value and holds_storage_types and holds_storage_types.empty? then
+        holds_storage_types.merge!(value.holds_storage_types)
+      end
+      if value and holds_specimen_array_types and holds_specimen_array_types.empty? then
+        holds_specimen_array_types.merge!(value.holds_specimen_array_types)
+      end
+      if value and holds_specimen_classes and holds_specimen_classes.empty? then
+        holds_specimen_classes.merge!(value.holds_specimen_classes)
+      end
+      setStorageType(value)
+    end
+    
+    def located_at_position=(value)
+      setLocatedAtPosition(value)
+    end
+
+    add_attribute_aliases(:container_type => :storage_type)
+
+    # Aternative to the inherited secondary key +name+.
+    set_alternate_key_attributes(:site, :barcode)
+
+    add_mandatory_attributes(:site, :storage_type)
+
+    qualify_attribute(:collection_protocols, :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)
+
+    def initialize(params=nil)
+      super(params)
+      # JRuby alert - specimen_positions is sometimes unrecognized unless primed with respond_to? call
+      respond_to?(:specimen_positions)
+      # work around caTissue Bug #64
+      self.specimen_positions ||= Java::JavaUtil::LinkedHashSet.new
+    end
+
+    # Corrects the +caTissue+ +occupied_positions+ method to include +specimen_positions+.
+    def all_occupied_positions
+      subcontainer_positions.union(specimen_positions)
+    end
+
+    alias :add_local :add
+
+    # Moves the given Storable from its current Position, if any, to this Container at the optional
+    # coordinate. The default coordinate is the first available slot within this Container.
+    # The storable Storable position is updated to reflect the new location. Returns self.
+    #
+    # If there is no coordinate and this container cannot hold the storable type, then the
+    # storable is added to a subcontainer which can hold the storable type.
+    #
+    # @param [Storable] the item to add
+    # @param [Coordinate] the storage location (default is first available location)
+    # @return [StorageContainer] self
+    # @raise [IndexError] if this Container is full
+    # @raise [IndexError] if the row and column are given but exceed the Container bounds
+    def add(storable, coordinate=nil)
+      return add_local(storable, coordinate) if coordinate
+      add_to_existing_container(storable) or add_to_new_subcontainer(storable) or out_of_bounds(storable)
+      self
+    end
+
+    alias :<< :add
+    
+    # Finds the container with the given name, or creates a new container
+    # of the given type if necessary.
+    #
+    # @param [String] the container search name
+    # @param [CaTissue::StorageContainer] the container type
+    # @return a container with the given name
+    def find_subcontainer(name, type)
+      logger.debug { "Finding box with name #{name}..." }
+      ctr = CaTissue::StorageContainer.new(:name => name)
+      if ctr.find then
+        logger.debug { "Container found: #{ctr}." }
+      else
+        logger.debug { "Container not found: #{name}." }
+        create_subcontainer(name, type)
+      end
+      box
+    end
+
+    # @return a new Container with the given name and type in this Container
+    def create_subcontainer(name, type)
+      logger.debug { "Creating #{qp} subcontainer of type #{type} with name #{name}..." }
+      ctr = type.create_container(:name => name, :site => site)
+      self << ctr
+      ctr.create
+      logger.debug { "Made #{self} subcontainer #{ctr}." }
+      ctr
+    end
+
+    protected
+    
+    # Returns the the content collection to which the storable is added, specimen_positions
+    # if storable is a Specimen, container_positions otherwise.
+    def content_collection_for(storable)
+      CaTissue::Specimen === storable ? specimen_positions : super
+    end
+
+    # Adds the given storable to a container within this StorageContainer's hierarchy.
+    #
+    # @param @storable (see #add)
+    # @return [StorageContainer, nil] self if added, nil otherwise
+    def add_to_existing_container(storable)
+      # the subcontainers in column, row sort order
+      scs = subcontainers.sort { |sc1, sc2| sc1.position.location <=> sc2.position.location }
+      # the first subcontainer that can hold the storable is preferred
+      if scs.detect { |ctr| ctr.add_to_existing_container(storable) if StorageContainer === ctr } then
+        self
+      elsif can_hold_child?(storable) then
+        add_local(storable)
+      end
+    end
+
+    # Creates a subcontainer which holds the given storable. Creates nested subcontainers as necessary.
+    #
+    # @param @storable (see #add)
+    # @return [StorageContainer, nil] self if a subcontainer was created, nil otherwise
+    def add_to_new_subcontainer(storable)
+      # the subcontainers in column, row sort order
+      scs = subcontainers.sort { |sc1, sc2| sc1.position.location <=> sc2.position.location }
+      # the first subcontainer that can hold the new subcontainer is preferred
+      if scs.detect { |ctr| ctr.add_to_new_subcontainer(storable) if StorageContainer === ctr } then
+        self
+      elsif not full? then
+        create_subcontainer_for(storable)
+      end
+    end
+
+    # @param [Storable] (see #add)
+    # @return whether this StorageContainer is not full and can hold the given item's StorableType
+    def can_hold_child?(storable)
+      st = storable.storable_type
+      not full? and child_types.any? { |ct| CaRuby::Resource.value_equal?(ct, st) }
+    end
+
+    private
+
+    # Adds the follwing defaults:
+    # * the default child_types are this container's CaTissue::ContainerType child_types.
+    # * the default site is the parent container site, if any.
+    def add_defaults_local
+      super
+      if child_types.empty? and container_type and not container_type.child_types.empty? then
+        container_type.child_types.each { |type| add_child_type(type) }
+      end
+      # Although this default is set by the caTissue app, it is good practice to do so here
+      # for clarity.
+      self.site ||= parent.site if parent
+    end
+
+    # @see #add_to_new_subcontainer
+    def create_subcontainer_for(storable)
+      # the StorageType path to storable
+      type_path = type_path_to(storable) || return
+      # create a container for each type leading to storable and add it to the parent container
+      ctr = type_path.reverse.inject(storable) do |occ, type|
+        subctr = type.create_container
+        subctr.site = site
+        logger.debug { "Created #{qp} #{subctr.container_type.name} subcontainer #{subctr} to hold #{occ}." }
+        subctr << occ
+      end
+      add_local(ctr)
+    end
+
+    # Returns a StorageType array from a child StorageType to a descendant StorageType which can
+    # hold the given storable, or nil if no such path exists.
+    def type_path_to(storable)
+      holds_storage_types.detect_value { |type| type.path_to(storable) }
+    end
+
+    private
+
+    def out_of_bounds(storable)
+      raise IndexError.new("Container #{name} does not have an available position for #{storable}")
+    end
+  end
+end