caruby-tissue 1.2.1

data/lib/catissue/domain/collection_protocol.rb

@@ -0,0 +1,177 @@
+require 'date'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.CollectionProtocol')
+
+  # The CollectionProtocol domain class.
+  class CollectionProtocol
+    include Resource
+    
+    # caTissue alert - Bug #64: Some domain collection properties not initialized.
+    # Initialize consent_tiers if necessary. 
+    #
+    # @return [Java::JavaUtil::Set] the tiers
+    def consent_tiers
+      getConsentTierCollection or (self.consent_tiers = Java::JavaUtil::LinkedHashSet.new)
+    end
+
+    add_attribute_aliases(:events => :collection_protocol_events, :registrations => :collection_protocol_registrations)
+
+    set_secondary_key_attributes(:short_title)
+
+    add_attribute_defaults(:consents_waived => false, :aliquot_in_same_container => false)
+
+    add_mandatory_attributes(:aliquot_in_same_container, :collection_protocol_events, :consents_waived, :enrollment, :start_date, :title)
+
+    add_dependent_attribute(:collection_protocol_events)
+
+    add_dependent_attribute(:consent_tiers)
+
+    # 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)
+
+    # caTissue alert - Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    # Create CollectionProtocol in API ignores startDate.
+    set_attribute_type(:coordinators, CaTissue::User)
+
+    # caTissue alert - Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    # Create CollectionProtocol in API ignores startDate.
+    qualify_attribute(:coordinators, :fetched)
+
+    def initialize(params=nil)
+      super
+      respond_to?(:consent_tiers)
+      # work around caTissue Bug #64 - consent tiers is nil rather than an empty set
+      self.consent_tiers ||= Java::JavaUtil::LinkedHashSet.new
+    end
+
+    # Returns all participants registered in this protocol.
+    def participants
+      registrations.nil? ? [] : registrations.map { |reg| reg.participant }
+    end
+
+    # Overrides the Java CollectionProtocol hashCode to make the hash insensitive to identifier assignment.
+    #
+    # @see #==
+    def hash
+      # caTissue alert - bad caTissue API hashCode leads to ugly cascading errors when using a CP in a Set
+      (object_id * 31) + 17
+    end
+
+    # Returns whether other is {#equal?} to CollectionProtocol.
+    #
+    # This method is a work-around for caTissue Bug #70: CollectionProtocol and non-CollectionProtocol are equal in caTissue 1.1.
+    def ==(other)
+      object_id == other.object_id
+    end
+
+    alias :eql? :==
+
+    # Returns a new CollectionProtocolRegistration for the specified participant in this CollectionProtocol with
+    # optional +protocol_participant_identifier+ ppi.
+    def register(participant, ppi=nil)
+      CollectionProtocolRegistration.new(:participant => participant, :protocol => self, :protocol_participant_identifier => ppi)
+    end
+
+    # Returns the CollectionProtocolRegistration for the specified participant in this CollectionProtocol,
+    def registration(participant)
+      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
+    end
+
+    # Returns the specimens collected from the given participant for this CollectionProtocol,
+    # or all specimens in this protocol if participant is nil.
+    def specimens(participant=nil)
+      if participant.nil? then return registrations.map { |reg| reg.specimens }.flatten end
+      reg = registration(participant)
+      reg.nil? ? Array::EMPTY_ARRAY : reg.specimens
+    end
+
+    # Adds specimens to this protocol. Arguments:
+    # * participant - the Participant from whom the specimen is collected
+    # * biospecimens - the collected top-level underived specimens
+    # * params - additional SCG parameters as described in {SpecimenCollectionGroup#merge} method
+    # If params does not include a :collectionProtocolEvent parameter, then the SCG is assigned
+    # to the first collection event in this protocol.
+    # If params does not include a :specimen_collection_site parameter, then the SCG is assigned
+    # to the participant's collection site as determined by {Participant#collection_site}, if that
+    # can be uniquely determined.
+    #
+    # This add_specimens method adds the following association to params before calling the
+    # SpecimenCollectionGroup constructor:
+    # * :registration => a new CollectionProtocolRegistration for this protocol and the specified participant
+    # If there is no :name parameter, then this method builds a new unique SCG name as this
+    # CollectionProtocol's name followed by a unique suffix.
+    #
+    # Returns a new SpecimenCollectionGroup for the given participant containing the specimens.
+    #
+    # Raises ArgumentError if the SpecimenCollectionGroup does not include all required attributes.
+    def add_specimens(*specimens_and_params)
+      params = specimens_and_params.pop
+      spcs = specimens_and_params
+      # validate arguments
+      unless params then
+        raise ArgumentError.new("Collection parameters are missing when adding specimens to protocol #{self}")
+      end
+      # there must be a participant
+      pnt = params.delete(:participant)
+      unless pnt then
+        raise ArgumentError.new("Participant missing from collection parameters: #{params.qp}")
+      end
+      # there must be a receiver
+      unless params[:receiver] then
+        raise ArgumentError.new("Receiver missing from collection parameters: #{params.qp}")
+      end
+      # the required registration
+      params[:registration] ||= registration(pnt) || make_cpr(pnt)
+      # the new SCG
+      scg = SpecimenCollectionGroup.new(params)
+      # set each Specimen SCG
+      spcs.each { |spc| spc.specimen_collection_group = scg }
+      scg
+    end
+
+    private
+
+    # Sets the defaults as follows:
+    # * The start date is set to now.
+    # * The title is set to the short title.
+    # * If there is no CP coordinator and there is exactly one site with a coordinator, then the
+    #   default CP coordinator is the site coordinator.
+    # * If there is no CP site and there is exactly one coordinator site, then the default CP site
+    #   is the coordinator site.
+    def add_defaults_local
+      super
+      self.title ||= short_title
+      self.short_title ||= title
+      self.start_date ||= Java::JavaUtil::Date.new
+      if coordinators.empty? and sites.size == 1 then
+        coord = sites.first.coordinator
+        coordinators << coord if coord
+      elsif sites.empty? and coordinators.size == 1 then
+        site = coordinators.first.sites.first
+        sites << site if site
+      end
+      make_default_collection_event unless events.detect { |evt| CollectionProtocolEvent === evt }
+    end
+
+    def make_default_collection_event
+      # make this protocol's CPE
+      cpe = CollectionProtocolEvent.new(:protocol => self)
+      # make a tissue requirement
+      CaTissue::TissueSpecimenRequirement.new(
+        :collection_event => cpe,
+        :specimen_characteristics => CaTissue::SpecimenCharacteristics.new)
+    end
+    
+    def make_cpr(participant)
+      CollectionProtocolRegistration.new(:participant => participant, :protocol => self)
+    end
+  end
+end

