caruby-core 1.5.5 → 2.1.1

data/lib/caruby/domain/metadata.rb

@@ -1,142 +0,0 @@
-require 'caruby/util/collection'
-require 'caruby/import/java'
-require 'caruby/domain/java_attribute'
-require 'caruby/domain/introspection'
-require 'caruby/domain/inverse'
-require 'caruby/domain/dependency'
-require 'caruby/domain/attributes'
-require 'caruby/json/deserializer'
-
-module CaRuby
-  module Domain
-    # Exception raised if a meta-data setting is missing or invalid.
-    class MetadataError < RuntimeError; end
-    
-    # Adds introspected metadata to a Class.
-    module Metadata
-      include Introspection, Inverse, Dependency, Attributes, JSON::Deserializer
-      
-      # @return [Module] the {Domain} module context
-      attr_accessor :domain_module
-      
-      def self.extended(klass)
-        super
-        klass.class_eval do
-          # Add this class's metadata.
-          introspect
-          # Add the {attribute=>value} argument constructor.
-          class << self
-            def new(opts=nil)
-              obj = super()
-              obj.merge_attributes(opts) if opts
-              obj
-            end
-          end
-        end
-      end
-  
-      # @return the domain type for attribute, or nil if attribute is not a domain attribute
-      def domain_type(attribute)
-        attr_md = attribute_metadata(attribute)
-        attr_md.type if attr_md.domain?
-      end
-  
-      # Returns an empty value for the given attribute.
-      # * If this class is not abstract, then the empty value is the initialized value.
-      # * Otherwise, if the attribute is a Java primitive number then zero.
-      # * Otherwise, if the attribute is a Java primitive boolean then +false+.
-      # * Otherwise, the empty value is nil.
-      #
-      # @param [Symbol] attribute the target attribute
-      # @return [Numeric, Boolean, Enumerable, nil] the empty attribute value
-      def empty_value(attribute)
-        if abstract? then
-          attr_md = attribute_metadata(attribute)
-          # the Java property type
-          jtype = attr_md.property_descriptor.property_type if JavaAttribute === attr_md
-          # A primitive is either a boolean or a number (String is not primitive).
-          if jtype and jtype.primitive? then
-            type.name == 'boolean' ? false : 0
-          end
-        else
-          # Since this class is not abstract, create a prototype instance on demand and make
-          # a copy of the initialized collection value from that instance.
-          @prototype ||= new
-          value = @prototype.send(attribute) || return
-          value.class.new
-        end
-      end
-      
-     # Prints this classifier's content to the log.
-      def pretty_print(q)
-        # the Java property descriptors
-        property_descriptors = java_attributes.wrap { |attr| attribute_metadata(attr).property_descriptor }
-        # build a map of relevant display label => attributes
-        prop_printer = property_descriptors.wrap { |pd| PROP_DESC_PRINTER.wrap(pd) }
-        prop_syms = property_descriptors.map { |pd| pd.name.to_sym }.to_set
-        aliases = @alias_std_attr_map.keys - attributes.to_a - prop_syms
-        alias_attr_hash = aliases.to_compact_hash { |aliaz| @alias_std_attr_map[aliaz] }
-        dependents_printer = dependent_attributes.wrap { |attr| DEPENDENT_ATTR_PRINTER.wrap(attribute_metadata(attr)) }
-        owner_printer = owners.wrap { |type| TYPE_PRINTER.wrap(type) }
-        inverses = @attributes.to_compact_hash do |attr|
-           attr_md = attribute_metadata(attr)
-           "#{attr_md.type.qp}.#{attr_md.inverse}" if attr_md.inverse
-        end
-        domain_attr_printer = domain_attributes.to_compact_hash { |attr| domain_type(attr).qp }
-        map = {
-          "Java properties" => prop_printer,
-          "standard attributes" => attributes,
-          "aliases to standard attributes" => alias_attr_hash,
-          "secondary key" => secondary_key_attributes,
-          "mandatory attributes" => mandatory_attributes,
-          "domain attributes" => domain_attr_printer,
-          "creatable domain attributes" => creatable_domain_attributes,
-          "updatable domain attributes" => updatable_domain_attributes,
-          "fetched domain attributes" => fetched_domain_attributes,
-          "cascaded domain attributes" => cascaded_attributes,
-          "owners" => owner_printer,
-          "owner attributes" => owner_attributes,
-          "inverse attributes" => inverses,
-          "dependent attributes" => dependents_printer,
-          "default values" => defaults
-        }.delete_if { |key, value| value.nil_or_empty? }
-        
-        # one indented line per entry, all but the last line ending in a comma
-        content = map.map { |label, value| "  #{label}=>#{format_print_value(value)}" }.join(",\n")
-        # print the content to the log
-        q.text("#{qp} structure:\n#{content}")
-      end
-  
-      protected
-  
-      def self.extend_class(klass, mod)
-        klass.extend(self)
-        klass.add_metadata(mod)
-      end
-  
-      private
-      
-      # A proc to print the unqualified class name.
-      TYPE_PRINTER = PrintWrapper.new { |type| type.qp }
-  
-      DEPENDENT_ATTR_PRINTER = PrintWrapper.new do |attr_md|
-        flags = []
-        flags << :logical if attr_md.logical?
-        flags << :autogenerated if attr_md.autogenerated?
-        flags << :disjoint if attr_md.disjoint?
-        flags.empty? ? "#{attr_md}" : "#{attr_md}(#{flags.join(',')})"
-      end
-  
-      # A proc to print the property descriptor name.
-      PROP_DESC_PRINTER = PrintWrapper.new { |pd| pd.name }
-
-      def format_print_value(value)
-        case value
-          when String then value
-          when Class then value.qp
-          else value.pp_s(:single_line)
-        end
-      end
-    end
-  end
-end

