caruby-core 1.5.5 → 2.1.1

data/lib/caruby/domain/uniquify.rb

@@ -1,50 +0,0 @@
-require 'singleton'
-require 'caruby/util/uniquifier'
-require 'caruby/util/collection'
-
-module CaRuby
-  module Resource
-    # The Unique mix-in makes values unique within the scope of a Resource class.
-    module Unique
-      # Makes the given String value unique in the context of this object's class.
-      # @return nil if value is nil
-      # Raises TypeError if value is neither nil nor a String.
-      def uniquify_value(value)
-        unless String === value or value.nil? then
-          raise TypeError.new("Cannot uniquify #{qp} non-String value #{value}")
-        end
-        ResourceUniquifier.instance.uniquify(self, value)
-      end
-      
-      # Makes the secondary key unique by replacing each String key attribute value
-      # with a unique value.
-      def uniquify
-        self.class.secondary_key_attributes.each do |attr|
-          oldval = send(attr)
-          next unless String === oldval
-          newval = uniquify_value(oldval)
-          set_attribute(attr, newval)
-          logger.debug { "Reset #{qp} #{attr} from #{oldval} to unique value #{newval}." }
-        end
-      end
-    end
-  end
-  
-  # The ResourceUniquifier singleton makes Resource instance attribute values unique.
-  class ResourceUniquifier
-    include Singleton
-
-    def initialize
-      @cache = LazyHash.new { Hash.new }
-    end
-
-    # Makes the obj attribute value unique, or returns nil if value is nil.
-    def uniquify(obj, value)
-      @cache[obj.class][value] ||= value.uniquify if value
-    end
-
-    def clear
-      @cache.clear
-    end
-  end
-end

data/lib/caruby/import/java.rb

