caruby-tissue 1.2.2 → 1.2.3

data/examples/galena/lib/galena/seed/defaults.rb

@@ -98,11 +98,6 @@ module Galena
         @freezer_type << rack_type
         rack_type << box_type
         @box_type << 'Tissue'
-        
-        # a sample freezer and box
-        frz = CaTissue::StorageContainer.new(:name => 'GTB Freezer 1', :storage_type=>@freezer_type, :site=>@tissue_bank)
-        @box = CaTissue::StorageContainer.new(:name => 'GTB Box 1', :storage_type=>@box_type)
-        frz << @box
       end
     end
   end

data/lib/catissue/annotation/annotatable.rb

@@ -0,0 +1,37 @@
+require 'catissue/annotation/annotatable_class'
+
+module CaTissue
+  # {CaTissue::Resource} annotation hook mix-in.
+  module Annotatable
+    def method_missing(mth, *args)
+      name = mth.to_s
+      # remove trailing assignment '=' character if present
+      attr = name =~ /=$/ ? name.chop.to_sym : mth
+      # If an annotation can be generated on demand, then resend the method.
+      # Otherwise, delegate to super for the standard error.
+      self.class.annotation_attribute?(attr) ? send(mth, *args) : super
+    end
+    
+    # Creates a {Annotation::Proxy} whose hook reference is set to this annotatable object.
+    #
+    # @param [Class] the proxy class
+    # @return [Resource] the new proxy
+    def create_proxy(klass)
+      # make the proxy instance
+      pxy = klass.new
+      # set the proxy hook reference to this hook instance
+      pxy.hook = self
+      logger.debug { "Created #{qp} #{klass.domain_module.qp} annotation proxy #{pxy}." }
+      pxy
+    end
+    
+    # @param [Symbol] attribute the hook -> annotation attribute
+    # @return [Annotation] the hook -> proxy attribute
+    # @raise (see AnnotatableClass#annotation_proxy_attribute)
+    def annotation_proxy(attribute)
+      pxy_attr = self.class.annotation_proxy_attribute(attribute)
+      # the hook -> proxy attribute value
+      send(pxy_attr)
+    end
+  end
+end

data/lib/catissue/annotation/annotatable_class.rb