data/lib/catissue/domain/collection_protocol_event.rb

@@ -0,0 +1,108 @@
+require 'caruby/util/collection'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.CollectionProtocolEvent')
+
+  # The CollectionProtocolRegistration domain class.
+  class CollectionProtocolEvent
+    include Resource
+    
+    # caTissue alert - Bug #64: Some domain collection properties not initialized.
+    # Initialize specimen_collection_groups if necessary.
+    #
+    # @return [Java::JavaUtil::Set] the SCGs
+    def specimen_collection_groups
+      getSpecimenCollectionGroupCollection or (self.specimen_collection_groups = Java::JavaUtil::LinkedHashSet.new)
+    end
+
+    add_attribute_aliases(:label => :collection_point_label,
+      :protocol => :collection_protocol,
+      :requirements => :specimen_requirements,
+      :event_point => :study_calendar_event_point)
+
+    # CPE secondary key is the CP and collection point.
+    set_secondary_key_attributes(:collection_protocol, :collection_point_label)
+
+    # CPE alternate key is the CP and event point.
+    set_alternate_key_attributes(:collection_protocol, :study_calendar_event_point)
+
+    # Default event point is day one.
+    add_attribute_defaults(:study_calendar_event_point => 1.0)
+
+    add_mandatory_attributes(:collection_protocol, :clinical_diagnosis, :specimen_requirements)
+
+    # caTissue alert - specimen_requirements is a cascaded dependent, but it is not fetched.
+    # It is marked as auto-generated, since it must be refetched and matched on CPE create.
+    # CollectionProtocol create cascades through each dependent CPE to each SpecimenRequirement.
+    # TODO - confirm that the :autogenerated flag is necessary.
+    add_dependent_attribute(:specimen_requirements, :autogenerated, :unfetched)
+
+    # The event point used for saving this CollectionProtocolEvent if none other is set.
+    DEFAULT_EVENT_POINT = 1.0
+
+    def initialize(params=nil)
+      super
+      respond_to?(:specimen_collection_groups)
+      # work around caTissue Bug #64
+      self.specimen_collection_groups ||= Java::JavaUtil::LinkedHashSet.new
+    end
+
+    # Overrides {CaRuby::ResourceAttributes#mandatory_attributes} to correct the following caTissue bug:
+    #
+    # caTissue alert - specimen_collection_site is incorrectly attached in the caTissue class model
+    # to AbstractSpecimenCollectionGroup rather than SpecimenCollectionGroup. Since CollectionProtocolEvent
+    # is a subclass of AbstractSpecimenCollectionGroup and mandatory attributes are inherited,
+    # specimen_collection_site must be listed as optional here to counteract the effect of marking it
+    # as mandatory for a SCG (cf. caTissue Bug #116).
+    def mandatory_attributes
+      @mdtry_attrs_filter ||= @mandatory_attributes.filter { |attr| attr != :specimen_collection_site }
+    end
+
+    # Overrides the Java CollectionProtocolEvent hashCode to make the hash insensitive to identifier assignment.
+    def hash
+      # caTissue alert - caTissue determines the hashCode from the identifier. Consequently, a CollectionProtocolEvent
+      # added to a HashSet without an identifier can no longer find the CPE when it is assigned an identifier.
+      # This bug results in obscure delayed cascade errors. Work-around is to override the hash method in the
+      # Ruby CPE wrapper class.
+      (object_id * 31) + 17
+    end
+
+    # Returns whether other is a CollectionProtocolEvent with the same identifier as this CollectionProtocolEvent,
+    # or the same object_id if this CollectionProtocolEvent's identifier is nil.
+    #
+    # This method is a work-around for caTissue bug: CollectionProtocolEvent and non-CollectionProtocolEvent are equal in caTissue 1.1.
+    def ==(other)
+      object_id == other.object_id
+    end
+
+    alias :eql? :==
+
+    # Removes associations to this registration
+    def delete
+      protocol.events.delete(self) if protocol
+    end
+
+    # Overrides {CaRuby::Resource#references} in the case of the _specimen_requirements_ attribute to select
+    # only top-level SpecimenRequirements not derived from another SpecimenRequirement.
+    def direct_dependents(attribute)
+      if attribute == :specimen_requirements then
+        super.reject { |spc| spc.parent }
+      else
+        super
+      end
+    end
+
+    private
+
+    # Sets the default label to the protcol name followed by the event point.
+    def add_defaults_local
+      super
+      self.label ||= default_label
+    end
+
+    def default_label
+      "#{protocol.short_title.sub(' ', '_')}_#{event_point}" if protocol and protocol.short_title and event_point
+    end
+  end
+end