data/lib/caruby/domain/mixin.rb

@@ -1,35 +0,0 @@
-require 'caruby/domain/metadata'
-
-module CaRuby
-  module Domain
-    # Mixin extends a module to add meta-data to included classes.
-    module Mixin
-      # Adds {Metadata} to an included class.
-      #
-      # @example
-      #   module CaRuby
-      #     module Resource
-      #       def self.included(mod)
-      #         mod.extend(Domain::Mixin)
-      #       end
-      #     end
-      #   end
-      #   module ClinicalTrials
-      #     module Resource
-      #       include CaRuby::Resource
-      #     end
-      #     class Subject
-      #       include Resource #=> introspects the Subject meta-data
-      #     end
-      #   end
-      #
-      # @param [Module] class_or_module the included module, usually a class
-      def included(class_or_module)
-        super
-        if Class === class_or_module then
-          Metadata.ensure_metadata_introspected(class_or_module)
-        end
-      end
-    end
-  end
-end

data/lib/caruby/domain/properties.rb

@@ -1,95 +0,0 @@
-require 'caruby/util/properties'
-require 'caruby/util/collection'
-require 'caruby/util/options'
-
-module CaRuby
-  module Domain
-    # CaRuby::Domain::Properties specializes the generic CaRuby::Properties class for domain properties.
-    class Properties < CaRuby::Properties
-
-      # The application login userid environment variable.
-      USER_ENV_VAR_SUFFIX = 'USER'
-
-      # The application login password environment variable.
-      PASSWORD_ENV_VAR_SUFFIX = 'PASSWORD'
-
-      # The application service user property name.
-      USER_PROP = :user
-
-      # The application service password property name.
-      PASSWORD_PROP = :password
-
-      # The application Java jar location.
-      PATH_PROP = :path
-
-      attr_reader :application
-
-      # Creates a new Properties.
-      #
-      # Supported options include the CaRuby::Properties options as well as the following:
-      # * :application - the application name
-      #
-      # The application name is used as a prefix for application-specific upper-case environment variables
-      # and lower-case file names, e.g. +CATISSUE_USER+ for the +caTissue+ application login username
-      # environment variable. The default application name is +caBIG+.
-      #
-      # The user properties file is always loaded if it exists. This file's name is a period followed by the
-      # lower-case application name, located in the home directory, e.g. +~/.catissue.yaml+ for application
-      # +caTissue+.
-      def initialize(file=nil, options=nil)
-        @application = Options.get(:application, options, "caBIG")
-        super(file, options)
-      end
-
-      # Loads the properties in the following low-to-high precedence order:
-      # * the home file +.+_application_+.yaml+, where _application_ is the application name
-      # * the given property file
-      # * the environment variables
-      def load_properties(file)
-        # canonicalize the file path
-        file = File.expand_path(file)
-        # load the home properties file, if it exists
-        user_file = File.expand_path("~/.#{@application.downcase}.yaml")
-        super(user_file) if user_file != file and File.exists?(user_file)
-        # load the given file
-        super(file)
-        # the environment variables take precedence
-        load_environment_properties
-        # validate the required properties
-        validate_properties
-      end
-
-      private
-
-      def load_environment_properties
-        user = ENV[user_env_var]
-        if user then
-          self[USER_PROP] = user
-          logger.info("#{@application} login user obtained from environment property #{user_env_var} value '#{user}'.")
-        end
-        password = ENV[password_env_var]
-        if password then
-          self[PASSWORD_PROP] = password
-          logger.info("#{@application} login password obtained from environment property #{password_env_var} value.")
-        end
-        path = ENV[path_env_var]
-        if path then
-          self[PATH_PROP] = path
-          logger.info("#{@application} Java library path obtained from environment property #{path_env_var} value '#{path}'.")
-        end
-      end
-
-      def user_env_var
-        "#{@application}_#{USER_PROP}".upcase
-      end
-
-      def password_env_var
-        "#{@application}_#{PASSWORD_PROP}".upcase
-      end
-
-      def path_env_var
-        "#{@application}_#{PATH_PROP}".upcase
-      end
-    end
-  end
-end