@@ -1,387 +0,0 @@
-#
-# Include file to set up the classpath and logger.
-#
-
-# The jRuby Java bridge
-require 'java'
-require 'ftools'
-require 'date'
-
-require 'caruby/util/class'
-require 'caruby/util/log'
-require 'caruby/util/inflector'
-require 'caruby/util/collection'
-
-module Java
-  private
-  
-  # The Windows semi-colon path separator.
-  WINDOWS_PATH_SEP = ';'
-  
-  # The Unix colon path separator.
-  UNIX_PATH_SEP = ':'
-  
-  public
-  
-  # Adds the directories in the given path and all Java jar files contained in the directories
-  # to the execution classpath.
-  #
-  # @param [String] path the colon or semi-colon separated directories
-  def self.add_path(path)
-    # the path separator
-    sep = path[WINDOWS_PATH_SEP] ? WINDOWS_PATH_SEP : UNIX_PATH_SEP
-    # the path directories
-    dirs = path.split(sep).map { |dir| File.expand_path(dir) }
-    # Add all jars found anywhere within the directories to the the classpath.
-    add_jars(*dirs)
-    # Add the directories to the the classpath.
-    dirs.each { |dir| add_to_classpath(dir) }
-  end  
-  
-  # Adds the jars in the directories to the execution class path.
-  #
-  # @param [<String>] directories the directories containing jars to add
-  def self.add_jars(*directories)
-    directories.each do |dir|
-      Dir[File.join(dir , "**", "*.jar")].each { |jar| add_to_classpath(jar) }
-    end
-  end
-  
-  # Adds the given jar file or directory to the classpath.
-  #
-  # @param [String] file the jar file or directory to add
-  def self.add_to_classpath(file)
-    unless File.exist?(file) then
-      logger.warn("File to place on Java classpath does not exist: #{file}")
-      return
-    end
-    if file =~ /.jar$/ then
-      # require is preferred to classpath append for a jar file
-      require file
-    else
-      # A directory must end in a slash since JRuby uses an URLClassLoader.
-      if File.directory?(file) and not file =~ /\/$/ then file = file + '/' end
-      $CLASSPATH << file
-    end
-  end
-
-  module JavaUtil
-    # Aliases Java Collection methods with the standard Ruby Set counterpart, e.g. +delete+ for +remove+.
-    module Collection
-      def to_a
-        inject(Array.new) { |array, item| array << item }
-      end
-
-      # Removes the given item from this collection.
-      def delete(item)
-        # can't alias delete to remove, since a Java interface doesn't implement any methods
-        remove(item)
-      end
-
-      # Removes the items from this collection for which the block given to this method returns a non-nil, non-false value.
-      def delete_if
-        removeAll(select { |item| yield item })
-        self
-      end
-    end
-
-    # Aliases Java List methods with the standard Ruby Array counterpart, e.g. +merge+ for +addAll+.
-    module List
-      # Returns whether this List has the same content as the other Java List or Ruby Array.
-      def ==(other)
-        Array === other ? to_a == other : equals(other)
-      end
-
-      # Removes the given item from this collection.
-      def delete(item)
-        remove(item)
-      end
-    end
-
-    module Map
-      # Returns whether this Set has the same content as the other Java Map or Ruby Hash.
-      def ==(other)
-        ::Hash === other ? (size == other.size and other.all? { |key, value| get(key) == value }) : equals(other)
-      end
-
-      # Merges the other Java Map or Ruby Hash into this Map. Returns this modified Map.
-      #
-      # If a block is given to this method, then the block determines the mapped value
-      # as specified in the Ruby Hash merge method documentation.
-      def merge(other)
-        other.each do |key, value|
-          value = yield(key, get(key), value) if block_given? and containsKey(key)
-          put(key, value)
-        end
-        self
-      end
-
-      alias :merge! :merge
-    end
-
-    module Set
-      # Returns whether this Set has the same content as the other Java Set or Ruby Set.
-      def ==(other)
-        ::Set === other ? (size == other.size and all? { |item| other.include?(item) }) : equals(other)
-      end
-
-      # Merges the other Enumerable into this Set. Returns this modified Set.
-      #
-      # This method conforms to the Ruby Set merge contract rather than the Ruby List and Hash
-      # merge contract. Ruby Set merge modifies the Set in-place, whereas Ruby List and Hash
-      # merge return a new collection.
-      def merge(other)
-        return self if other.nil?
-        raise ArgumentError.new("Merge argument must be enumerable: #{other}") unless Enumerable === other
-        other.each { |item| self << item }
-        self
-      end
-
-      alias :merge! :merge
-    end
-
-    class HashSet
-      alias :base__clear :clear
-      private :base__clear
-      def clear
-        base__clear
-        self
-      end
-    end
-
-    class TreeSet
-      alias :base__first :first
-      private :base__first
-      # Fixes the jRuby {TreeSet#first} to return nil on an empty set rather than raise a Java exception.
-      def first
-        empty? ? nil : base__first
-      end
-    end
-
-    class ArrayList
-      alias :base__clear :clear
-      private :base__clear
-      def clear
-        base__clear
-        self
-      end
-    end
-
-    class Date
-      # The millisecond-to-day conversion factor.
-      MILLIS_PER_DAY = (60 * 60 * 1000) * 24
-
-      # Converts this Java Date to a Ruby DateTime.
-      #
-      # @quirk caTissue Bug #165: API CPR create date validation is time zone dependent.
-      #   Since Java Date accounts for DST and Ruby DateTime doesn't, this method makes the
-      #   DST adjustment by subtracting a compensatory one-hour DST offset from the
-      #   Java Date time zone offset and using that to set the DateTime offset.
-      #   This ensures that Date conversion is idempotent, i.e.
-      #     date.to_ruby_date().to_java_date == date
-      #
-      #   However, there can be adverse consequences for an application that assumes that the
-      #   client time zone is the same as the server time zone, as described in caTissue
-      #   Bug #165.
-      #
-      # @return [DateTime] the Ruby date
-      def to_ruby_date
-        calendar = java.util.Calendar.instance
-        calendar.setTime(self)
-        secs = calendar.timeInMillis.to_f / 1000
-        # millis since epoch
-        time = Time.at(secs)
-        # convert UTC timezone millisecond offset to Rational fraction of a day
-        offset_millis = calendar.timeZone.getOffset(calendar.timeInMillis).to_f
-        if offset_millis.zero? then
-          offset = 0
-        else
-          offset_days = offset_millis / MILLIS_PER_DAY
-          offset_fraction = 1 / offset_days
-          offset = Rational(1, offset_fraction)
-        end
-        # convert to DateTime
-        DateTime.civil(time.year, time.mon, time.day, time.hour, time.min, time.sec, offset)
-      end
-
-      # Converts a Ruby Date or DateTime to a Java Date.
-      #
-      # @param [::Date, DateTime] date the Ruby date
-      # @return [Date] the Java date
-      def self.from_ruby_date(date)
-        return if date.nil?
-        # DateTime has time attributes, Date doesn't
-        if DateTime === date then
-          hour, min, sec = date.hour, date.min, date.sec
-        else
-          hour = min = sec = 0
-        end
-        # the Ruby time
-        rtime = Time.local(sec, min, hour, date.day, date.mon, date.year, nil, nil, nil, nil)
-        # millis since epoch
-        millis = (rtime.to_f * 1000).truncate
-        # the Java date factory
-        calendar = java.util.Calendar.instance
-        calendar.setTimeInMillis(millis)
-        jtime = calendar.getTime
-        # the daylight time flag
-        isdt = calendar.timeZone.inDaylightTime(jtime)
-        return jtime unless isdt
-        # adjust the Ruby time for DST
-        rtime = Time.local(sec, min, hour, date.day, date.mon, date.year, nil, nil, isdt, nil)
-        millis = (rtime.to_f * 1000).truncate
-        calendar.setTimeInMillis(millis)
-        calendar.getTime
-      end
-    end
-  end
-
-  def self.now
-    JavaUtil::Date.from_ruby_date(DateTime.now)
-  end
-  
-  # @param [Class, String] the JRuby class or the full Java class name
-  # @return (String, String] the package and base for the given name
-  def self.split_class_name(name_or_class)
-    name = Class === name_or_class ? name_or_class.java_class.name : name_or_class
-    match = NAME_SPLITTER_REGEX.match(name)
-    match ? match.captures : [nil, name]
-  end
-  
-  private
-  
-  NAME_SPLITTER_REGEX = /^([\w.]+)\.(\w+)$/
-end
-
-class Class
-  # Returns whether this is a Java wrapper class.
-  def java_class?
-    method_defined?(:java_class)
-  end
-
-  # Returns the Ruby class for the given class, as follows:
-  # * If the given class is already a Ruby class, then return the class.
-  # * If the class argument is a Java class or a Java class name, then
-  #   the Ruby class is the JRuby wrapper for the Java class.
-  #
-  # @param [Class, String] class_or_name the class or class name
-  # @return [Class] the corresponding Ruby class
-  def self.to_ruby(class_or_name)
-    case class_or_name
-      when Class then class_or_name
-      when String then eval to_ruby_name(class_or_name)
-      else to_ruby(class_or_name.name)
-    end
-  end
-
-  # @return [Boolean] whether this is a wrapper for an abstract Java class
-  def abstract?
-    java_class? and Java::JavaLangReflect::Modifier.isAbstract(java_class.modifiers)
-  end
-
-  # Returns whether the given PropertyDescriptor pd corresponds to a transient field in this class, or nil if there is no such field.
-  def transient?(pd)
-    begin
-      field = java_class.declared_field(pd.name)
-    rescue Exception
-      # should occur only if a property is not a field; not an error
-      return
-    end
-    Java::JavaLangReflect::Modifier.isTransient(field.modifiers) if field
-  end
-
-  # Returns this class's readable and writable Java PropertyDescriptors, or an empty Array if none.
-  # If the hierarchy flag is set to +false+, then only this class's properties
-  # will be introspected.
-  def java_properties(hierarchy=true)
-    return Array::EMPTY_ARRAY  unless java_class?
-    info = hierarchy ? Java::JavaBeans::Introspector.getBeanInfo(java_class) : Java::JavaBeans::Introspector.getBeanInfo(java_class, java_class.superclass)
-    info.propertyDescriptors.select { |pd| pd.write_method and property_read_method(pd) }
-  end
-
-  # Redefines the reserved method corresponeding to the given Java property descriptor pd
-  # back to the Object implementation, if necessary.
-  # If both this class and Object define a method with the property name,
-  # then a new method is defined with the same body as the previous method.
-  # Returns the new method symbol, or nil if name_or_symbol is not an occluded
-  # Object instance method.
-  #
-  # This method undoes the jRuby clobbering of Object methods by Java property method
-  # wrappers. The method is renamed as follows:
-  # * +id+ is changed to :identifier
-  # * +type+ is prefixed by the underscore subject class name, e.g. +Specimen.type => :specimen_type+,
-  #   If the property name is +type+ and the subject class name ends in 'Type', then the attribute
-  #   symbol is the underscore subject class name, e.g. +HistologicType.type => :histologic_type+.
-  #
-  # Raises ArgumentError if symbol is not an Object method.
-  def unocclude_reserved_method(pd)
-    oldname = pd.name.underscore
-    return unless OBJ_INST_MTHDS.include?(oldname)
-    oldsym = oldname.to_sym
-    undeprecated = case oldsym
-      when :id then :object_id
-      when :type then :class
-      else oldsym
-    end
-    rsvd_mth = Object.instance_method(undeprecated)
-    base = self.qp.underscore
-    newname = if oldname == 'id' then
-      'identifier'
-    elsif base[-oldname.length..-1] == oldname then
-      base
-    else
-      "#{base}_#{oldname}"
-    end
-    newsym = newname.to_sym
-    rdr = property_read_method(pd).name.to_sym
-    alias_method(newsym, rdr)
-    # alias the writers
-    wtr = pd.write_method.name.to_sym
-    alias_method("#{newsym}=".to_sym, wtr)
-    # alias a camel-case Java-style method if necessary
-    altname = newname.camelize
-    unless altname == newname then
-      alias_method(altname.to_sym, oldsym)
-      alias_method("#{altname}=".to_sym, wtr)
-    end
-    # restore the old method to Object
-    define_method(oldsym) { |*args| rsvd_mth.bind(self).call(*args) }
-    newsym
-  end
-
-  # @quirk caCORE java.lang.Boolean is<name> is not introspected as a read method, since the type
-  # must be primitive, i.e. `boolean is`<name>.
-  #
-  # @return [Symbol] the property descriptor pd introspected or discovered Java read Method
-  def property_read_method(pd)
-    return pd.read_method if pd.read_method
-    return unless pd.get_property_type == Java::JavaLang::Boolean.java_class
-    rdr = java_class.java_method("is#{pd.name.capitalize_first}") rescue nil
-    logger.debug { "Discovered #{qp} #{pd.name} property non-introspected reader method #{rdr.name}." } if rdr
-    rdr
-  end
-  
-  private
-  
-  OBJ_INST_MTHDS = Object.instance_methods
-  
-  # @param [String] jname the fully-qualified Java class or interface name
-  # @return [String] the JRuby class or module name
-  # #example
-  #   Java.to_ruby_class_name('com.test.Sample') #=> Java::ComTest::Sample
-  def self.to_ruby_name(jname)
-    path = jname.split('.')
-    return "Java::#{jname}" if path.size == 1
-    cname = path[-1]
-    pkg = path[0...-1].map { |s| s.capitalize_first }.join
-    "Java::#{pkg}::#{cname}"
-  end
-end
-
-class Array
-  alias :equal__base :==
-  # Overrides the standard == to compare a Java List with a Ruby Array.
-  def ==(other)
-    Java::JavaUtil::List === other ? other == self : equal__base(other)
-  end
-end