data/lib/catissue/domain/collection_protocol_registration.rb

@@ -0,0 +1,108 @@
+require 'caruby/util/collection'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.CollectionProtocolRegistration')
+
+  # The CollectionProtocolRegistration domain class.
+  class CollectionProtocolRegistration
+    include Resource
+    
+    # caTissue alert - Bug #64: Some domain collection properties not initialized.
+    # Initialize consent_tier_responses if necessary. 
+    #
+    # @return [Java::JavaUtil::Set] the responses
+    def consent_tier_responses
+      getConsentTierResponseCollection or (self.consent_tier_responses = Java::JavaUtil::LinkedHashSet.new)
+    end
+
+    # Returns whether the consent available flag is equal to the String 'true'. This method converts
+    # the caTissue String to a Boolean.
+    def consent_available
+      getIsConsentAvailable == 'true'
+    end
+
+    # Sets the consent available flag to the specified value. A Boolean value is converted to a String.
+    def consent_available=(value)
+      value = value.to_s if value
+      setIsConsentAvailable(value)
+    end
+
+    # Sets the consent available flag to the specified value. An Integer value is converted to a String.
+    def protocol_participant_identifier=(value)
+      value = value.to_s if value
+      setProtocolParticipantIdentifier(value)
+    end
+
+    add_attribute_aliases("consented?".to_sym => :is_consent_available, :protocol => :collection_protocol,
+      :participant_identifier => :protocol_participant_identifier, :consent_responses => :consent_tier_responses)
+
+    set_secondary_key_attributes(:collection_protocol, :participant)
+
+    set_alternate_key_attributes(:collection_protocol, :protocol_participant_identifier)
+
+    add_attribute_defaults(:activity_status => 'Active')
+
+    add_mandatory_attributes(:registration_date)
+
+    # consent_tier_responses is a cascaded dependent but is not fetched
+    add_dependent_attribute(:consent_tier_responses, :unfetched)
+
+    # The CPR-CP association is bi-directional.
+    set_attribute_inverse(:collection_protocol, :collection_protocol_registrations)
+
+    # The CPR-Participant association is bi-directional.
+    set_attribute_inverse(:participant, :collection_protocol_registrations)
+
+    add_dependent_attribute(:specimen_collection_groups, :logical, :autogenerated)
+
+    # CPR PPI is part of a key if it exists, but is optional.
+    qualify_attribute(:protocol_participant_identifier, :optional)
+
+    # caTissue alert -  Augment the standard metadata storable reference attributes to work around caTissue Bug #150:
+    # Create CollectionProtocol in API ignores startDate.
+    qualify_attribute(:registration_date, :update_only)
+
+    # caTissue alert -  Augment the standard metadata storable reference attributes to work around caTissue Bug #63
+    # that requires a SpecimenCollectionGroup with an identifier which references a CollectionProtocolRegistration
+    # with an identifier to nevertheless hold extraneous CollectionProtocolRegistration content, including the CPR
+    # collection protocol. The referenced CP should not itself cascade to its dependents. This is enforced by a
+    # Catissue::Database work-around.
+    #
+    # caTissue alert - CPR fetches the associated CP. This is unnecessary for the predominant caRuby use case,
+    # where the CP is known when the CPR is fetched. Don't mark the CP as fetched in the CPR metadata, since that
+    # precipitates an unnecessary CP copy/match/merge into a fetched CPR.
+    qualify_attribute(:collection_protocol)
+
+    def initialize(params=nil)
+      super
+      # following line works around an obscure problem whereby CPR init could not call consent_tier_responses below;
+      # TODO - verify that it is still necessary
+      respond_to?(:consent_tier_responses)
+      # work around caTissue Bug #64
+      self.consent_tier_responses ||= Java::JavaUtil::LinkedHashSet.new
+    end
+
+    # Removes associations to this registration
+    def delete
+      participant.collection_registrations.delete(self) if participant
+      protocol.registrations.delete(self) if protocol
+    end
+
+    # @return all specimens collected for this CollectionProtocolRegistration
+    def specimens
+      Flattener.new(specimen_collection_groups.map { |group| group.specimens })
+    end
+
+    private
+
+    # Adds defaults as follows:
+    # * The default registration date is the current time.
+    # * The default PPI is a unique number.
+    def add_defaults_local
+      super
+      self.registration_date ||= Java.now
+      self.protocol_participant_identifier ||= Uniquifier.qualifier.to_s
+    end
+  end
+end