@@ -0,0 +1,255 @@
+require 'forwardable'
+require 'caruby/util/inflector'
+require 'catissue/annotation/annotation_module'
+
+module CaTissue
+  # Mix-in for extending a caTissue domain class with annotations.
+  module AnnotatableClass
+    
+    # @return [Integer, nil] the the hook class designator that is used by caTissue to persist primary
+    #   annotation objects, or nil if this is not a primary annotation class
+    attr_reader :entity_id
+    
+    def self.extended(klass)
+      super
+      # the annotation name => spec hash 
+      klass.class_eval { extend Forwardable; @ann_spec_hash = {} }
+    end
+    
+    # @return [Integer, nil] this class's entity id, if it exists, otherwise the superclass effective entity id
+    #   if the superclass is an annotation class
+    def effective_entity_id
+      @entity_id or parent_entity_id
+    end
+    
+    # If there is an existing annotation whose proxy accessor is the
+    # given symbol, then return true. Otherwise, attempt to import
+    # an annotation and return whether the import was successful.
+    #
+    # @param [Symbol] symbol the potential accessor attribute
+    # @return [Boolean] whether there is a corresponding annotation
+    def annotation_attribute?(symbol)
+      # load annotations if necessary
+      ensure_annotations_loaded
+      # check for the annotation attribute
+      annotation_defined?(symbol)
+    end
+         
+    # Refines the {CaRuby::ResourceAttributes#toxic_attributes} to exclude annotation attributes.
+    #
+    # @return [<Symbol>] the non-annotation unfetched attributes
+    def toxic_attributes
+      @anntbl_toxic_attrs ||= unfetched_attributes.compose { |attr_md| not attr_md.type < Annotation } 
+    end
+    
+    def annotation_proxy_attribute(ann_attr)
+      annotatable_class_hierarchy.detect_value { |klass| klass.local_annotation_proxy_attribute(ann_attr) }
+    end
+
+    # Makes a new attribute in this hook class for the given annotation proxy domain attribute.
+    # The hook annotation reference attribute delegates to the proxy. This method is intended for
+    # the exclusive use of {Annotation::ProxyClass}.
+    #
+    # @param [AnnotationModule] mod the annotation module
+    # @param [Symbol] attribute the proxy => annotation reference 
+    def create_annotation_attribute(mod, attribute)
+      pxy = mod.proxy
+      pxy_attr = @ann_mod_pxy_hash[mod]
+      ann_attr_md = pxy.attribute_metadata(attribute)
+      # the type referenced by the annotation proxy
+      klass = ann_attr_md.type
+      # create annotation accessors which delegate to the proxy
+      def_delegators(pxy_attr, *ann_attr_md.accessors)
+      logger.debug { "Created #{qp}.#{attribute} which delegates to the annotation proxy #{pxy_attr}." }
+      # add the attribute
+      add_annotation_attribute(attribute, klass)
+    end
+    
+    # Loads the annotations, if necessary, and tries to get the constant again.
+    #
+    # @param [Symbol] symbol the missing constant
+    # @return [AnnotationModule] the imported annotation, if successful
+    # @raise [NameError] if the annotation could not be imported
+    def const_missing(symbol)
+      if annotations_loaded? then
+        super
+      else
+        ensure_annotations_loaded
+        const_get(symbol)
+      end
+    end
+    
+    protected
+    
+    # @return [<AnnotationModule>] the annotation modules in the class hierarchy
+    def annotation_modules
+      @ann_mods ||= load_annotations
+    end
+    
+    # @param [Symbol] ann_attr the annotation attribute
+    # @return [Symbol] the annotation proxy attribute
+    # @raise [TypeError] if the given attribute is not an annotation attribute
+    def local_annotation_proxy_attribute(ann_attr)
+      unless annotation_attribute?(ann_attr) then
+        raise TypeError.new("#{qp} #{ann_attr} is not an annotation attribute")
+      end
+      # the annotation class
+      klass = attribute_metadata(ann_attr).type
+      mod = klass.domain_module
+      @ann_mod_pxy_hash[mod]
+    end    
+    
+    private
+
+    # Loads the annotations defined for this class if necessary.
+    def ensure_annotations_loaded
+      # referencing the annotations loads them
+      annotation_modules
+    end
+    
+    # Loads the annotation modules in the class hierarchy.
+    #
+    # @return [<AnnotationModule>] an Enumerable on the loaded annotation modules
+    def load_annotations
+      @local_ann_mods = load_local_annotations
+      superclass < Annotatable ? @local_ann_mods.union(superclass.annotation_modules) : @local_ann_mods
+    end
+    
+    def parent_entity_id
+      superclass.entity_id if superclass < Annotatable
+    end
+    
+    def annotatable_class_hierarchy
+      class_hierarchy.filter { |klass| klass < Annotatable }
+    end
+    
+    # Sets the annotation service name for the given hook proxy atttribute.
+    # The default service name is the camelized attribute.
+    #
+    # @param [Symbol] attribute the hook proxy atttribute
+    # @param [{Symbol => Object}] opts the annotation options
+    # @option opts [String] :package the package name (default the decapitalized camelized name)
+    # @option opts [String] :service the service name (default the decapitalized underscore name)
+    def add_annotation(name, opts={})
+      # the module spec defaults
+      opts[:package] ||= name.camelize(:lower)
+      opts[:service] ||= name.underscore
+      # add the annotation entry
+      @ann_spec_hash[name.to_sym] = opts
+      logger.info("Added #{qp} annotation named #{name} with package #{opts[:package]} and service #{opts[:service]}.")
+    end
+    
+    # @return [Boolean] whether this annotatable class's annotations are loaded
+    def annotations_loaded?
+      not @ann_mods.nil?
+    end
+    
+    # Loads this class's annotations.
+    #
+    # @return [<AnnotationModule>] the loaded annotation modules
+    def load_local_annotations
+      # the annotation module => proxy hash
+      @ann_mod_pxy_hash = {}
+      # an annotated class has a hook entity id
+      unless @ann_spec_hash.empty? then
+        @entity_id = Annotation::EntityFacade.instance.hook_entity_id(self) 
+      end
+      # build the annotations
+      @ann_spec_hash.map { |name, opts| import_annotation(name, opts) }
+    end
+   
+    # @param [Symbol] attribute the annotation accessor
+    # @return [Module] the annotation module which implements the attribute
+    def annotation_attribute_module(attribute)
+      annotation_modules.detect { |mod| mod.proxy.attribute_defined?(attribute) }
+    end
+
+    # Builds a new annotation module for the given attribute.
+    #
+    # @param [<Symbol>] attribute the proxy attribute to import
+    # @return [Module] the annotation module
+    # @raise [AnnotationError] if there is no annotation proxy class
+    def import_annotation(name, opts)
+      logger.debug { "Importing #{qp} annotation #{name}..." }
+      # make the annotation module scoped by this Annotatable class
+      class_eval("module #{name}; end")
+      mod = const_get(name)
+      # append the AnnotationModule methods
+      AnnotationModule.extend_module(mod, self, opts)
+      # make the proxy attribute
+      create_proxy_attribute(mod)
+      # make the annotation dependent attributes
+      create_annotation_attributes(mod)
+      # add proxy references
+      mod.ensure_proxy_attributes_are_defined
+      mod.add_annotation_dependents
+      logger.debug { "Imported #{qp} annotation #{name}." }
+      mod
+    end
+
+    # Returns whether this class has an annotation whose proxy accessor is the
+    # given symbol.
+    #
+    # @param (see #annotation?)
+    # @return (see #annotation?)
+    # @see #annotation?
+    def annotation_defined?(symbol)
+      attribute_defined?(symbol) and attribute_metadata(symbol).type < Annotation
+    end
+    
+    # Makes an attribute whose name is the demodulized underscored given module name.
+    # The attribute reader creates an {Annotation::Proxy} instance of the method
+    # receiver {Annotatable} instance on demand.
+    # 
+    # @param [AnnotationModule] mod the subject annotation module
+    # @return [Symbol] the proxy attribute
+    def create_proxy_attribute(mod)
+      # the proxy class
+      pxy = mod.proxy
+      # the proxy attribute
+      attr = mod.name.demodulize.underscore.to_sym
+      # define the proxy attribute
+      attr_create_on_demand_accessor(attr) { |obj| obj.create_proxy(pxy) }
+      # add it as a standard (but unpersisted) attribute
+      add_attribute(attr, pxy, :unsaved)
+      # create the proxy => hook inverse
+      pxy.set_hook(self, attr)
+      logger.debug { "Added #{qp} #{mod.qp} annotation proxy attribute #{attr}." }
+      # the annotation module => proxy attribute association
+      @ann_mod_pxy_hash[mod] = attr
+      attr
+    end
+
+    # Makes a new attribute in this hook class for each of the given annotation module's
+    # proxy domain attributes. The hook annotation reference attribute delegates to the
+    # proxy.
+    #
+    # @param [AnnotationModule] mod the subject annotation module
+    # @param [Symbol] proxy_attribute the hook => proxy reference 
+    def create_annotation_attributes(mod)
+      # create annotation attributes which delegate to the proxy
+      mod.proxy.annotation_attributes.each do |attr|
+        create_annotation_attribute(mod, attr)
+      end
+    end
+
+    # Adds the given annotation attribute as a dependent collection attribute with meta-data.
+    #
+    # @param [Symbol] attribute the annotation accessor
+    # @param [Class] type the attribute domain type
+    def add_annotation_attribute(attribute, type)
+      logger.debug { "Adding #{qp} #{type.qp} annotation attribute #{attribute}..." }
+      # Mark the attribute as a collection.
+      add_attribute(attribute, type, :collection)
+      
+      # the camel-case attribute is a potential alias
+      jattr = attribute.to_s.camelize(:lower).to_sym
+      unless attribute == jattr then
+        add_attribute_aliases(jattr => attribute)
+      end
+      
+      # the annotation is a dependent
+      add_dependent_attribute(attribute, :logical)
+    end
+  end
+end