data/lib/caruby/migration/migrator.rb

@@ -1,918 +0,0 @@
-# load the required gems
-require 'rubygems'
-
-# the Units of Measurement gem
-gem 'uom'
-
-require 'enumerator'
-require 'date'
-require 'uom'
-require 'caruby/csv/csvio'
-require 'caruby/util/class'
-require 'caruby/util/log'
-require 'caruby/util/inflector'
-require 'caruby/util/options'
-require 'caruby/util/pretty_print'
-require 'caruby/util/properties'
-require 'caruby/util/collection'
-require 'caruby/migration/migratable'
-
-module CaRuby
-  class MigrationError < RuntimeError; end
-
-  # Migrates a CSV extract to a caBIG application.
-  class Migrator
-    include Enumerable
-
-    # Creates a new Migrator.
-    #
-    # @param [{Symbol => Object}] opts the migration options
-    # @option opts [String] :database required application {Database}
-    # @option opts [String] :target required target domain class
-    # @option opts [<String>, String] :mapping required input field => caTissue attribute mapping file(s)
-    # @option opts [<String>, String] :defaults optional caTissue attribute => value default mapping file(s)
-    # @option opts [<String>, String] :filters optional caTissue attribute input value => caTissue value filter file(s)
-    # @option opts [String] :input required source file to migrate
-    # @option opts [<String>, String] :shims optional shim file(s) to load
-    # @option opts [String] :unique ensures that migrated objects which include the {Resource::Unique}
-    # @option opts [String] :create optional flag indicating that existing target objects are ignored
-    # @option opts [String] :bad optional invalid record file
-    # @option opts [Integer] :offset zero-based starting source record number to process (default 0)
-    # @option opts [Boolean] :quiet suppress output messages
-    # @option opts [Boolean] :verbose print progress
-    def initialize(opts)
-      @rec_cnt = 0
-      parse_options(opts)
-      build
-    end
-    
-    # Imports this migrator's file into the database with the given connect options.
-    # This method creates or updates the domain objects mapped from the import source.
-    # If a block is given to this method, then the block is called on each stored
-    # migration target object.
-    #
-    # If the +:create+ option is set, then an input record for a target object which already
-    # exists in the database is noted in a debug log message and ignored rather than updated.
-    #
-    # @yield [target] operation performed on the migration target
-    # @yieldparam [Resource] target the migrated target domain object
-    def migrate_to_database(&block)
-      # migrate with save
-      tm = Stopwatch.measure { execute_save(&block) }.elapsed
-      logger.debug { format_migration_time_log_message(tm) }
-    end
-
-    # Imports this migrator's CSV file and calls the required block on each migrated target
-    # domain object.
-    #
-    # @yield [target] operation performed on the migration target
-    # @yieldparam [Resource] target the migrated target domain object
-    def migrate(&block)
-      raise MigrationError.new("The caRuby Migrator migrate block is missing") unless block_given?
-      migrate_rows(&block)
-    end
-
-    alias :each :migrate
-
-    private
-    
-    REGEXP_PAT = /^\/(.*[^\\])\/([inx]+)?$/
-
-    # Class {#migrate} with a {#save} block.
-    def execute_save
-      if @database.nil? then
-        raise MigrationError.new("Migrator cannot save records since the database option was not specified.")
-      end
-      @database.open do |db|
-        migrate do |target|
-          save(target, db)
-          yield target if block_given?
-          db.clear
-        end
-      end
-    end
-
-    # @return a log message String for the given migration time in seconds
-    def format_migration_time_log_message(time)
-      # the database execution time
-      dt = @database.execution_time
-      if time > 120 then
-        time /= 60
-        dt /= 60
-        unit = "minutes"
-      else
-        unit = "seconds"
-      end
-      "Migration took #{'%.2f' % time} #{unit}, of which #{'%.2f' % dt} were database operations."
-    end
-
-    def parse_options(opts)
-      @fld_map_files = opts[:mapping]
-      raise MigrationError.new("Migrator missing required field mapping file parameter") if @fld_map_files.nil?
-      @def_files = opts[:defaults]
-      @filter_files = opts[:filters]
-      @shims = opts[:shims] ||= []
-      @offset = opts[:offset] ||= 0
-      @input = Options.get(:input, opts)
-      raise MigrationError.new("Migrator missing required source file parameter") if @input.nil?
-      @database = opts[:database]
-      @target_class = opts[:target]
-      raise MigrationError.new("Migrator missing required target class parameter") if @target_class.nil?
-      @bad_rec_file = opts[:bad]
-      @create = opts[:create]
-      logger.info("Migration options: #{printable_options(opts).pp_s}.")
-      # flag indicating whether to print a progress monitor
-      @print_progress = opts[:verbose]
-    end
-    
-    def printable_options(opts)
-      popts = opts.reject { |option, value| value.nil_or_empty? }
-      # The target class should be a simple class name rather than the class metadata.
-      popts[:target] = popts[:target].qp if popts.has_key?(:target)
-      popts
-    end
-
-    def build
-      # the current source class => instance map
-      raise MigrationError.new("No file to migrate") if @input.nil?
-
-      # make a CSV loader which only converts input fields corresponding to non-String attributes
-      @loader = CsvIO.new(@input, &method(:convert))
-      logger.debug { "Migration data input file #{@input} headers: #{@loader.headers.qp}" } 
-      
-      # add shim modifiers
-      load_shims(@shims)
-
-      # create the class => path => default value hash
-      @def_hash = @def_files ? load_defaults_files(@def_files) : {}
-      # create the class => path => default value hash
-      @filter_hash = @filter_files ? load_filter_files(@filter_files) : {}
-      # create the class => path => header hash
-      fld_map = load_field_map_files(@fld_map_files)
-      # create the class => paths hash
-      @cls_paths_hash = create_class_paths_hash(fld_map, @def_hash)
-      # create the path => class => header hash
-      @header_map = create_header_map(fld_map)
-      # add missing owner classes (copy the keys rather than using each_key since the hash is updated)
-      @owners = Set.new
-      @cls_paths_hash.keys.each { |klass| add_owners(klass) }
-      # order the creatable classes by dependency, owners first, to smooth the migration process
-      @creatable_classes = @cls_paths_hash.keys.sort! { |klass, other| other.depends_on?(klass) ? -1 : (klass.depends_on?(other) ? 1 : 0) }
-      @creatable_classes.each do |klass|
-        if klass.abstract? then
-          raise MigrationError.new("Migrator cannot create the abstract class #{klass}; specify a subclass instead in the mapping file.")
-        end
-      end
-      
-      # print the maps
-      print_hash = LazyHash.new { Hash.new }
-      @cls_paths_hash.each do |klass, paths|
-        print_hash[klass.qp] = paths.map { |path| {path.map { |attr_md| attr_md.to_sym  }.join('.') => @header_map[path][klass] } }
-      end
-      logger.info { "Migration paths:\n#{print_hash.pp_s}" }
-      logger.info { "Migration creatable classes: #{@creatable_classes.qp}." }
-      unless @def_hash.empty? then logger.info { "Migration defaults: #{@def_hash.qp}." } end
-      
-      # the class => attribute migration methods hash
-      create_migration_method_hashes
-      
-      # Collect the String input fields for the custom CSVLoader converter.
-      @nonstring_headers = Set.new
-      logger.info("Migration attributes:")
-      @header_map.each do |path, cls_hdr_hash|
-        attr_md = path.last
-        cls_hdr_hash.each do |klass, hdr|
-          type_s = attr_md.type ? attr_md.type.qp : 'Object'
-          logger.info("  #{hdr} => #{klass.qp}.#{path.join('.')} (#{type_s})")
-        end
-        @nonstring_headers.merge!(cls_hdr_hash.values) if attr_md.type != Java::JavaLang::String
-      end
-    end
-    
-    # Converts the given input field value as follows:
-    # * if the info header is a String field, then return the value unchanged
-    # * otherwise, if the value is a case-insensitive match for +true+ or +false+, then convert
-    #   the value to the respective Boolean
-    # * otherwise, return nil which will delegate to the generic CsvIO converter
-    # @param (see CsvIO#convert)
-    # @yield (see CsvIO#convert)
-    def convert(value, info)
-      @nonstring_headers.include?(info.header) ? convert_boolean(value) : value
-    end
-    
-    # @param [String] value the input value
-    # @return [Boolean, nil] the corresponding boolean, or nil if none
-    def convert_boolean(value)
-      case value
-        when /true/i then true
-        when /false/i then false
-      end
-    end
-    
-    # Adds missing owner classes to the migration class path hash (with empty paths)
-    # for the  the given migration class.
-    #
-    # @param [Class] klass the migration class
-    def add_owners(klass)
-      owner = missing_owner_for(klass) || return
-      logger.debug { "Migrator adding #{klass.qp} owner #{owner}" }
-      @owners << owner
-      @cls_paths_hash[owner] = Array::EMPTY_ARRAY
-      add_owners(owner)
-    end
-    
-    # @param [Class] klass the migration class
-    # @return [Class, nil] the missing class owner, if any
-    def missing_owner_for(klass)
-      # check for an owner among the current migration classes
-      return if klass.owners.any? do |owner|
-        @cls_paths_hash.detect_key { |other| other <= owner }
-      end
-      # find the first non-abstract candidate owner
-      klass.owners.detect { |owner| not owner.abstract? }
-    end
-
-    # Creates the class => +migrate_+_<attribute>_ hash for the given klasses.
-    def create_migration_method_hashes
-      # the class => attribute => migration filter hash
-      @attr_flt_hash = {}
-      customizable_class_attributes.each do |klass, attr_mds|
-        flts = migration_filters(klass, attr_mds) || next
-        @attr_flt_hash[klass] = flts
-      end
-
-      # print the migration shim methods
-      unless @attr_flt_hash.empty? then
-        printer_hash = LazyHash.new { Array.new }
-        @attr_flt_hash.each do |klass, hash|
-          mths = hash.values.select { |flt| Symbol === flt }
-          printer_hash[klass.qp] = mths unless mths.empty?
-        end
-        logger.info("Migration shim methods: #{printer_hash.pp_s}.") unless printer_hash.empty?
-      end
-    end
-
-    # @return the class => attributes hash for terminal path attributes which can be customized by +migrate_+ methods
-    def customizable_class_attributes
-      # The customizable classes set, starting with creatable classes and adding in
-      # the migration path terminal attribute declarer classes below.
-      klasses = @creatable_classes.to_set
-      # the class => path terminal attributes hash
-      cls_attrs_hash = LazyHash.new { Set.new }
-      # add each path terminal attribute and its declarer class
-      @cls_paths_hash.each_value do |paths|
-        paths.each do |path|
-          attr_md = path.last
-          type = attr_md.declarer
-          klasses << type
-          cls_attrs_hash[type] << attr_md
-        end
-      end
-      
-      # Merge each redundant customizable superclass into its concrete customizable subclasses. 
-      klasses.dup.each do |cls|
-        redundant = false
-        klasses.each do |other|
-          # cls is redundant if it is a superclass of other
-          redundant = other < cls
-          if redundant then
-            cls_attrs_hash[other].merge!(cls_attrs_hash[cls])
-          end
-        end
-        # remove the redundant class
-        if redundant then
-          cls_attrs_hash.delete(cls)
-          klasses.delete(cls)
-        end
-      end
-      
-      cls_attrs_hash
-    end
-
-    # Discovers methods of the form +migrate+__attribute_ implemented for the paths
-    # in the given class => paths hash the given klass. The migrate method is called
-    # on the input field value corresponding to the path.
-    def migration_filters(klass, attr_mds)
-      # the attribute => migration method hash
-      mth_hash = attribute_method_hash(klass, attr_mds)
-      proc_hash = attribute_proc_hash(klass, attr_mds)
-      return if mth_hash.empty? and proc_hash.empty?
-
-      # for each class path terminal attribute metadata, add the migration filters
-      # to the attribute metadata => filter hash
-      attr_mds.to_compact_hash do |attr_md|
-        # the filter proc
-        proc = proc_hash[attr_md.to_sym]
-        # the migration shim method
-        mth = mth_hash[attr_md.to_sym]
-        if mth then
-          if proc then
-            Proc.new do |obj, value, row|
-              # filter the value
-              fval = proc.call(value)
-              # call the migration method on the filtered value
-              obj.send(mth, fval, row) unless fval.nil?
-            end
-          else
-            # call the migration method
-            Proc.new { |obj, value, row| obj.send(mth, value, row) }
-          end
-        elsif proc then
-          # call the filter
-          Proc.new { |obj, value, row| proc.call(value) }
-        end
-      end
-    end
-    
-    def attribute_method_hash(klass, attr_mds)
-      # the migrate methods, excluding the Migratable migrate_references method
-      mths = klass.instance_methods(true).select { |mth| mth =~ /^migrate.(?!references)/ }
-      # the attribute => migration method hash
-      mth_hash = {}
-      mths.each do |mth|
-        # the attribute suffix, e.g. name for migrate_name or Name for migrateName
-        suffix = /^migrate(_)?(.*)/.match(mth).captures[1]
-        # the attribute name
-        attr_nm = suffix[0, 1].downcase + suffix[1..-1]
-        # the attribute for the name, or skip if no such attribute
-        attr = klass.standard_attribute(attr_nm) rescue next
-        # associate the attribute => method
-        mth_hash[attr] = mth
-      end
-      mth_hash
-    end
-    
-    # @return [Attribute => {Object => Object}] the filter migration methods
-    def attribute_proc_hash(klass, attr_mds)
-      hash = @filter_hash[klass]
-      if hash.nil? then return Hash::EMPTY_HASH end
-      proc_hash = {}
-      attr_mds.each do |attr_md|
-        flt = hash[attr_md.to_sym] || next
-        proc_hash[attr_md.to_sym] = to_filter_proc(flt)
-      end
-      logger.debug { "Migration filters loaded for #{klass.qp} #{proc_hash.keys.to_series}." }
-      proc_hash
-    end
-    
-    # Builds a proc that filters the input value. The config filter mapping entry is one of the following:
-    #   * literal: literal
-    #   * regexp: literal
-    #   * regexp: template
-    #
-    # The regexp template can include match references (+$1+, +$2+, etc.) corresponding to the regexp captures.
-    # If the input value equals a literal, then the mapped literal is returned. Otherwise, if the input value
-    # matches a regexp, then the mapped transformation is returned after reference substitution. Otherwise,
-    # the input value is returned unchanged.
-    #
-    # For example, the config:
-    #   /(\d{1,2})\/x\/(\d{1,2})/: $1/1/$2
-    #   n/a: ~
-    # converts the input value as follows:
-    #   3/12/02 => 3/12/02 (no match)
-    #   5/x/04 => 5/1/04
-    #   n/a => nil 
-    #
-    # @param [{Object => Object}] filter the config value mapping
-    # @return [Proc] the filter migration block
-    # @raise [MigrationError] if the filter includes a regexp option other than +i+ (case-insensitive)
-    def to_filter_proc(filter)
-      # Split the filter into a straight value => value hash and a pattern => value hash.
-      ph, vh = filter.split { |k, v| k =~ REGEXP_PAT }
-      # The Regexp => value hash is built from the pattern => value hash.
-      reh = {}
-      ph.each do |k, v|
-        # The /pattern/opts string is parsed to the pattern and options.
-        pat, opt = REGEXP_PAT.match(k).captures
-        # Convert the regexp i option character to a Regexp initializer parameter.
-        reopt = if opt then
-          case opt
-            when 'i' then Regexp::IGNORECASE
-            else raise MigrationError.new("Migration value filter regular expression #{k} qualifier not supported: expected 'i', found '#{opt}'")
-          end
-        end
-        # the Regexp object
-        re = Regexp.new(pat, reopt)
-        # The regexp value can include match references ($1, $2, etc.). In that case, replace the $
-        # match reference with a %s print reference, since the filter formats the matching input value.
-        reh[re] = String === v ? v.gsub(/\$\d/, '%s') : v
-      end
-      # The new proc matches preferentially on the literal value, then the first matching regexp.
-      # If no match on either a literal or a regexp, then the value is preserved.
-      Proc.new do |value|
-        if vh.has_key?(value) then
-          vh[value]
-        else
-          # The first regex which matches the value.
-          regexp = reh.detect_key { |re| value =~ re }
-          # If there is a match, then apply the filter to the match data.
-          # Otherwise, pass the value through unmodified.
-          if regexp then
-            v = reh[regexp]
-            String === v ? v % $~.captures : v
-          else
-            value
-          end
-        end
-      end
-    end
-
-    # Loads the shim files.
-    #
-    # @param [<String>, String] files the file or file array
-    def load_shims(files)
-      logger.debug { "Loading shims with load path #{$:.pp_s}..." }
-      files.enumerate do |file|
-        # load the file
-        begin
-          require file
-      rescue Exception => e
-          logger.error("Migrator couldn't load shim file #{file} - #{e}.")
-          raise
-        end
-        logger.info { "Migrator loaded shim file #{file}." }
-      end
-    end
-
-    # Migrates all rows in the input.
-    #
-    # @yield (see #migrate)
-    # @yieldparam (see #migrate)
-    def migrate_rows
-      # open an CSV output for bad records if the option is set
-      if @bad_rec_file then
-        @loader.trash = @bad_rec_file
-        logger.info("Unmigrated records will be written to #{File.expand_path(@bad_rec_file)}.")
-      end
-      @rec_cnt = mgt_cnt = 0
-      logger.info { "Migrating #{@input}..." }
-      @loader.each do |row|
-        # the one-based current record number
-        rec_no = @rec_cnt + 1
-        # skip if the row precedes the offset option
-        @rec_cnt += 1 && next if @rec_cnt < @offset
-        begin
-          # migrate the row
-          logger.debug { "Migrating record #{rec_no}..." }
-          target = migrate_row(row)
-          # call the block on the migrated target
-          if target then
-            logger.debug { "Migrator built #{target} with the following content:\n#{target.dump}" }
-            yield target
-          end
-        rescue Exception => e
-          trace = e.backtrace.join("\n")
-          logger.error("Migration error on record #{rec_no} - #{e.message}:\n#{trace}")
-          raise unless @bad_file
-        end
-        if target then
-          # replace the log message below with the commented alternative to detect a memory leak
-          logger.debug { "Migrated record #{rec_no}." }
-          #memory_usage = `ps -o rss= -p #{Process.pid}`.to_f / 1024 # in megabytes
-          #logger.debug { "Migrated rec #{@rec_cnt}; memory usage: #{sprintf("%.1f", memory_usage)} MB." }
-          if @print_progress then print_progress(mgt_cnt) end
-          mgt_cnt += 1
-          # clear the migration state
-          clear(target)
-        else
-          # If there is a bad file then warn, reject and continue. Otherwise, bail.
-          if @bad_rec_file then
-            logger.warn("Migration not performed on record #{rec_no}.")
-            @loader.reject(row)
-          else
-            raise MigrationError.new("Migration not performed on record #{rec_no}")
-          end
-        end
-        # Bump the record count.
-        @rec_cnt += 1
-      end
-      logger.info("Migrated #{mgt_cnt} of #{@rec_cnt} records.")
-    end
-    
-    # Prints a +\++ progress indicator to stdout if the count parameter is divisible by ten.
-    #
-    # @param [Integer] count the progress step count
-    def print_progress(count)
-      if count % 720 then puts end
-      if count % 10 == 0 then puts "+" else print "+" end
-    end
-
-    # Clears references to objects allocated for migration of a single row into the given target.
-    # This method does nothing. Subclasses can override.
-    #
-    # This method is overridden by subclasses to clear the migration state to conserve memory,
-    # since this migrator should consume O(1) rather than O(n) memory for n migration records.
-    def clear(target)
-    end
-
-    # Imports the given CSV row into a target object.
-    #
-    # @param [{Symbol => Object}] row the input row field => value hash
-    # @return the migrated target object if the migration is valid, nil otherwise
-    def migrate_row(row)
-      # create an instance for each creatable class
-      created = Set.new
-      migrated = @creatable_classes.map { |klass| create(klass, row, created) }
-      # migrate each object from the input row
-      created.each { |obj| obj.migrate(row, migrated) }
-      valid = migrate_valid_references(row, migrated)
-      # the target object
-      target = valid.detect { |obj| @target_class === obj } || return
-      logger.debug { "Migrated target #{target}." }
-      target
-    end
-    
-    # Sets the migration references for each valid migrated object.
-    #
-    # @param [Array] the migrated objects
-    # @return [Array] the valid migrated objects
-    def migrate_valid_references(row, migrated)
-      # Split the valid and invalid objects. The iteration is in reverse dependency order,
-      # since invalidating a dependent can invalidate the owner.
-      valid, invalid = migrated.transitive_closure(:dependents).reverse.partition do |obj|
-        if migration_valid?(obj) then
-          obj.migrate_references(row, migrated, @attr_flt_hash[obj.class])
-          true
-        else
-          obj.class.owner_attributes.each { |attr| obj.clear_attribute(attr) }
-          false
-        end
-      end
-      
-      # Go back through the valid objects in dependency order to invalidate dependents
-      # whose owner is invalid.
-      valid.reverse.each do |obj|
-        unless owner_valid?(obj, valid, invalid) then
-          invalid << valid.delete(obj)
-          logger.debug { "Invalidated migrated #{obj} since it does not have a valid owner." }
-        end
-      end
-      
-      # Go back through the valid objects in reverse dependency order to invalidate owners
-      # created only to hold a dependent which was subsequently invalidated.
-      valid.reject do |obj|
-        if @owners.include?(obj.class) and obj.dependents.all? { |dep| invalid.include?(dep) } then
-          # clear all references from the invalidated owner
-          obj.class.domain_attributes.each_metadata { |attr_md| obj.clear_attribute(attr_md.to_sym) }
-          invalid << obj
-          logger.debug { "Invalidated #{obj.qp} since it was created solely to hold subsequently invalidated dependents." }
-          true
-        end
-      end
-    end
-    
-    # Returns whether the given domain object satisfies at least one of the following conditions:
-    # * it does not have an owner among the invalid objects
-    # * it has an owner among the valid objects
-    #
-    # @param [Resource] obj the domain object to check
-    # @param [<Resource>] valid the valid migrated objects
-    # @param [<Resource>] invalid the invalid migrated objects
-    # @return [Boolean] whether the owner is valid 
-    def owner_valid?(obj, valid, invalid)
-      otypes = obj.class.owners
-      invalid.all? { |other| not otypes.include?(other.class) } or
-        valid.any? { |other| otypes.include?(other.class) }
-    end
-
-    # @param [Migratable] obj the migrated object
-    # @return [Boolean] whether the migration is successful
-    def migration_valid?(obj)
-      if obj.migration_valid? then
-        true
-      else
-        logger.debug { "Migrated #{obj.qp} is invalid." }
-        false
-      end
-    end
-
-    # Creates an instance of the given klass from the given row.
-    # The new klass instance and all intermediate migrated instances are added to the
-    # created set.
-    #
-    # @param [Class] klass
-    # @param [{Symbol => Object}] row the input row
-    # @param [<Resource>] created the migrated instances for this row
-    # @return [Resource] the new instance
-    def create(klass, row, created)
-      # the new object
-      logger.debug { "Migrator building #{klass.qp}..." }
-      created << obj = klass.new
-      migrate_attributes(obj, row, created)
-      add_defaults(obj, row, created)
-      logger.debug { "Migrator built #{obj}." }
-      obj
-    end
-    
-    # @param [Resource] the migration object
-    # @param row (see #create)
-    # @param [<Resource>] created (see #create)
-    def migrate_attributes(obj, row, created)
-      # for each input header which maps to a migratable target attribute metadata path,
-      # set the target attribute, creating intermediate objects as needed.
-      @cls_paths_hash[obj.class].each do |path|
-        header = @header_map[path][obj.class]
-        # the input value
-        value = row[header]
-        next if value.nil?
-        # fill the reference path
-        ref = fill_path(obj, path[0...-1], row, created)
-        # set the attribute
-        migrate_attribute(ref, path.last, value, row)
-      end
-    end
-    
-    # @param [Resource] the migration object
-    # @param row (see #create)
-    # @param [<Resource>] created (see #create)
-    def add_defaults(obj, row, created)
-      dh = @def_hash[obj.class] || return
-      dh.each do |path, value|
-        # fill the reference path
-        ref = fill_path(obj, path[0...-1], row, created)
-        # set the attribute to the default value unless there is already a value
-        ref.merge_attribute(path.last.to_sym, value)
-      end
-    end
-
-    # Fills the given reference Attribute path starting at obj.
-    #
-    # @param row (see #create)
-    # @param created (see #create)
-    # @return the last domain object in the path
-    def fill_path(obj, path, row, created)
-      # create the intermediate objects as needed (or return obj if path is empty)
-      path.inject(obj) do |parent, attr_md|
-        # the referenced object
-        parent.send(attr_md.reader) or create_reference(parent, attr_md, row, created)
-      end
-    end
-
-    # Sets the given migrated object's reference attribute to a new referenced domain object.
-    #
-    # @param [Resource] obj the domain object being migrated
-    # @param [Attribute] attr_md the attribute being migrated
-    # @param row (see #create)
-    # @param created (see #create)
-    # @return the new object
-    def create_reference(obj, attr_md, row, created)
-      if attr_md.type.abstract? then
-        raise MigrationError.new("Cannot create #{obj.qp} #{attr_md} with abstract type #{attr_md.type}")
-      end
-      ref = attr_md.type.new
-      ref.migrate(row, Array::EMPTY_ARRAY)
-      obj.send(attr_md.writer, ref)
-      created << ref
-      logger.debug { "Migrator created #{obj.qp} #{attr_md} #{ref}." }
-      ref
-    end
-
-    # Sets the given attribute value to the filtered input value. If there is a filter
-    # defined for the attribute, then that filter is applied. If there is a migration
-    # shim method with name +migrate_+_attribute_, then than method is called on the
-    # (possibly filtered) value. The target object attribute is set to the resulting
-    # filtered value. 
-    #
-    # @param [Migratable] obj the target domain object
-    # @param [Attribute] attr_md the target attribute
-    # @param value the input value
-    # @param [{Symbol => Object}] row the input row
-    def migrate_attribute(obj, attr_md, value, row)
-      # if there is a shim migrate_<attribute> method, then call it on the input value
-      value = filter_value(obj, attr_md, value, row) || return
-      # set the attribute
-      begin
-        obj.send(attr_md.writer, value)
-      rescue Exception
-        raise MigrationError.new("Could not set #{obj.qp} #{attr_md} to #{value.qp} - #{$!}")
-      end
-      logger.debug { "Migrated #{obj.qp} #{attr_md} to #{value}." }
-    end
-    
-    # Calls the shim migrate_<attribute> method or config filter on the input value.
-    #
-    # @param value the input value
-    # @return the input value, if there is no filter, otherwise the filtered value
-    def filter_value(obj, attr_md, value, row)
-      filter = filter_for(obj, attr_md)
-      return value if filter.nil?
-      fval = filter.call(obj, value, row)
-      unless value == fval then
-        logger.debug { "Migration filter transformed #{obj.qp} #{attr_md} value from #{value.qp} to #{fval.qp}." }
-      end
-      fval
-    end
-    
-    def filter_for(obj, attr_md)
-      flts = @attr_flt_hash[obj.class] || return
-      flts[attr_md]
-    end
-
-    # @param [Resource] obj the domain object to save in the database
-    # @return [Resource, nil] obj if the save is successful, nil otherwise
-    def save(obj, database)
-      if @create then
-        if database.find(obj) then
-          logger.debug { "Migrator ignored record #{current_record}, since it already exists as #{obj.printable_content(obj.class.secondary_key_attributes)} with id #{obj.identifier}." }
-        else
-          logger.debug { "Migrator creating #{obj}..." }
-          database.create(obj)
-          logger.debug { "Migrator creating #{obj}." }
-        end
-      else
-        logger.debug { "Migrator saving #{obj}..." }
-        database.save(obj)
-        logger.debug { "Migrator saved #{obj}." }
-      end
-    end
-    
-    def current_record
-      @rec_cnt + 1
-    end
-
-    # @param [<String>, String] files the migration fields mapping file or file array
-    # @return [{Class => {Attribute => Symbol}}] the class => path => header hash
-    #   loaded from the mapping files
-    def load_field_map_files(files)
-      map = LazyHash.new { Hash.new }
-      files.enumerate { |file| load_field_map_file(file, map) }
-
-      # include the target class
-      map[@target_class] ||= Hash.new
-      # include the default classes
-      @def_hash.each_key { |klass| map[klass] ||= Hash.new }
-
-      # add superclass paths into subclass paths
-      map.each do |klass, path_hdr_hash|
-        map.each do |other, other_path_hdr_hash|
-          if klass < other then
-            # add, but don't replace, path => header entries from superclass
-            path_hdr_hash.merge!(other_path_hdr_hash) { |key, old, new| old }
-          end
-        end
-      end
-
-      # include only concrete classes
-      classes = map.keys
-      map.delete_if do |klass, paths|
-        klass.abstract? or classes.any? { |other| other < klass }
-      end
-
-      map
-    end
-    
-    # @param [String] file the migration fields configuration file
-    # @param [{Class => {Attribute => Symbol}}] hash the class => path => header hash
-    #   loaded from the configuration file
-    def load_field_map_file(file, hash)
-      # load the field mapping config file
-      begin
-        config = YAML::load_file(file)
-      rescue
-        raise MigrationError.new("Could not read field map file #{file}: " + $!)
-      end
-
-      # collect the class => path => header entries
-      config.each do |field, attr_list|
-        next if attr_list.blank?
-        # the header accessor method for the field
-        header = @loader.accessor(field)
-        raise MigrationError.new("Field defined in migration configuration #{file} not found in input file #{@input} headers: #{field}") if header.nil?
-        # associate each attribute path in the property value with the header
-        attr_list.split(/,\s*/).each do |path_s|
-          klass, path = create_attribute_path(path_s)
-          hash[klass][path] = header
-        end
-      end
-    end
-    
-    # Loads the defaults config files.
-    #
-    # @param [<String>, String] files the file or file array to load
-    # @return [<Class => <String => Object>>] the class => path => default value entries 
-    def load_defaults_files(files)
-      # collect the class => path => value entries from each defaults file
-      hash = LazyHash.new { Hash.new }
-      files.enumerate { |file| load_defaults_file(file, hash) }
-      hash
-    end
-    
-    # Loads the defaults config file into the given hash.
-    #
-    # @param [String] file the file to load
-    # @param [<Class => <String => Object>>] hash the class => path => default value entries 
-    def load_defaults_file(file, hash)
-      begin
-        config = YAML::load_file(file)
-      rescue
-        raise MigrationError.new("Could not read defaults file #{file}: " + $!)
-      end
-      # collect the class => path => value entries
-      config.each do |path_s, value|
-        next if value.nil_or_empty?
-        klass, path = create_attribute_path(path_s)
-        hash[klass][path] = value
-      end
-    end    
-    # Loads the filter config files.
-    #
-    # @param [<String>, String] files the file or file array to load
-    # @return [<Class => <String => Object>>] the class => path => default value entries 
-    def load_filter_files(files)
-      # collect the class => path => value entries from each defaults file
-      hash = {}
-      files.enumerate { |file| load_filter_file(file, hash) }
-      hash
-    end
-    
-    # Loads the filter config file into the given hash.
-    #
-    # @param [String] file the file to load
-    # @param [<Class => <String => <Object => Object>>>] hash the class => path => input value => caTissue value entries 
-    def load_filter_file(file, hash)
-      begin
-        config = YAML::load_file(file)
-      rescue
-        raise MigrationError.new("Could not read filter file #{file}: " + $!)
-      end
-      # collect the class => attribute => filter entries
-      config.each do |path_s, flt|
-        next if flt.nil_or_empty?
-        klass, path = create_attribute_path(path_s)
-        unless path.size == 1 then
-          raise MigrationError.new("Migration filter configuration path not supported: #{path_s}")
-        end
-        attr = klass.standard_attribute(path.first.to_sym)
-        flt_hash = hash[klass] ||= {}
-        flt_hash[attr] = flt
-      end
-    end
-
-    # @param [String] path_s a period-delimited path string path_s in the form _class_(._attribute_)+
-    # @return [<Attribute>] the corresponding attribute metadata path
-    # @raise [MigrationError] if the path string is malformed or an attribute is not found
-    def create_attribute_path(path_s)
-      names = path_s.split('.')
-      # if the path starts with a capitalized class name, then resolve the class.
-      # otherwise, the target class is the start of the path.
-      klass = names.first =~ /^[A-Z]/ ? class_for_name(names.shift) : @target_class
-      # there must be at least one attribute
-      if names.empty? then
-        raise MigrationError.new("Attribute entry in migration configuration is not in <class>.<attribute> format: #{value}")
-      end
-      # build the Attribute path
-      path = []
-      names.inject(klass) do |parent, name|
-        attr = name.to_sym
-        attr_md = begin
-          parent.attribute_metadata(attr)
-        rescue NameError
-          raise MigrationError.new("Migration field mapping attribute #{parent.qp}.#{attr} not found: #{$!}")
-        end
-        if attr_md.collection? then
-          raise MigrationError.new("Migration field mapping attribute #{parent.qp}.#{attr} is a collection, which is not supported")
-        end
-        path << attr_md
-        attr_md.type
-      end
-      # return the starting class and Attribute path.
-      # note that the starting class is not necessarily the first path attribute declarer, since the
-      # starting class could be the concrete target class rather than an abstract declarer. this is
-      # important, since the class must be instantiated.
-      [klass, path]
-    end
-    
-    # @param [String] name the class name, without the {#context_module}
-    # @return [Class] the corresponding class
-    def class_for_name(name)
-      # navigate through the scope to the final class
-      name.split('::').inject(context_module) do |ctxt, cnm|
-        ctxt.const_get(cnm)
-      end
-    end
-    
-    # The context module is given by the target class {ResourceClass#domain_module}.
-    #
-    # @return [Module] the class name resolution context
-    def context_module
-      @target_class.domain_module
-    end
-
-    # @return a new class => [paths] hash from the migration fields configuration map
-    def create_class_paths_hash(fld_map, def_map)
-      hash = {}
-      fld_map.each { |klass, path_hdr_hash| hash[klass] = path_hdr_hash.keys.to_set }
-      def_map.each { |klass, path_val_hash| (hash[klass] ||= Set.new).merge(path_val_hash.keys) }
-      hash
-    end
-
-    # @return a new path => class => header hash from the migration fields configuration map
-    def create_header_map(fld_map)
-      hash = LazyHash.new { Hash.new }
-      fld_map.each do |klass, path_hdr_hash|
-        path_hdr_hash.each { |path, hdr| hash[path][klass] = hdr }
-      end
-      hash
-    end
-  end
-end