caruby-tissue 1.5.6 → 2.1.1

data/lib/catissue/domain/abstract_domain_object.rb

@@ -0,0 +1,5 @@
+module CaTissue
+  class AbstractDomainObject
+    property :identifier, :primary_key
+  end
+end

data/lib/catissue/domain/abstract_position.rb

@@ -1,12 +1,10 @@
-require 'catissue/util/position'
+require 'catissue/helpers/position'
 
 module CaTissue
-  resource_import Java::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.
+  # methods.
   class AbstractPosition
     include Position
 
@@ -19,4 +17,4 @@ module CaTissue
     # add the synthetic {#location} attribute
     add_attribute(:location, Location)
   end
-end
+end

data/lib/catissue/domain/abstract_specimen.rb

@@ -1,13 +1,11 @@
 require 'set'
-require 'caruby/util/inflector'
-require 'caruby/util/validation'
+require 'jinx/helpers/inflector'
+require 'jinx/helpers/validation'
 
 module CaTissue
-  resource_import Java::edu.wustl.catissuecore.domain.AbstractSpecimen
-  
   class AbstractSpecimen
     # 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.
+    # the shortcut symbols :fresh, :fixed and +:frozen+.
     #
     # @param [String, Symbol, nil] value the value to set
     def specimen_type=(value)
@@ -28,7 +26,7 @@ module CaTissue
     add_mandatory_attributes(:lineage, :pathological_status, :specimen_class, :specimen_type, :specimen_characteristics)
 
     # @quirk caTissue Specimen characteristics are auto-generated but SpecimenRequirement
-    #   characteristics are not. It is safe to set the :autogenerated flag for both
+    #   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.
     #
@@ -40,33 +38,42 @@ module CaTissue
     #   differs from the existing id.
     #
     # @quirk caTissue Unlike other dependents, AbstractSpecimen characteristics, events and child
-    #   specimens have cascade style 'all'. This implies that an AbstractSpecimen update does not
+    #   specimens have cascade style +all+. This implies that an AbstractSpecimen update does not
     #   create a referenced dependent. AbstractSpecimen create cascades to create and AbstractSpecimen
     #   update cascades to update, but AbstractSpecimen update does not cascade to create.
-    #   The :no_cascade_update_to_create flag is set to handle this feature of cascade style 'all'.
+    #   The +:no_cascade_update_to_create flag+ is set to handle this feature of cascade style +all+.
     qualify_attribute(:specimen_characteristics, :cascaded, :fetched, :autogenerated, :no_cascade_update_to_create)
 
-    # The :no_cascade_update_to_create flag is set since events has cascade style 'all'.
-    add_dependent_attribute(:specimen_events, :create_only, :disjoint, :no_cascade_update_to_create)
-   
+    # The +:no_cascade_update_to_create+ flag is set since specimen_events has cascade style +all+.
+    add_dependent_attribute(:specimen_event_parameters, :disjoint)
+    
     set_attribute_inverse(:parent_specimen, :child_specimens)
     
-    add_dependent_attribute(:child_specimens, :unfetched, :no_cascade_update_to_create)
+    # @quirk caTissue A Specimen update cascades to a child specimen, but the update is not reflected
+    #   in the caTissue updateObject result. Work-around is to fetch the updated child from the
+    #   database to ensure that the database content reflects the intended update argument.
+    #
+    # The +:no_cascade_update_to_create+ flag is set since child_specimens has cascade style +all+.
+    add_dependent_attribute(:child_specimens, :unfetched, :fetch_saved, :no_cascade_update_to_create)
 
+    # The specimen_class attribute constants.
     class SpecimenClass
       TISSUE = 'Tissue'
       FLUID = 'Fluid'
       MOLECULAR = 'Molecular'
       CELL = 'Cell'
 
-      EXTENT = Set.new([TISSUE, FLUID, MOLECULAR, CELL])
-
+      # The standard units used for each specimen class.
       UNIT_HASH = {TISSUE => 'gm', FLUID => 'ml', MOLECULAR => 'ug'}
 
-      # @return whether the value is an accepted tissue class value
+      # @return [Boolean] whether the value is an accepted tissue class value
       def self.include?(value)
         EXTENT.include?(value)
       end
+      
+      private
+
+      EXTENT = Set.new([TISSUE, FLUID, MOLECULAR, CELL])
     end
 
     # Initializes this AbstractSpecimen. The default +specimen_class+ is inferred from this
@@ -76,33 +83,33 @@ module CaTissue
       self.specimen_class ||= infer_specimen_class(self.class)
     end
 
-    # @return whether this specimen is derived from a parent specimen
+    # @return [Boolean] whether this specimen is derived from a parent specimen
     def derived?
-      not parent.nil?
+      !!parent
     end
 