data/lib/catissue/annotation/annotation.rb

@@ -0,0 +1,49 @@
+require 'caruby/resource'
+require 'caruby/domain/id_alias'
+
+module CaTissue
+  # Annotation acceess error class.
+  class AnnotationError < StandardError; end
+  
+  # Annotation class mix-in.
+  module Annotation
+    include CaRuby::Resource, CaRuby::IdAlias
+
+    # Returns the CaTissue::Database which stores this object.
+    def database
+      CaTissue::Database.instance
+    end
+    
+    # Updates the annotation proxy to reflect the hook, if necessary.
+    #
+    # @see Proxy#ensure_identifier_reflects_hook
+    def ensure_proxy_reflects_hook
+      pxy = proxy || return
+      pxy.ensure_identifier_reflects_hook
+    end
+    
+    # @return [Annotatable] the hook object which owns this annotation, or nil if this annotation
+    #   is not directly owned by a hook entity
+    def hook
+      pxy_attr = self.class.proxy_attribute
+      send(pxy_attr) if pxy_attr
+    end
+    
+    # If there is no conventional owner, then try the hook.
+    #
+    # @return the {CaRuby::Resource#owner} or the {#hook}
+    def owner
+      super or hook
+    end
+    
+    # @return [Proxy] the proxy which references this annotation
+    def proxy
+      # the annotation owner hook instance 
+      ownr = hook || return
+      # the hook -> annotation reference attribute
+      attr = self.class.hook_proxy_attribute
+      # the owner proxy for the attribute
+      ownr.annotation_proxy(attr)
+    end
+  end
+end