data/lib/caruby/domain/reference_visitor.rb

@@ -1,428 +0,0 @@
-require 'enumerator'
-require 'generator'
-require 'caruby/util/options'
-require 'caruby/util/collection'
-require 'caruby/util/validation'
-require 'caruby/util/visitor'
-require 'caruby/util/math'
-
-module CaRuby
-  # A ReferenceVisitor traverses reference attributes.
-  class ReferenceVisitor < Visitor
-    private
-
-    # Flag to print a detailed debugging visit message
-    DETAIL_DEBUG = false
-
-    public
-
-    attr_reader :ref_attr_hash
-
-    # Creates a new ReferenceVisitor on domain reference attributes.
-    #
-    # If a selector block is given to this initializer, then the reference attributes to visit
-    # are determined by calling the block. Otherwise, the {Domain::Attributes#saved_domain_attributes}
-    # are visited.
-    #
-    # @param options (see Visitor#initialize)
-    # @yield [ref] selects which attributes to visit next
-    # @yieldparam [Resource] ref the currently visited domain object
-    def initialize(options=nil, &selector)
-      raise ArgumentError.new("Reference visitor missing domain reference selector") unless block_given?
-      @selector = selector
-      # delegate to Visitor with the visit selector block
-      super { |parent| references_to_visit(parent) }
-      # the visited reference => parent attribute hash
-      @ref_attr_hash = {}
-      # TODO - reconcile @excludes here with Visitor exclude.
-      # refactor usage and interaction with prune_cycles.
-      # eliminate if possible.
-      @excludes = []
-    end
-
-    # @return [Symbol, nil] the parent attribute which was visited to get to the current visited domain object
-    def attribute
-      @ref_attr_hash[current]
-    end
-
-    # Excludes obj from the next visit.
-    # Exclusions are cleared after visit is completed.
-    def exclude(obj)
-      @excludes << obj
-    end
-
-    # Performs Visitor::visit and clears exclusions.
-    def visit(obj)
-      if DETAIL_DEBUG then
-        logger.debug { "Visiting #{obj.qp} from navigation path #{lineage.qp}..." }
-      end
-      
-      # TODO - current, attribute and parent are nil when a value is expected.
-      # Uncomment below, build test cases, analyze and fix.
-      #
-      # puts "Visit #{obj.qp} current: #{self.current.qp} parent: #{self.parent.qp} attribute: #{self.attribute}"
-      # puts "  lineage:#{lineage.qp}n  attributes:#{@ref_attr_hash.qp}"
-      # puts "  reference => attribute hash: #{@ref_attr_hash.qp}"
-
-      result = super
-      @excludes.clear
-      result
-    end
-
-    # Adds a default matcher block if necessary and delegates to {Visitor#sync}. The default matcher block
-    # calls {Resource#match_in} to match the candidate domain objects to visit.
-    #
-    # @yield [ref, others] matches ref in others (optional)
-    # @yieldparam [Resource] ref the domain object to match
-    # @yieldparam [<Resource>] the candidates for matching ref
-    def sync(&matcher)
-      MatchVisitor.new(:matcher => matcher, &@selector)
-    end
-
-    protected
-
-    def clear
-      super
-      @ref_attr_hash.clear
-    end
-
-    private
-    
-    # @param [Resource] parent the referencing domain object
-    # @return [<Resource>] the domain attributes to visit next
-    def attributes_to_visit(parent)
-       @selector.call(parent)
-    end
-
-    # @param [Resource] parent the referencing domain object
-    # @return [<Resource>] the referenced domain objects to visit next for the given parent
-    def references_to_visit(parent)
-      attrs = attributes_to_visit(parent)
-      if attrs.nil? then return Array::EMPTY_ARRAY end
-      refs = []
-      attrs.each do | attr|
-        # the reference(s) to visit
-        value = parent.send(attr)
-        # associate each reference to visit with the current visited attribute
-        value.enumerate do |ref|
-          @ref_attr_hash[ref] = attr
-          refs << ref
-        end
-      end
-      if DETAIL_DEBUG then
-        logger.debug { "Visiting #{parent.qp} references: #{refs.qp}" }
-        logger.debug { " lineage: #{lineage.qp}" }
-        logger.debug { " attributes: #{attrs.qp}..." }
-      end
-      
-      refs
-    end
-  end
-  
-  # A MatchVisitor visits two domain objects' visitable attributes transitive closure in lock-step.
-  class MatchVisitor < ReferenceVisitor
-
-    attr_reader :matches
-
-    # Creates a new visitor which matches source and target domain object references.
-    # The domain attributes to visit are determined by calling the selector block given to
-    # this initializer. The selector arguments consist of the match source and target.
-    #
-    # @param (see ReferenceVisitor#initialize)
-    # @option opts [Proc] :mergeable the block which determines which attributes are merged
-    # @option opts [Proc] :matchable the block which determines which attributes to match
-    #   (default is the visit selector)
-    # @option opts [Proc] :matcher the block which matches sources to targets
-    # @option opts [Proc] :copier the block which copies an unmatched source
-    # @yield (see ReferenceVisitor#initialize)
-    # @yieldparam [Resource] source the matched source object
-    def initialize(opts=nil)
-      raise ArgumentError.new("Reference visitor missing domain reference selector") unless block_given?
-      opts = Options.to_hash(opts)
-      @matcher = opts.delete(:matcher) || Resource.method(:match_all)
-      @matchable = opts.delete(:matchable)
-      @copier = opts.delete(:copier)
-      # the source => target matches
-      @matches = {}
-      # the class => {id => target} hash
-      @id_mtchs = LazyHash.new { Hash.new }
-      super { |src| yield(src) if @matches[src] }
-    end
-
-    # Visits the source and target.
-    #
-    # If a block is given to this method, then this method returns the evaluation of the block on the visited
-    # source reference and its matching copy, if any. The default return value is the target which matches
-    # source.
-    #
-    # caCORE alert = caCORE does not enforce reference identity integrity, i.e. a search on object _a_
-    # with database record references _a_ => _b_ => _a_, the search result might be _a_ => _b_ => _a'_,
-    # where _a.identifier_ == _a'.identifier_. This visit method remedies this caCORE defect by matching
-    # source references on a previously matched identifier where possible.
-    #
-    # @param [Resource] source the match visit source
-    # @param [Resource] target the match visit target
-    # @yield [target, source] the optional block to call on the matched source and target
-    # @yieldparam [Resource] source the visited source domain object
-    # @yieldparam [Resource] target the domain object which matches the visited source
-    def visit(source, target, &block)
-      # clear the match hashes
-      @matches.clear
-      @id_mtchs.clear
-      # seed the matches with the top-level source => target
-      add_match(source, target)
-      # visit the source reference. the visit block merges each source reference into
-      # the matching target reference.
-      super(source) { |src| visit_matched(src, &block) }
-    end
-
-    private
-    
-    # Visits the given source domain object.
-    #
-    # @param [Resource] source the match visit source
-    # @yield [target, source] the optional block to call on the matched source and target
-    # @yieldparam [Resource] source the visited source domain object
-    # @yieldparam [Resource] target the domain object which matches the visited source
-    def visit_matched(source)
-      tgt = match_for_visited(source)
-      # match the matchable references, if any
-      if @matchable then
-        attrs = @matchable.call(source) - attributes_to_visit(source)
-        attrs.each { |attr| match_reference(source, tgt, attr) }
-      end
-      block_given? ? yield(source, tgt) : tgt
-    end
-
-    # @param source (see #match_visited)
-    # @return [<Resource>] the domain objects referenced by the source to visit next
-    def references_to_visit(source)
-      # the source match
-      target = match_for_visited(source)
-      # the attributes to visit
-      attrs = attributes_to_visit(source)
-      # the matched source references
-      match_references(source, target, attrs).keys
-    end
-    
-    # @param source (see #match_visited)
-    # @return [<Resource>] the source match
-    # @raise [ValidationError] if there is no match
-    def match_for_visited(source)
-      target = @matches[source]
-      if target.nil? then raise ValidationError.new("Match visitor target not found for #{source}") end
-      target
-    end
-
-    # @param [Resource] source (see #match_visited)
-    # @param [Resource] target the source match
-    # @param [<Symbol>] attributes the attributes to match on
-    # @return [{Resource => Resource}] the referenced attribute matches
-    def match_references(source, target, attributes)
-      # collect the references to visit
-      matches = {}
-      attributes.each do |attr|
-        matches.merge!(match_reference(source, target, attr))
-      end
-      matches
-    end
-    
-    # Matches the given source and target attribute references.
-    # The match is performed by this visitor's matcher Proc.
-    #
-    # @param source (see #visit)
-    # @param target (see #visit)
-    # @return [{Resource => Resource}] the referenced source => target matches
-    def match_reference(source, target, attribute)
-      srcs = source.send(attribute).to_enum
-      tgts = target.send(attribute).to_enum
-      
-      # the match targets
-      mtchd_tgts = Set.new
-      # capture the matched targets and the the unmatched sources
-      unmtchd_srcs = srcs.reject do |src|
-        # the prior match, if any
-        tgt = match_for(src)
-        mtchd_tgts << tgt if tgt
-      end
-      
-      # the unmatched targets
-      unmtchd_tgts = tgts.difference(mtchd_tgts)
-      # match the residual targets and sources
-      rsd_mtchs = @matcher.call(unmtchd_srcs, unmtchd_tgts)
-      # add residual matches
-      rsd_mtchs.each { |src, tgt| add_match(src, tgt) }
-      
-      # The source => target match hash.
-      # If there is a copier, then copy each unmatched source.
-      matches = srcs.to_compact_hash { |src| match_for(src) or copy_unmatched(src) }
-      logger.debug { "Match visitor matched #{matches.qp}." } unless matches.empty?
-      
-      matches
-    end
-
-    # @return the target matching the given source
-    def match_for(source)
-      @matches[source] or identifier_match(source)
-    end
-    
-    def add_match(source, target)
-      @matches[source] = target
-      @id_mtchs[source.class][source.identifier] = target if source.identifier
-      target
-    end
-
-    # @return the target matching the given source on the identifier, if any
-    def identifier_match(source)
-      tgt = @id_mtchs[source.class][source.identifier] if source.identifier
-      @matches[source] = tgt if tgt
-    end
-
-    # @return [Resource, nil] a copy of the given source if this ReferenceVisitor has a copier,
-    #   nil otherwise
-    def copy_unmatched(source)
-      return unless @copier
-      copy = @copier.call(source)
-      add_match(source, copy)
-    end
-  end
-
-  # A MergeVisitor merges a domain object's visitable attributes transitive closure into a target.
-  class MergeVisitor < MatchVisitor
-    # Creates a new MergeVisitor on domain attributes.
-    # The domain attributes to visit are determined by calling the selector block given to
-    # this initializer as described in {ReferenceVisitor#initialize}.
-    #
-    # @param (see MatchVisitor#initialize)
-    # @option opts [Proc] :mergeable the block which determines which attributes are merged
-    # @option opts [Proc] :matcher the block which matches sources to targets
-    # @option opts [Proc] :copier the block which copies an unmatched source
-    # @yield (see MatchVisitor#initialize)
-    # @yieldparam (see MatchVisitor#initialize)
-    def initialize(opts=nil, &selector)
-      opts = Options.to_hash(opts)
-      # Merge is depth-first, since the source references must be matched, and created if necessary,
-      # before they can be merged into the target.
-      opts[:depth_first] = true
-      @mergeable = opts.delete(:mergeable) || selector
-      # each mergeable attribute is matchable
-      unless @mergeable == selector then
-        opts[:matchable] = @mergeable
-      end
-      super
-    end
-
-    # Visits the source and target and returns a recursive copy of obj and each of its visitable references.
-    #
-    # If a block is given to this method, then this method returns the evaluation of the block on the visited
-    # source reference and its matching copy, if any. The default return value is the target which matches
-    # source.
-    #
-    # caCORE alert = caCORE does not enforce reference identity integrity, i.e. a search on object _a_
-    # with database record references _a_ => _b_ => _a_, the search result might be _a_ => _b_ => _a'_,
-    # where _a.identifier_ == _a'.identifier_. This visit method remedies the caCORE defect by matching source
-    # references on a previously matched identifier where possible.
-    #
-    # @param [Resource] source the domain object to merge from
-    # @param [Resource] target the domain object to merge into 
-    # @yield [target, source] the optional block to call on the visited source domain object and its matching target
-    # @yieldparam [Resource] target the domain object which matches the visited source
-    # @yieldparam [Resource] source the visited source domain object
-    def visit(source, target)
-      # visit the source reference. the visit block merges each source reference into
-      # the matching target reference.
-      super(source, target) do |src, tgt|
-         merge(src, tgt)
-         block_given? ? yield(src, tgt) : tgt
-      end
-    end
-
-    private
-
-    # Merges the given source object into the target object.
-    #
-    # @param [Resource] source the domain object to merge from
-    # @param [Resource] target the domain object to merge into
-    # @return [Resource] the merged target
-    def merge(source, target)
-      # trivial case
-      return target if source.equal?(target)
-      # the domain attributes to merge
-      attrs = @mergeable.call(source)
-      logger.debug { format_merge_log_message(source, target, attrs) }
-      # merge the non-domain attributes
-      target.merge_attributes(source)
-      # merge the source domain attributes into the target
-      target.merge(source, attrs, @matches)
-    end
-    
-    # @param source (see #merge)
-    # @param target (see #merge)
-    # @param attributes (see Mergeable#merge)
-    # @return [String] the log message
-    def format_merge_log_message(source, target, attributes)
-      attr_clause = " including domain attributes #{attributes.to_series}" unless attributes.empty?
-      "Merging #{source.qp} into #{target.qp}#{attr_clause}..."
-    end
-  end
-
-  # A CopyVisitor copies a domain object's visitable attributes transitive closure.
-  class CopyVisitor < MergeVisitor
-    # Creates a new CopyVisitor with the options described in {MergeVisitor#initialize}.
-    # The default :copier option is {Resource#copy}.
-    #
-    # @param (see MergeVisitor#initialize)
-    # @option opts [Proc] :mergeable the mergeable domain attribute selector
-    # @option opts [Proc] :matcher the match block
-    # @option opts [Proc] :copier the unmatched source copy block
-    # @yield (see MergeVisitor#initialize)
-    # @yieldparam (see MergeVisitor#initialize)
-    def initialize(opts=nil)
-      opts = Options.to_hash(opts)
-      opts[:copier] ||= Proc.new { |src| src.copy }
-      # no match forces a copy
-      opts[:matcher] = Proc.new { Hash::EMPTY_HASH }
-      super
-    end
-
-    # Visits obj and returns a recursive copy of obj and each of its visitable references.
-    #
-    # If a block is given to this method, then the block is called with the visited
-    # source reference and its matching copy target.
-    #
-    # @param (see MergeVisitor#visit)
-    # @yield (see MergeVisitor#visit)
-    # @yieldparam (see MergeVisitor#visit)
-    def visit(source)
-      target = @copier.call(source)
-      super(source, target)
-    end
-  end
-
-  # A ReferencePathVisitorFactory creates a ReferenceVisitor that traverses an attributes path.
-  #
-  # For example, given the attributes:
-  #   treatment: BioMaterial -> Treatment
-  #   measurement: Treatment -> BioMaterial
-  # then a path visitor given by:
-  #   ReferencePathVisitorFactory.create(BioMaterial, [:treatment, :measurement])
-  # visits all biomaterial, treatments and measurements derived directly or indirectly from a starting BioMaterial instance.
-  class ReferencePathVisitorFactory
-    # @return a new ReferenceVisitor that visits the given path attributes starting at an instance of type
-    def self.create(type, attributes, options=nil)
-      # augment the attributes path as a [class, attribute] path
-      path = []
-      attributes.each do |attr|
-        path << [type, attr]
-        type = type.domain_type(attr)
-      end
-
-      # make the visitor
-      visitor = ReferenceVisitor.new(options) do |ref|
-        # collect the path reference attributes whose source match the ref type up to the next position in the path
-        max = visitor.lineage.size.min(path.size)
-        (0...max).map { |i| path[i].last if ref.class == path[i].first }.compact
-      end
-    end
-  end
-end