-    # @return whether this specimen is an aliquot
+    # @return [Boolean] whether this specimen is an aliquot
     def aliquot?
       lineage ||= default_lineage
       lineage == 'Aliquot'
     end
 
-    # @return this specimen's aliquots
+    # @return [<AbstractSpecimen>] this specimen's aliquots
     def aliquots
       children.filter { |child| child.aliquot? }
     end
 
-    # @return whether this specimen's type is 'Fresh Tissue'
+    # @return [Boolean] whether this specimen's type is 'Fresh Tissue'
     def fresh?
       specimen_type == 'Fresh Tissue'
     end
 
-    # @return whether this specimen's type starts with 'Fixed'
+    # @return [Boolean] whether this specimen's type starts with 'Fixed'
     def fixed?
       specimen_type =~ /^Fixed/
     end
 
-    # @return whether this specimen's type starts with 'Frozen'
+    # @return [Boolean] whether this specimen's type starts with 'Frozen'
     def frozen?
       specimen_type =~ /^Frozen/
     end
@@ -119,11 +126,12 @@ module CaTissue
       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.
+    # Derives a new specimen from this specimen. The options are described in
+    # {Specimen.create_specimen}, with one addition:
+    # * +:count+(+Integer+) - 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
+    # If the +:count+ option is greater than one and the +:specimen_class+,
+    # +:specimen_type+ and +:specimen_characteristics+ options 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)
@@ -144,50 +152,52 @@ module CaTissue
     #
     # 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.
+    # e.g. +3090_3+ for the third child in the parent specimen with label +3090+.
     #
-    # @return the new derived specimen if _count_ is one, otherwise an Array of _count_ derived specimens
-    # @raise [ValidationError] if an aliquoted parent available quantity is not greater than zero
+    # @param [{Symbol => Object}, nil] opts the attribute => value hash
+    # @return [AbstractSpecimen, <AbstractSpecimen>] the new derived specimen if the +:count+ option
+    #   is missing or one, otherwise an Array of _count_ derived specimens
+    # @raise [Jinx::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={})
+    def derive(opts=Hash::EMPTY_HASH)
       # add defaults
       add_defaults if specimen_class.nil?
-      # copy the parameters
-      params = params.dup
+      # copy the option hash
+      opts = opts.dup
       # standardize the requirement param, if any