data/lib/catissue/domain/consent_tier_response.rb

@@ -0,0 +1,13 @@
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.ConsentTierResponse')
+
+  class ConsentTierResponse
+    include Resource
+
+    add_mandatory_attributes(:consent_tier, :response)
+
+    add_attribute_defaults(:response => 'Not Specified')
+
+  end
+end

data/lib/catissue/domain/consent_tier_status.rb

@@ -0,0 +1,29 @@
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.ConsentTierStatus')
+
+  class ConsentTierStatus
+    include Resource
+
+    add_mandatory_attributes(:consent_tier, :status)
+
+    add_attribute_defaults(:status => 'Not Specified')
+
+    # Returns whether this ConsentTierStatus is minimally consistent with the other ConsentTierStatus.
+    # This method returns whether the referenced ConsentTier has the same identifer or statement text
+    # as the other referenced ConsentTier.
+    def minimal_match?(other)
+      super and statement_match?(other)
+    end
+
+    private
+
+    # Returns true if this ConsentTierStatus ConsentTier is nil, the other ConsentTierStatus ConsentTier is nil,
+    # both ConsentTier identifiers are equal, or both ConsentTier statements are equal.
+    def statement_match?(other)
+      ct = resume_lazy_loader { consent_tier }
+      oct = other.resume_lazy_loader { other.consent_tier }
+      ct and oct and (ct.identifier == oct.identifier or ct.statement == oct.statement)
+    end
+  end
+end