data/lib/catissue/annotation/annotation_class.rb

@@ -0,0 +1,277 @@
+require 'xmlsimple'
+require 'catissue/annotation/annotation'
+require 'catissue/database/annotation/reference_writer'
+
+module CaTissue
+  module AnnotationClass
+    
+    # @return [Symbol, nil] the annotation => proxy attribute, or nil if this is not a primary annotation
+    attr_reader :proxy_attribute
+    
+    # @return [Integer, nil] the annotation class designator that is used by caTissue to persist primary
+    #   annotation objects, or nil if this is not a primary annotation
+    attr_reader :entity_id
+    
+    # @return [Intger, nil] the container id, or nil if this is not a primary annotation
+    attr_reader :container_id
+
+    # Infers the given annotation class dependent attributes as described in
+    # {#infer_dependents}.
+    #
+    # @param [Class] klass the annotation class
+    def self.extended(klass)
+      super
+      klass.extend_as_annotation
+    end
+   
+    # Adds metadata to this annotation class.
+    def extend_as_annotation
+      efcd = Annotation::EntityFacade.instance
+      # The entity id, or nil if this is not a primary entity.
+      @entity_id = efcd.primary_entity_id(self, false)
+      # A primary entity has a container id.
+      if @entity_id then @container_id = efcd.container_id(@entity_id) end
+      # infer non-dependent attribute inverses
+      detect_inverses
+    end
+    
+    # Creates the proxy attribute if this is a primary_entity annotation class which does not
+    # have a caTissue proxy property.
+    #
+    # @param [Class] proxy the {AnnotationProxy} class
+    def ensure_primary_has_proxy(proxy)
+      if primary? then @proxy_attribute ||= create_proxy_attribute(proxy) end
+    end
+    
+    # Saves the annotations referenced by the given annotation.
+    #
+    # @param [Annotation] annotation the subject annotation
+    def save_dependent_attributes(annotation)
+      dependent_attributes.each { |attr| save_dependent_attribute(annotation, attr) }
+    end
+    
+    # Detects or creates the proxy attribute that references the given proxy class.
+    # if this is a primary_entity annotation class which does not
+    # have a caTissue proxy property.
+    #
+    # @param [Class] proxy the {AnnotationProxy} class
+    def proxy=(proxy)
+      # msut be primary
+      unless primary? then raise AnnotationError.new("Can't set proxy for non-primary annotation class #{qp}") end
+      # make the proxy attribute
+      @proxy_attribute = obtain_proxy_attribute(proxy)
+      # set the hook
+      self.hook = proxy.hook
+      # primary superclass gets a proxy as well
+      if superclass < Annotation and superclass.primary? then superclass.proxy = proxy end
+    end
+    
+    # @param [Class] klass the hook class for this primary annotation
+    def hook=(klass)
+      # only a primary can have a hook
+      unless primary? then
+        raise AnnotationError.new("#{domain_module.qp} annotation #{qp} #{domain_module.proxy.qp} proxy owner accessor attribute not found.")
+      end
+      # redirect the hook writer method to write to the proxy instead
+      convert_hook_to_proxy(klass)
+    end
+    
+    # @return [Symbol, nil] the hook proxy class attribute which references this annotation, or nil if this
+    #   class is not a primary annotation class
+    def hook_proxy_attribute
+      # The hook => primary attribute symbol is the same as the proxy => primary attribute symbol.
+      attribute_metadata(@proxy_attribute).inverse if @proxy_attribute
+    end
+    
+    # @return [Symbol, nil] the primary owner annotation, if it exists
+    def primary_owner_attributes
+      @pr_owr_attrs ||= domain_attributes.compose do |attr_md|
+        attr_md.type < Annotation and attr_md.type.method_defined?(:hook)
+      end
+    end
+    
+    # @return [Boolean] whether this annotation class references a hook proxy
+    def primary?
+      not @entity_id.nil?
+    end
+    
+    # @return [Array] an empty array, since no annotation reference is lazy-loaded by caTissue.
+    def toxic_attributes
+      Array::EMPTY_ARRAY
+    end
+    
+    protected
+    
+    # @return [Symbol => ReferenceWriter] this class's attribute => writer hash
+    def attribute_writer_hash
+      @attr_writer_hash ||= map_writers
+    end
+        
+    # Marks each of this annotation class's non-owner domain attributes as a dependent.
+    def add_dependent_attributes
+      domain_attributes.each_pair do |attr, attr_md|
+        next if attr == @proxy_attribute or attr_md.dependent? or attr_md.owner? or not attr_md.declarer == self
+        logger.debug { "Adding annotation #{qp} #{attr} attribute as a dependent..." }
+        add_dependent_attribute(attr)
+      end
+    end
+        
+    # Recurses the dependency hierarchy to this annotation class's dependents in a
+    # breadth-first manner.
+    #
+    # @param [<CaRuby::AttributeMetadata>] the visited attributes
+    def add_dependent_attribute_closure(path=[])
+      return if path.include?(self)
+      attrs = dependent_attributes(false)
+      return if attrs.empty?
+      logger.debug { "Adding #{qp} dependents..." }
+      # add breadth-first dependencies
+      dependent_attributes(false).each_pair do |attr, attr_md|
+        attr_md.type.add_dependent_attributes
+      end
+      # recurse to dependents
+      dependent_attributes(false).each_metadata do |attr_md|
+        klass = attr_md.type
+        path.push(klass)
+        klass.add_dependent_attribute_closure(path)
+        path.pop
+      end
+      logger.debug { "Added #{qp} dependents #{dependent_attributes(false).qp}." }
+    end
+    
+    private
+    
+    # Infers this annotation class inverses attributes. A domain attribute is
+    # recognized as an inverse according to the {ResourceInverse#detect_inverse_attribute}
+    # criterion. Annotation dependencies are not specified in a configuration and
+    # follow the naming convention described in {ResourceInverse#detect_inverse_attribute}.
+    def detect_inverses
+      domain_attributes.each do |attr|
+        attr_md = attribute_metadata(attr)
+        next if attr_md.inverse
+        inverse = attr_md.type.detect_inverse_attribute(self)
+        if inverse then set_attribute_inverse(attr, inverse) end
+      end
+    end
+    
+    # Saves the annotations referenced by the given annotation attribute.
+    #
+    # @param annotation (see #save_annotation)
+    # @param [Symbol] attribute the attribute to save
+    def save_dependent_attribute(annotation, attribute)
+      annotation.send(attribute).enumerate do |ref|
+        logger.debug { "Saving #{annotation} #{attribute} dependent #{ref.qp}..." }
+        writer(attribute).save(ref)
+      end
+    end
+    
+    # @param [Symbol] attribute the annotation attribute
+    # @return [AnnotationWriter] the attribute writer for instances of this class
+    def writer(attribute)
+      attribute_writer_hash[attribute]
+    end
+    
+    # @return [{Symbol => Annotation::ReferenceWriter}] the annotation attribute => writer hash
+    def map_writers
+      hash = {}
+      cascaded_attributes.each_pair do |attr, attr_md|
+        # skip attributes defined in a superclass
+        next unless attr_md.declarer == self
+        hash[attr] = Annotation::ReferenceWriter.new(@entity_id, attr_md)
+      end
+      # If the superclass is also an annotation, then form the union of its writers with the local writers.
+      superclass < Annotation && superclass.primary? ? hash + superclass.attribute_writer_hash : hash
+    end
+    
+    def obtain_proxy_attribute(proxy)
+      # parent proxy is reserved for RadiationTherapy use case described in ParticipantTest.
+      # TODO - either support this use case of delete the parent proxy call
+      detect_proxy_attribute(proxy) or create_proxy_attribute(proxy) or parent_proxy_attribute
+    end
+    
+    def parent_proxy_attribute
+      superclass.proxy_attribute if superclass < Annotation
+    end
+    
+    # @return [Symbol] the annotation -> proxy attribute
+    def detect_proxy_attribute(proxy)
+      attr_md = detect_proxy_attribute_metadata(proxy)
+      if attr_md then
+        attr_md.type = proxy.hook
+        logger.debug { "Reset #{qp} #{attr_md} attribute type from the proxy class #{proxy} to the hook class #{proxy.hook}" }
+      end
+      attr_md
+    end
+    
+    # @return [Symbol] the annotation -> proxy attribute
+    def detect_proxy_attribute_metadata(proxy)
+      domain_attributes.each_metadata { |attr_md| return attr_md if attr_md.type == proxy }
+      nil
+    end
+    
+    # @param [Class] proxy the domain module {Annotation::ProxyClass}
+    # @return [Symbol] the new annotation -> proxy attribute
+    def create_proxy_attribute(proxy)
+      # the proxy attribute symbol
+      attr = proxy.name.demodulize.underscore.to_sym
+      logger.debug { "Creating primary annotation #{qp} proxy attribute #{attr}..." }
+      # make the attribute
+      attr_accessor(attr)
+      # Add the attribute. Setting the saved flag ensures that the save template passed to
+      # the annotation service includes a reference to the hook object. This in turn allows
+      # the annotation service to call the integration service to associate the annotation
+      # to the hook object.
+      add_attribute(attr, proxy.hook, :saved)
+      # make the inverse proxy -> annotation dependent attribute
+      proxy.create_annotation_attribute(self, attr)
+      attr
+    end
+    
+    # Wraps the proxy owner attribute with a proxy <-> hook converter as follows:
+    # * the reader method is redefined to convert a proxy to its hook
+    # * the writer method is redefined to convert a hook argument to its proxy
+    #
+    # @param [Class] klass the hook class
+    def convert_hook_to_proxy(klass)
+      # the proxy reference attribute
+      attr_md = attribute_metadata(@proxy_attribute)
+      # wrap the proxy reader with a proxy => hook converter
+      convert_proxy_reader_result_to_hook(attr_md.reader)
+      # the proxy => hook attribute metadata
+      pxy_hook_attr_md = domain_module.proxy.attribute_metadata(:hook)
+      # the hook => proxy attribute
+      hook_pxy_attr = pxy_hook_attr_md.inverse
+      # wrap the proxy writer with a hook -> proxy converter
+      convert_proxy_writer_hook_argument_to_proxy(attr_md.writer, klass, hook_pxy_attr)
+    end
+    
+    # Wraps the proxy reader method to convert a proxy to its hook.
+    #
+    # @param [Symbol] reader the proxy reader method
+    def convert_proxy_reader_result_to_hook(reader)
+      redefine_method(reader) do |old_mth|
+        lambda do
+          pxy = send(old_mth)
+          pxy.hook if pxy
+        end
+      end
+      logger.debug { "Redefined the #{qp} #{reader} reader method to convert a proxy parameter to its hook object." }
+    end
+    
+    # Wraps the proxy writer method to convert a hook argument to its proxy.
+    #
+    # @param [Symbol] writer the proxy writer method
+    # @param klass (see #convert_hook_to_proxy)
+    # @param [Symbol] inverse the hook => proxy attribute
+    def convert_proxy_writer_hook_argument_to_proxy(writer, klass, inverse)
+      redefine_method(writer) do |old_mth|
+        lambda do |value|
+          # Convert the parameter from a hook to a proxy, if necessary.
+          pxy = klass === value ? value.send(inverse) : value
+          send(old_mth, pxy)
+        end
+      end
+      logger.debug { "Redefined the #{klass.qp} #{inverse} proxy writer #{writer} to convert a hook #{klass.qp} parameter to the hook proxy." }
+    end
+  end
+end