caruby-tissue 1.5.6 → 2.1.1

data/lib/catissue/domain/specimen_requirement.rb

@@ -1,11 +1,8 @@
-require 'caruby/util/validation'
+require 'jinx/helpers/validation'
 
 module CaTissue
-  # import the Java class
-  resource_import Java::edu.wustl.catissuecore.domain.SpecimenRequirement
-
   # The SpecimenRequirement domain class.
-  class SpecimenRequirement < CaTissue::AbstractSpecimen
+  class SpecimenRequirement
     # @quirk caTissue Bug #64: Some domain collection properties not initialized.
     #   Initialize specimens if necessary. 
     #
@@ -16,7 +13,11 @@ module CaTissue
 
     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_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)
 
@@ -36,18 +37,18 @@ module CaTissue
     # parent CPE is created.
     qualify_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
+    # The preferred owner attribute evaluation order is the parent specimen, then the CPE.
+    order_owner_attributes(:parent_specimen, :collection_protocol_event)
     
-    # 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.
+    # Returns the SpecimenRequirement in others which matches this SpecimenRequirement in the
+    # scope of an owner CollectionProtocolEvent. This method relaxes
+    # +Jinx::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.class and specimen_type == other.specimen_type and pathological_status == other.pathological_status and
-         characteristics and characteristics.match?(other.characteristics)
+         characteristics and characteristics.matches?(other.characteristics)
       end
     end
 
@@ -95,14 +96,15 @@ module CaTissue
       klass.new(params.merge(:collection_protocol_event => event))
     end
 
-    # Returns the {#collection_event} protocol, if any.
+    # @return [CaTissue::CollectionProtocol] the collection event protocol, if any
     def collection_protocol
       collection_event.protocol if collection_event
     end
 
     protected
 
-    # @quirk caTissue Overrides the CaRuby::Resource method to handle caTissue Bug #67 - SpecimenRequirement activityStatus cannot be set.
+    # @quirk caTissue Overrides the Jinx::Resource method to handle caTissue Bug #67 -
+    #   SpecimenRequirement activityStatus cannot be set.
     #
     # @return [<Symbol>] the required attributes which are nil for this domain object
     def missing_mandatory_attributes
@@ -121,16 +123,16 @@ module CaTissue
       children.size > 1 and children.any? { |drv| not drv.aliquot? }
     end
 
-    # Augments {CaRuby::Resource#validate} to verify that this SpecimenRequirement does not have multiple non-aliquot
-    # derivatives, which is disallowed by caTissue.
+    # Augments +Jinx::Resource.validate+ to verify that this SpecimenRequirement does not have multiple
+    # non-aliquot derivatives, which is disallowed by caTissue.
     #
     # @quirk caTissue multiple SpecimenRequirement non-aliquot derivatives is accepted by caTissue but results
     #   in obscure downstream errors (cf. Bug #151).
     #
-    # @raise [ValidationError] if this SpecimenRequirement has multiple non-aliquot derivatives
+    # @raise [Jinx::ValidationError] if this SpecimenRequirement has multiple non-aliquot derivatives
     def validate_local
       super
-      if multiple_derivatives? then raise ValidationError.new("Multiple derivatives not supported by caTissue") end
+      if multiple_derivatives? then raise Jinx::ValidationError.new("Multiple derivatives not supported by caTissue") end
     end
 
     # Adds the following default values, if necessary:

data/lib/catissue/domain/storage_container.rb

@@ -1,14 +1,11 @@
 require 'enumerator'
-require 'caruby/util/validation'
-require 'caruby/util/partial_order'
-require 'catissue/util/storage_type_holder'
+require 'jinx/helpers/validation'
+require 'jinx/helpers/partial_order'
+require 'catissue/helpers/storage_type_holder'
 
 module CaTissue
-  # import the Java class
-  resource_import Java::edu.wustl.catissuecore.domain.StorageContainer
-
   # The +caTissue+ +StorageContainer+ domain class wrapper.
-  class StorageContainer < CaTissue::Container
+  class StorageContainer
     include StorageTypeHolder
     
     # @quirk caTissue Bug #64: Some domain collection properties not initialized.
@@ -124,10 +121,10 @@ module CaTissue
     #
     # @param [Storable] (see #add)
     # @return [Boolean] whether this container is not full and can hold the given item's
-    #   {CaTissue::StorableType}
+    #   {CaTissue::StorageType}
     def can_hold_child?(storable)
       st = storable.storable_type