data/lib/catissue/domain/container.rb

@@ -0,0 +1,234 @@
+require 'caruby/util/coordinate'
+require 'catissue/util/storable'
+require 'catissue/util/location'
+
+module CaTissue
+  # import the Java class
+  java_import('edu.wustl.catissuecore.domain.Container')
+
+  # The +caTissue+ +Container+ domain class wrapper.
+  # Each Container subclass is required to implement the {#container_type} method.
+  class Container
+    include Storable, Resource
+
+    add_attribute_aliases(:position => :located_at_position, :subcontainer_positions => :occupied_positions)
+
+    set_secondary_key_attributes(:name)
+
+    add_attribute_defaults(:activity_status => 'Active', :full => false)
+
+    add_dependent_attribute(:capacity, :logical, :autogenerated)
+
+    # located_at_position is cascaded but not fetched.
+    add_dependent_attribute(:located_at_position, :unfetched)
+
+    # Like SCG, Container name is ignored and assigned by caTissue. Therefore, this
+    # attribute is marked auto-generated.
+    qualify_attribute(:name, :autogenerated)
+
+    # Returns the ContainerType which constrains a Container in its roles as a Storable
+    # occupant rather than a Storable holder. {#storable_type} aliases the _container_type_
+    # defined by every Container subclass.
+    def storable_type
+      # can't alias because container_type is defined by subclasses
+      container_type
+    end
+
+    # @return this Container's ContainerType
+    def container_type
+      if self.class < Container then raise NotImplementedError.new("Container subclass does not implement the container_type method") end
+    end
+
+    def copy(*attributes)
+      ctr = super
+      ctr.container_type = self.container_type if attributes.empty?
+      ctr
+    end
+
+    # Returns the ContainerPosition class which this Container can occupy in its role as
+    # a Storable.
+    def position_class
+      CaTissue::ContainerPosition
+    end
+
+    # Lazy-initializes this Container's capacity to a copy of the {#storable_type} capacity.
+    def capacity
+      # caTissue alert - this override is necessary because the +caTissue+ API does
+      # not make the reasonable assumption that the default Container capacity is the
+      # ContainerType capacity.
+      getCapacity or copy_container_type_capacity
+    end
+
+    def bounds
+      capacity.bounds if capacity
+    end
+
+    # @return the number of rows in this Container
+    def rows
+      capacity.rows
+    end
+
+    # @return the number of columns in this Container
+    def columns
+      capacity.columns
+    end
+
+    # @return this Container's parent container
+    def parent
+      position and position.parent
+    end
+
+    # @return the occupants in this Container's positions.
+    # @see 
+    def occupants
+      all_occupied_positions.wrap { |pos| pos.occupant }
+    end
+
+    alias :contents :occupants
+
+    # Returns whether this Container holds the given item or this Container holds
+    # a subcontainer which holds the item.
+    def include?(item)
+      occupants.detect { |occ| occ == item or occ.include?(item) }
+    end
+
+    # @return the Specimen occupants
+    def specimens
+      occupants.filter { |occ| Specimen === occ }
+    end
+
+    # @return the Container occupants
+    def subcontainers
+      occupants.filter { |occ| Container === occ }
+    end
+
+    # @return the Containers in this StorageContainer hierarchy
+    def subcontainers_in_hierarchy
+      @ctr_enum ||= SUBCTR_VISITOR.to_enum(self)
+    end
+
+    # @return whether this container or a subcontainer in the hierarchy holds the given object
+    def holds?(storable)
+      contents.include?(storable) or subcontainers.any? { |ctr| ctr.holds?(storable) }
+    end
+
+    # @return true if this Container or a subcontainer in the hierarchy can hold the given storable
+    #
+    # @see #can_hold_child?
+    def can_hold?(storable)
+      can_hold_child?(storable) or subcontainers.detect { |ctr| ctr.can_hold?(storable) }
+    end
+
+    # @return true if this Container is not full and the {#container_type} can hold the storable as a child
+    def can_hold_child?(storable)
+      not full? and container_type.can_hold_child?(storable)
+    end
+
+    # @return whether this Container and every subcontainer in the hierarchy are full
+    def completely_full?
+      full? and subcontainers.all? { |ctr| ctr.completely_full? }
+    end
+
+    # Returns -1, 0, or 1 if self is contained in, contains or the same as the other
+    # Container, resp.
+    def <=>(other)
+      raise TypeError.new("Can't compare #{qp} to #{other}") unless StorageContainer === self
+      return 0 if equal?(other) or (name and name == other.name)
+      return 1 if subcontainers.detect { |child| child >= other if StorageContainer === child }
+      -1 if other > self
+    end
+
+    # @return the occupant at the given zero-based row and column, or nil if none
+    def [](column, row)
+      all_occupied_positions.detect_value do |pos|
+        return if row < pos.row
+        next unless row == pos.row
+        pos.occupant if pos.column == column
+      end
+    end
+
+    # 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.
+    #
+    # Raises IndexError if this Container is full.
+    # Raises IndexError if the row and column are given but exceed the Container bounds.
+    def add(storable, coordinate=nil, attribute=nil)
+      validate_type(storable)
+      loc = create_location(coordinate)
+      pos = storable.position || storable.position_class.new
+      pos.location = loc
+      pos.occupant = storable
+      pos.holder = self
+      logger.debug { "Added #{storable.qp} to #{qp} at #{loc.coordinate}." }
+      update_full_flag
+      self
+    end
+
+    alias :<< :add
+
+    protected
+
+    # Returns the the content collection to which the storable is added. This default returns
+    # occupied_positions if storable is a Container, nil otherwise. Subclasses can override.
+    #
+    # @param [Storable] the item to store
+    # @return [<Position>] the occupied positions
+    def content_collection_for(storable)
+      subcontainer_positions if Container === storable
+    end
+
+    private
+
+    # Subcontainer visitor.
+    SUBCTR_VISITOR = CaRuby::ReferenceVisitor.new { [:subcontainers] }
+
+    # @param [Storable] the item to store
+    # @raise [TypeError] if this container cannot hold the storable
+    def validate_type(storable)
+      unless container_type.can_hold_child?(storable) then
+        raise TypeError.new("Container #{self} cannot hold an item of the #{storable} type")
+      end
+    end
+
+    # @param [Coordinate] coordinate the optional location to create
+    # @return [Location] the created location
+    def create_location(coordinate=nil)
+      if coordinate then
+        Location.new(:in => self, :at => coordinate)
+      else
+        first_available_location or raise IndexError.new("Container #{qp} does not have an available location")
+      end
+    end
+
+    # @return [Location] the next available Location in this container, or nil if no unoccupied
+    #   location is available
+    def first_available_location
+      return if full?
+      # look for the first unoccupied location
+      occupied = all_occupied_positions.map { |pos| pos.location }.sort
+      # find a gap, if one exists, otherwise return the next location
+      # after the last occupied location
+      current = Location.new(:in => self, :at => Coordinate.new(0, 0))
+      occupied.each do |loc|
+        break if current < loc
+        current.succ!
+      end
+      current
+    end
+
+    # Copies this Container's ContainerType capacity, if it exists, to the Container capacity.
+    #
+    # @return [Capacity, nil] the initialized capacity, if any
+    def copy_container_type_capacity
+      return unless container_type and container_type.capacity
+      self.capacity = container_type.capacity.copy(:rows, :columns)
+      update_full_flag
+      capacity
+    end
+    
+    def update_full_flag
+      self.full = all_occupied_positions.size == rows * columns
+    end
+  end
+end