-      rqmt = params.delete(:requirement)
-      params[:specimen_requirement] ||= rqmt if rqmt
+      rqmt = opts.delete(:requirement)
+      opts[: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
+      unless opts.has_key?(:specimen_requirement) then
+        opts[:specimen_class] ||= self.specimen_class ||= infer_specimen_class
+        opts[:specimen_type] ||= self.specimen_type
       end
-      unless Class === params[:specimen_class] then
-        params[:specimen_class] = infer_class(params)
+      unless Class === opts[:specimen_class] then
+        opts[:specimen_class] = infer_class(opts)
       end
-      count = params.delete(:count)
+      count = opts.delete(:count)
       count ||= 1
       aliquot_flag = false
-      if count > 1 and params[:specimen_class] == self.class and params[:specimen_type] == self.specimen_type then
+      if count > 1 and opts[:specimen_class] == self.class and opts[:specimen_type] == self.specimen_type then
         # aliquots share the specimen_characteristics
-        child_chr = params[:specimen_characteristics] ||= specimen_characteristics
+        child_chr = opts[:specimen_characteristics] ||= specimen_characteristics
         aliquot_flag = child_chr == specimen_characteristics
       end
       # set aliquot parameters if necessary
-      if aliquot_flag then set_aliquot_parameters(params, count) end
+      if aliquot_flag then set_aliquot_parameters(opts, count) end
       # make the derived specimens
-      count == 1 ? create_derived(params) : Array.new(count) { create_derived(params) }
+      count == 1 ? create_derived(opts) : Array.new(count) { create_derived(opts) }
     end
 
     # Returns whether this AbstractSpecimen is minimally consistent with the other specimen.
-    # This method augments the {CaRuby::Resource#minimal_match?} with an additional restriction
+    # This method augments the +Jinx::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?)
+    # @param (see Jinx::Resource#minimal_match?)
+    # @return (see Jinx::Resource#minimal_match?)
     def minimal_match?(other)
       super and tolerant_match?(other, TOLERANT_MATCH_ATTRS)
     end
@@ -206,12 +216,12 @@ module CaTissue
     # @param [Integer] count the number of aliquots
     def set_aliquot_parameters(params, count); end
 
-    # Overrides {CaRuby::Resource#each_defaults_dependent} to visit the {CaTissue::SpecimenCharacteristics}.
+    # Overrides +Jinx::Resource.each_defaultable_reference} to visit the {CaTissue::SpecimenCharacteristics+.
     # The characteristics are not dependent since they can be shared among aliquots.
     # However, the defaults should be added to them. Do so here.
     #
-    # @yield (see CaRuby::Resource#each_defaults_dependent)
-    def each_defaults_dependent
+    # @yield (see Jinx::Resource#each_defaultable_reference)
+    def each_defaultable_reference
       super { |dep| yield dep }
       yield characteristics if characteristics
     end
@@ -228,11 +238,11 @@ module CaTissue
       self.characteristics ||= default_characteristics
     end
 
-    # Returns the Class from the given params hash.If the :specimen_class parameter
+    # 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,
+    # :specimen_class parameter is missing and there is a +:specimen_requirement+ parameter,
     # then the specimen requirement specimen_class attribute value is used.
     #
     # @param [{Symbol => Object}] params the specimen attribute => value hash
@@ -251,19 +261,23 @@ module CaTissue
       CaTissue.const_get(cls_nm)
     end
 
-    # Creates a derived specimen.
+    # Creates a derived specimen. The options is an attribute => value hash. The options
+    # can also include a +:specimen_requirement+. The non-domain attribute values of the
+    # new derived specimen are determined according to the following precedence rule:
+    # 1. The attribute => value option.
+    # 2. The requirement property value.
+    # 3. This specimen's property value.
     #
-    # @param [{Symbol => Object}] params the derived specimen attribute => value hash
-    # @return [Specimen] the derived specimen
-    def create_derived(params)
+    # @param [{Symbol => Object}] opts the derived specimen attribute => value hash
+    # @return [AbstractSpecimen] the derived specimen or requirement
+    def create_derived(opts)
       # 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
+      opts = value_hash(DERIVED_MERGEABLE_ATTRS).merge!(opts) unless opts.has_key?(:specimen_requirement)
+      # Copy this specimen's characteristics, if not already given in the options.
+      opts[:specimen_characteristics] ||= default_derived_characteristics
+      # Make the new specimen.
+      spc = Specimen.create_specimen(opts)
+      # The derived specimen's parent is this specimen.
       spc.parent = self
       spc
     end
@@ -274,8 +288,8 @@ module CaTissue
     # @return [CaTissue::SpecimenCharacteristics, nil] a copy of this Specimen's specimen_characteristics, or nil if none
      def default_derived_characteristics
       chrs = specimen_characteristics || return
-      attrs = chrs.class.nondomain_attributes.reject { |attr| attr == :identifier }
-      chrs.copy(attrs)
+      pas = chrs.class.nondomain_attributes.reject { |pa| pa == :identifier }
+      chrs.copy(pas)
     end
 
     # @return a copy of the parent characteristics, if any, or a new SpecimenCharacteristics otherwise

data/lib/catissue/domain/abstract_specimen_collection_group.rb

@@ -1,6 +1,4 @@
 module CaTissue
-  resource_import Java::edu.wustl.catissuecore.domain.AbstractSpecimenCollectionGroup
-
   class AbstractSpecimenCollectionGroup
     add_attribute_aliases(:diagnosis => :clinical_diagnosis, :site => :specimen_collection_site, :collection_site => :specimen_collection_site)
 
@@ -8,14 +6,13 @@ module CaTissue
 
     add_mandatory_attributes(:activity_status)
 
-    # Overrides {CaRuby::Resource#each_dependent} to exclude Specimens or SpecimenRequirements with a parent,
+    # Overrides +Jinx::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)
+    # @yield (see Jinx::Resource#each_dependent)
+    # @yieldparam (see Jinx::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

@@ -1,6 +1,4 @@
 module CaTissue
-  resource_import Java::edu.wustl.catissuecore.domain.Address
-
   class Address
     # Sets this Address's zip_code to value. The value argument can be nil, a String or an Integer.
     def zip_code=(value)

data/lib/catissue/domain/cancer_research_group.rb

@@ -1,7 +1,4 @@
 module CaTissue
-  # import the Java class
-  resource_import Java::edu.wustl.catissuecore.domain.CancerResearchGroup
-
   # The CancerResearchGroup domain class.
   class CancerResearchGroup
     set_secondary_key_attributes(:name)

data/lib/catissue/domain/capacity.rb

@@ -1,8 +1,6 @@
-require 'caruby/util/coordinate'
+require 'caruby/helpers/coordinate'
 
 module CaTissue
-  resource_import Java::edu.wustl.catissuecore.domain.Capacity
-
   class Capacity
     # 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)
@@ -24,7 +22,7 @@ module CaTissue
 
     add_mandatory_attributes(:one_dimension_capacity, :two_dimension_capacity)
 
-    # Returns the read-only Coordinate with this Capacity's #rows and {#columns}.
+    # Returns the read-only Coordinate with this capacity's rows and columns.
     def bounds
       @bounds ||= Coordinate.new(columns, rows)
     end

data/lib/catissue/domain/check_in_check_out_event_parameter.rb

@@ -1,7 +1,4 @@
 module CaTissue
-  # import the Java class
-  resource_import Java::edu.wustl.catissuecore.domain.CheckInCheckOutEventParameter
-
   class CheckInCheckOutEventParameter
     # The check-in/check-out status permissible values.
     module Status

data/lib/catissue/domain/collection_event_parameters.rb

@@ -1,17 +1,12 @@
-require 'catissue/util/collectible_event_parameters'
-require 'caruby/util/validation'
+require 'catissue/helpers/collectible_event_parameters'
 
 module CaTissue
-  # import the Java class
-  resource_import Java::edu.wustl.catissuecore.domain.CollectionEventParameters
-
   class CollectionEventParameters
     include CollectibleEventParameters
     
     add_attribute_defaults(:collection_procedure => 'Not Specified', :container => 'Not Specified')
     
     # An auto-generated CEP must fetch the user.
-    qualify_attribute(:user, :saved_fetch)
-
+    qualify_attribute(:user, :fetch_saved)
   end
 end

data/lib/catissue/domain/collection_protocol.rb

@@ -1,13 +1,10 @@
 require 'date'
-require 'catissue/domain/hash_code'
+require 'catissue/helpers/hash_code'
 
 module CaTissue
-  # import the Java class
-  resource_import Java::edu.wustl.catissuecore.domain.CollectionProtocol
-
   # The CollectionProtocol domain class.
   #
-  # @quirk caTissue Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+  # @quirk caTissue Augment the standard metadata savable reference attributes to work around caTissue Bug #150:
   #   Create CollectionProtocol in API ignores startDate.
   class CollectionProtocol
     include HashCode
@@ -30,15 +27,15 @@ module CaTissue
 
     add_dependent_attribute(:consent_tiers)
 
-    # @quirk caTissue Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    # @quirk caTissue Augment the standard metadata savable reference attributes to work around caTissue Bug #150:
     #   Create CollectionProtocol in API ignores startDate.
     qualify_attribute(:start_date, :update_only)
 
-    # @quirk caTissue Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    # @quirk caTissue Augment the standard metadata savable reference attributes to work around caTissue Bug #150:
     #   Create CollectionProtocol in API ignores startDate.
     set_attribute_type(:coordinators, CaTissue::User)
 
-    # @quirk caTissue Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    # @quirk caTissue Augment the standard metadata savable reference attributes to work around caTissue Bug #150:
     #   Create CollectionProtocol in API ignores startDate.
     qualify_attribute(:coordinators, :fetched)
 
@@ -67,9 +64,9 @@ module CaTissue
       registrations.detect { |registration| registration.participant == participant }
     end
 
-    # Returns the event in this protocol with the earliest study calendar event point.
-    def first_event
-      events.sort_by { |event| event.event_point or CollectionProtocolEvent::DEFAULT_EVENT_POINT }.first
+    # Returns this protocol's events sorted by study calendar event point.
+    def sorted_events
+      events.sort_by { |ev| ev.event_point || CollectionProtocolEvent::DEFAULT_EVENT_POINT }
     end
 
     # Returns the specimens collected from the given participant for this CollectionProtocol,
@@ -83,7 +80,7 @@ module CaTissue
     # Adds specimens to this protocol. The following parameter options are supported:
     # * :participant - the Participant from whom the specimen is collected
     # * :biospecimens - the collected top-level underived specimens
-    # * additional SCG parameters as described in {SpecimenCollectionGroup#merge}.
+    # * additional SCG parameters as described in {CaTissue::SpecimenCollectionGroup#merge_attributes}.
     #
     # If the options does not include a +:collection_protocol_event+, then the SCG is assigned
     # to the first collection event in this protocol.
@@ -98,7 +95,7 @@ module CaTissue
     #
     # @param [(<Specimen>, {Symbol => Object})] specimens_and_params the specimens to add followed
     #   by the required parameter hash
-    # @return [SpecimenCollectionGroup] a new SCG for the given participant containing the specimens
+    # @return [CaTissue::SpecimenCollectionGroup] a new SCG for the given participant containing the specimens
     # @raise [ArgumentError] if the {SpecimenCollectionGroup} does not include all required attributes
     def add_specimens(*specimens_and_params)
       params = specimens_and_params.pop
@@ -164,10 +161,8 @@ module CaTissue
     def add_default_site
       if coordinators.size == 1 then
         site = coordinators.first.sites.first
-      else
-        site = CaTissue::Site.default_site
-        site.find unless site.identifier
       end
+      site ||= CaTissue::Site.default_site
       sites << site
     end