-      not full? and child_types.any? { |ct| CaRuby::Resource.value_equal?(ct, st) }
+      not full? and child_types.any? { |ct| Jinx::Resource.value_equal?(ct, st) }
     end
     
     protected
@@ -142,10 +139,10 @@ module CaTissue
     #
     # @param @storable (see #add)
     # @return [StorageContainer, nil] self if added, nil otherwise
-    # @raise [ValidationError] if this container does not have a storage type, or if a circular
+    # @raise [Jinx::ValidationError] if this container does not have a storage type, or if a circular
     #   containment reference is detected
     def add_to_existing_container(storable)
-      if storage_type.nil? then raise ValidationError.new("Cannot add #{storable.qp} to #{qp} with missing storage type") end
+      if storage_type.nil? then raise Jinx::ValidationError.new("Cannot add #{storable.qp} to #{qp} with missing storage type") end
       # the subcontainers in column, row sort order
       scs = subcontainers.sort { |sc1, sc2| sc1.position.coordinate <=> sc2.position.coordinate }
       logger.debug { "Looking for a #{self} subcontainer from among #{scs.pp_s} to place #{storable.qp}..." } unless scs.empty?
@@ -155,7 +152,7 @@ module CaTissue
         # in CaTissue::Database#query_object. The work-around circumvents the bug for now, but
         # it doesn't hurt to check again.
         if identifier and sc.identifier == identifier then
-          raise ValidationError.new("#{self} has a circular containment reference to subcontainer #{sc}")
+          raise Jinx::ValidationError.new("#{self} has a circular containment reference to subcontainer #{sc}")
         end
         # No circular reference; add to subcontainer if possible
         sc.add_to_existing_container(storable) if StorageContainer === sc

data/lib/catissue/domain/storage_type.rb

@@ -1,15 +1,11 @@
-require 'caruby/util/collection'
-require 'caruby/util/partial_order'
-require 'catissue/util/storage_type_holder'
-require 'catissue/domain/hash_code'
+require 'jinx/helpers/partial_order'
+require 'catissue/helpers/storage_type_holder'
+require 'catissue/helpers/hash_code'
 
 module CaTissue
-  # import the Java class
-  resource_import Java::edu.wustl.catissuecore.domain.StorageType
-
   # The StorageType domain class.
-  class StorageType < CaTissue::ContainerType
-    include StorageTypeHolder, PartialOrder, HashCode
+  class StorageType
+    include StorageTypeHolder, Jinx::PartialOrder, HashCode
 
     add_attribute_aliases(:default_temperature => :default_temprature_in_centigrade)
 
@@ -58,7 +54,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 {#equal?} to 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/transfer_event_parameters.rb

@@ -1,13 +1,10 @@
-require 'caruby/util/validation'
-require 'catissue/util/location'
+require 'jinx/helpers/validation'
+require 'catissue/helpers/location'
 
 module CaTissue
-  # import the Java class
-  resource_import Java::edu.wustl.catissuecore.domain.TransferEventParameters
-
   # The +caTissue+ TransferEventParameters class is augmented with zero-based
   # +from_row+, +from_column+, +to_row+ and +to_column+ methods wrapping the corresponding one-based dimension attributes.
-  class TransferEventParameters < CaTissue::SpecimenEventParameters
+  class TransferEventParameters
     add_attribute_aliases(:from_container => :from_storage_container, :to_container => :to_storage_container)
 
     # column and row are the zero-offset counterparts of position_dimension_one and position_dimension_two, resp.

data/lib/catissue/domain/user.rb

@@ -1,31 +1,26 @@
-require 'caruby/util/validation'
-require 'catissue/resource'
-require 'catissue/util/person'
+require 'jinx/helpers/validation'
+require 'catissue/helpers/person'
 
 module CaTissue
-  # import the Java class
-  resource_import Java::edu.wustl.catissuecore.domain.User
-
   # 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 it's accessor method is 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.
-  # @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.
   class User
     include Person
 
     # @quirk caTissue work-around for caTissue Bug #66 - Client missing CSException class et al.
     #   caTissue User class initializes roleId to "", which triggers a client exception on subsequent
     #   getRoleId call. Use a private variable instead and bypass getRoleId.
+    #
+    # @quirk caTissue 1.2 Call to getRoleId results in the following error:
+    #     NoClassDefFoundError: gov/nih/nci/security/dao/SearchCriteria
+    #   This bug is probably a result of caTissue "fixing" Bug #66.
+    #   The work-around to the caTissue bug fix bug is to return nil unless the role id has been set
+    #   by a call to the {#role_id=} setter method.
     def role_id
-      # TODO - uncomment following and get rid of @role_id i.v. when bug is fixed.
-      #value = send(old_method)
-      #return if value == ''
-      #value.to_i
       @role_id
     end
 
@@ -45,18 +40,15 @@ module CaTissue
       setRoleId(value_s)
     end
 
-    # @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
+    if property_defined?(:adminuser) then remove_attribute(:adminuser) end
 
-    # make 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)
 
-    # @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
+    if property_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.
@@ -76,14 +68,15 @@ module CaTissue
     add_mandatory_attributes(:activity_status, :address, :cancer_research_group, :department,
       :email_address, :first_name, :institution, :last_name, :page_of, :role_id)
 
-    # @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 caTissue 1.2 User address can be updated in 1.1.2, but not 1.2. This difference is handled
+    #   by the caRuby {CaTissue::Database} update case logic.
     #
-    # @quirk caRuby adding the :saved_fetch qualifier results in JRuby load_error. TODO - fix this.
+    # @quirk caTissue 1.2 User address is fetched on create in 1.1.2, but not 1.2. This difference is
+    #   handled by the caRuby {CaTissue::Database} create case logic.
     add_dependent_attribute(:address)
 
-    # Password cannot be saved in 1.2.
+    # Password is removed as a visible caRuby attribute, since it is immutable in 1.2 and there
+    # is no use case for its access.
     remove_attribute(:passwords)
 
     set_attribute_inverse(:protocols, :assigned_protocol_users)
@@ -108,7 +101,7 @@ module CaTissue
 
     private
 
-    # By default, the emailAddress is the same as the loginName.
+    # By default, the email address is the same as the login name.
     def add_defaults_local
       super
       self.login_name ||= email_address

data/lib/catissue/{util → helpers}/collectible.rb

@@ -1,7 +1,8 @@
-require 'caruby/util/validation'
+require 'jinx/helpers/validation'
 
 module CaTissue
-  # A Collectible mix-in instance can hold a #{ReceivedEventParameters} and a #{CollectedEventParameters}.
+  # A Collectible mix-in instance can hold a #{CaTissue::ReceivedEventParameters} and a
+  # #{CaTissue::CollectedEventParameters}.
   module Collectible
     # Builds this collectible domain object's SpecimenEventParameters from atomic parameters.
     #
@@ -9,7 +10,7 @@ module CaTissue
     #   scg = CaTissue::SpecimenCollectionGroup.new(..., :collector => collector, :receiver => receiver)
     #   scg.collection_event_parameters.user #=> collector
     #   scg.received_event_parameters.user #=> receiver
-    # @param (see CaRuby::Resource#merge_attributes)
+    # @param (see Jinx::Resource#merge_attributes)
     # @option opts (see #collect)
     def merge_attributes(other, attributes=nil)
       if Hash === other then
@@ -20,61 +21,65 @@ module CaTissue
       super
     end
 
-    # Collects and receives this {Collectible} with the given options.
+    # Collects and receives this Collectible with the given options.
     #
     # @param (see #extract_event_parameters)
     # @option opts (see #extract_event_parameters)
-    # @return [CaTissue::SpecimenEventParameters] the augmented SEPS
-    # @raise [ValidationError] if this SCG has already been received
+    # @raise [Jinx::ValidationError] if this Collectible has already been received
     def collect(opts)
-      raise ValidationError.new("#{self} is already collected") if received?
+      raise Jinx::ValidationError.new("#{self} is already collected") if received?
       specimen_event_parameters.merge!(extract_event_parameters(opts))
     end
 
-    # Returns whether this SCG has a collected event.
+    # @return [Boolean] whether this Collectible has a collected event.
     def collected?
       collection_event_parameters
     end
 
-    # Returns the User who collected this SCG.
+    # Returns the User who collected this Collectible.
     def collector
       ep = collection_event_parameters
       ep.user if ep
     end
 
-    # @return [Date] the date this SCG was donated by the participant.
+    # @return [Date] the date this Collectible was donated by the participant.
     def collection_timestamp
       ep = collection_event_parameters
       ep.timestamp if ep
     end
 
-    # Returns the CollectionEventParameters for this specimen group.
+    # Returns the CollectionEventParameters for this Collectible.
     def collection_event_parameters
       event_parameters.detect { |ep| CaTissue::CollectionEventParameters === ep }
     end
 
-    # Returns whether this SCG has a received event.
+    # Returns the {CollectibleEventParameters} for this Collectible.
+    def collectible_event_parameters
+      event_parameters.select { |ep| CaTissue::CollectibleEventParameters === ep }
+    end
+
+    # Returns whether this Collectible has a received event.
     def received?
       received_event_parameters
     end
 
-    # Returns the User who received this specimen group.
+    # Returns the User who received this Collectible.
     def receiver
       ep = received_event_parameters
       ep.user if ep
     end
 
-    # Returns the ReceivedEventParameters for this specimen group.
+    # Returns the ReceivedEventParameters for this Collectible.
     def received_event_parameters
       event_parameters.detect { |ep| CaTissue::ReceivedEventParameters === ep }
     end
     
     private
    
-    #  Overrides {CaRuby::Resource#each_defaults_dependent} to visit the {CaTissue::ReceivedEventParameters}.
+    #  Overrides +Jinx::Resource.each_defaultable_reference+ to visit the +CaTissue::ReceivedEventParameters+.
     #
-    # @yield (see CaRuby::Resource#each_defaults_dependent)
-    def each_defaults_dependent
+    # @yield (see Jinx::Resource#each_defaultable_reference)
+    def each_defaultable_reference
       # visit ReceivedEventParameters first
       rep = received_event_parameters
       yield rep if rep
@@ -107,7 +112,7 @@ module CaTissue
       cdate = opts.delete(:collected_date)
       cdate ||= rdate
       eps << CaTissue::SpecimenEventParameters.create_parameters(:collection, self, :user => cltr, :timestamp => cdate)
-      logger.debug { "SCG #{self} event parameters: #{eps.pp_s(:single_line)}" }
+      logger.debug { "Collectible #{self} event parameters: #{eps.pp_s(:single_line)}" }
       eps
     end
   end

data/lib/catissue/helpers/collectible_event_parameters.rb

@@ -0,0 +1,68 @@
+module CaTissue
+  # A CollectibleEventParameters is a SpecimenEventParameters which pertains to Specimen
+  # or SpecimenCollectionGroup collection at the point of tissue acquisition from the participant
+  # 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 +Jinx::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) }
+    end
+    
+    private
+    
+    # Injects validations into the owner writer methods for the following constraints:
+    # * a CollectibleEventParameters instance cannot be owned by both a specimen and a SCG.
+    # * a Collectible cannot include more than one CollectibleEventParameters instance of a given type.
+    #
+    # @param [Class] klass the including class
+    def self.included(klass)
+      klass.class_eval do
+        [:specimenCollectionGroup, :specimen].each do |pa|
+          wtr = "#{pa}=".to_sym
+          redefine_method(wtr) do |base|
+            lambda do |obj|
+              validate_no_owner_confict(pa, obj)
+              validate_exclusivity(pa, obj)
+              send(base, obj)
+            end
+          end
+          logger.debug { "Redefined the #{qp} #{pa} method to ensure the owner exclusivity constraints." }
+        end
+      end
+    end
+    
+    # @param attribute the owner attribute to set
+    # @param obj the owner to set
+    # @raise [Jinx::ValidationError] if this event parameters object already has a different owner attribute referent
+    def validate_no_owner_confict(attribute, obj)
+      return if obj.nil?
+      self.class.owner_attributes.each do |oa|
+        next if oa == attribute
+        other = send(oa)
+        if other then
+          raise Jinx::ValidationError.new("Cannot add #{qp} to #{attribute} #{obj}, since it is already owned by #{other}")
+        end
+      end
+    end
+    
+    def validate_exclusivity(attribute, obj)
+      return if obj.nil?
+      inv = self.class.property(attribute).inverse
+      other = obj.send(inv).detect { |ep| self.class === ep }
+      if other and other != self then
+        raise Jinx::ValidationError.new("Cannot add #{self} to #{attribute} #{obj}, since #{obj} already includes #{other}")
+      end
+    end
+    
+    # Overrides +Jinx::Migratable.migratable__preferred_owner+ to give preference to
+    # a SCG over a Specimen.
+    #
+    # @param (see Jinx::Migratable#migratable__migrate_owner)
+    def migratable__preferred_owner(candidates)
+      candidates.detect { |obj| CaTissue::SpecimenCollectionGroup === obj }
+    end
+  end
+end