moab-versioning 1.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fe7dbe157c6bc9418f8b336b65431a1266ca4375
+  data.tar.gz: 5328ef34ef060962cf9598001c6d146cde7afdc3
+SHA512:
+  metadata.gz: 79893b2a0f5b5d5791cee7ef9d26213d2f6876ea32f71a258d6d3030982fa8a6824f5285de20e343775ca1dc4625cbc16d32c793182116f830c7a4065dd5c5ce
+  data.tar.gz: e73bae98354c6001887a6a1fa24589919e696596c74ffdaac0b3132b123c761fea0850e5000d3795443af49b696a3e4cbc92567d4ccb7fa5020f1cbfa7aeb191

data/lib/moab.rb

@@ -0,0 +1,59 @@
+# Moab is a module that provides a distintive namespace for the collection of classes it contains.
+#
+# ====Data Model
+#
+# * <b>{FileInventory} = container for recording information about a collection of related files</b>
+#   * {FileGroup} [1..*] = subset allow segregation of content and metadata files
+#     * {FileManifestation} [1..*] = snapshot of a file's filesystem characteristics
+#       * {FileSignature} [1] = file fixity information
+#       * {FileInstance} [1..*] = filepath and timestamp of any physical file having that signature
+#
+# * <b>{SignatureCatalog} = lookup table containing a cumulative collection of all files ever ingested</b>
+#   * {SignatureCatalogEntry} [1..*] = an row in the lookup table containing storage information about a single file
+#     * {FileSignature} [1] = file fixity information
+#
+# * <b>{FileInventoryDifference} = compares two {FileInventory} instances based on file signatures and pathnames</b>
+#   * {FileGroupDifference} [1..*] = performs analysis and reports differences between two matching {FileGroup} objects
+#     * {FileGroupDifferenceSubset} [1..5] = collects a set of file-level differences of a give change type
+#       * {FileInstanceDifference} [1..*] = contains difference information at the file level
+#         * {FileSignature} [1..2] = contains the file signature(s) of two file instances being compared
+#
+# * <b>{VersionMetadata} = descriptive information about a digital object's versions</b>
+#   * {VersionMetadataEntry} [1..*] = attributes of a digital object version
+#     * {VersionMetadataEvent} [1..*] = object version lifecycle events with timestamps
+#
+# * <b>{StorageObject} = represents a digital object's repository storage location and ingest/dissemination methods</b>
+#   * {StorageObjectVersion} [1..*] = represents a version subdirectory within an object's home directory
+#     * {Bagger} [1] = utility for creating bagit packages for ingest or dissemination
+#
+# @note Copyright (c) 2012 by The Board of Trustees of the Leland Stanford Junior University.
+#   All rights reserved.  See {file:LICENSE.rdoc} for details.
+module Moab
+end
+
+require 'serializer'
+include Serializer
+require 'confstruct/configuration'
+require 'moab/config'
+require 'moab/file_signature'
+require 'moab/file_instance'
+require 'moab/file_manifestation'
+require 'moab/file_group'
+require 'moab/file_inventory'
+require 'moab/signature_catalog_entry'
+require 'moab/signature_catalog'
+require 'moab/file_instance_difference'
+require 'moab/file_group_difference_subset'
+require 'moab/file_group_difference'
+require 'moab/file_inventory_difference'
+require 'moab/version_metadata_event'
+require 'moab/version_metadata_entry'
+require 'moab/version_metadata'
+require 'moab/bagger'
+require 'moab/storage_object'
+require 'moab/storage_object_version'
+require 'moab/storage_repository'
+require 'moab/storage_services'
+require 'moab/exceptions'
+require 'moab/verification_result'
+

data/lib/moab/bagger.rb

@@ -0,0 +1,289 @@
+require 'moab'
+require 'systemu'
+
+module Moab
+
+  # A class used to create a BagIt package from a version inventory and a set of source files.
+  # The {#fill_bag} method is called with a package_mode parameter that specifies
+  # whether the bag is being created for deposit into the repository or is to contain the output of a version reconstruction.
+  # * In <b>:depositor</b> mode, the version inventory is filtered using the digital object's signature catalog so that only new files are included
+  # * In <b>:reconstructor</b> mode, the version inventory and signature catalog are used together to regenerate the complete set of files for the version.
+  #
+  # ====Data Model
+  # * {StorageRepository} = represents a digital object repository storage node
+  #   * {StorageServices} = supports application layer access to the repository's objects, data, and metadata
+  #   * {StorageObject} = represents a digital object's repository storage location and ingest/dissemination methods
+  #     * {StorageObjectVersion} [1..*] = represents a version subdirectory within an object's home directory
+  #       * <b>{Bagger} [1] = utility for creating bagit packages for ingest or dissemination</b>
+  #
+  # @note Copyright (c) 2012 by The Board of Trustees of the Leland Stanford Junior University.
+  #   All rights reserved.  See {file:LICENSE.rdoc} for details.
+  class Bagger
+
+    # @param version_inventory [FileInventory] The complete inventory of the files comprising a digital object version
+    # @param signature_catalog [SignatureCatalog] The signature catalog, used to specify source paths (in :reconstructor mode),
+    #   or to filter the version inventory (in :depositor mode)
+    # @param bag_pathname [Pathname,String] The location of the Bagit bag to be created
+    def initialize(version_inventory, signature_catalog, bag_pathname)
+      @version_inventory = version_inventory
+      @signature_catalog = signature_catalog
+      @bag_pathname = Pathname.new(bag_pathname)
+      create_bagit_txt()
+    end
+
+    # @return [FileInventory] The complete inventory of the files comprising a digital object version
+    attr_accessor :version_inventory
+
+    # @return [SignatureCatalog] The signature catalog, used to specify source paths (in :reconstructor mode),
+    #   or to filter the version inventory (in :depositor mode)
+    attr_accessor :signature_catalog
+
+    # @return [Pathname] The location of the Bagit bag to be created
+    attr_accessor :bag_pathname
+
+    # @return [FileInventory] The actual inventory of the files to be packaged (derived from @version_inventory in {#fill_bag})
+    attr_accessor :bag_inventory
+
+    # @return [Symbol] The operational mode controlling what gets bagged {#fill_bag}
+    #   and the full path of source files {#fill_payload}
+    attr_accessor :package_mode
+
+    # @return [void] Delete any existing bag data and re-initialize the bag directory
+    def reset_bag
+      delete_bag
+      delete_tarfile
+      create_bagit_txt
+    end
+
+    # @api internal
+    # @return [void] Generate the bagit.txt tag file
+    def create_bagit_txt()
+      @bag_pathname.mkpath
+      @bag_pathname.join("bagit.txt").open('w') do |f|
+        f.puts "Tag-File-Character-Encoding: UTF-8"
+        f.puts "BagIt-Version: 0.97"
+      end
+    end
+
+    # @return [NilClass] Delete the bagit files
+    def delete_bag()
+      # make sure this looks like a bag before deleting
+      if @bag_pathname.join('bagit.txt').exist?
+        if @bag_pathname.join('data').exist?
+          @bag_pathname.rmtree
+        else
+          @bag_pathname.children.each {|file| file.delete}
+          @bag_pathname.rmdir
+        end
+      end
+      nil
+    end
+
+    # @param tar_pathname [Pathname] The location of the tar file (default is based on bag location)
+    def delete_tarfile()
+      bag_name = @bag_pathname.basename
+      bag_parent = @bag_pathname.parent
+      tar_pathname = bag_parent.join("#{bag_name}.tar")
+      tar_pathname.delete if tar_pathname.exist?
+    end
+
+    # @api external
+    # @param package_mode [Symbol] The operational mode controlling what gets bagged and the full path of source files (Bagger#fill_payload)
+    # @param source_base_pathname [Pathname] The home location of the source files
+    # @return [Bagger] Perform all the operations required to fill the bag payload, write the manifests and tagfiles, and checksum the tagfiles
+    # @example {include:file:spec/features/storage/deposit_spec.rb}
+    def fill_bag(package_mode, source_base_pathname)
+      create_bag_inventory(package_mode)
+      fill_payload(source_base_pathname)
+      create_tagfiles
+      self
+    end
+
+    # @api external
+    # @param package_mode [Symbol] The operational mode controlling what gets bagged and the full path of source files (Bagger#fill_payload)
+    # @return [FileInventory] Create, write, and return the inventory of the files that will become the payload
+    def create_bag_inventory(package_mode)
+      @package_mode = package_mode
+      @bag_pathname.mkpath
+      case package_mode
+        when :depositor
+          @version_inventory.write_xml_file(@bag_pathname, 'version')
+          @bag_inventory = @signature_catalog.version_additions(@version_inventory)
+          @bag_inventory.write_xml_file(@bag_pathname, 'additions')
+        when :reconstructor
+          @bag_inventory = @version_inventory
+          @bag_inventory.write_xml_file(@bag_pathname, 'version')
+      end
+      @bag_inventory
+    end
+
+    # @api internal
+    # @param source_base_pathname [Pathname] The home location of the source files
+    # @return [void] Fill in the bag's data folder with copies of all files to be packaged for delivery.
+    # This method uses Unix hard links in order to greatly speed up the process.
+    # Hard links, however, require that the target bag must be created within the same filesystem as the source files
+    def fill_payload(source_base_pathname)
+      @bag_inventory.groups.each do |group|
+        group_id = group.group_id
+        case @package_mode
+          when :depositor
+            deposit_group(group_id, source_base_pathname.join(group_id))
+          when :reconstructor
+            reconstuct_group(group_id, source_base_pathname)
+        end
+      end
+    end
+
+    # @param group_id [String] The name of the data group being copied to the bag
+    # @param source_dir [Pathname] The location from which files should be copied
+    # @return [Boolean] Copy all the files listed in the group inventory to the bag.
+    #    Return true if successful or nil if the group was not found in the inventory
+    def deposit_group(group_id, source_dir)
+      group = @bag_inventory.group(group_id)
+      return nil? if group.nil? or group.files.empty?
+      target_dir = @bag_pathname.join('data',group_id)
+      group.path_list.each do |relative_path|
+        source = source_dir.join(relative_path)
+        target = target_dir.join(relative_path)
+        target.parent.mkpath
+        FileUtils.symlink source, target
+      end
+      true
+    end
+
+    # @param group_id [String] The name of the data group being copied to the bag
+    # @param storage_object_dir [Pathname] The home location of the object store from which files should be copied
+    # @return [Boolean] Copy all the files listed in the group inventory to the bag.
+    #    Return true if successful or nil if the group was not found in the inventory
+    def reconstuct_group(group_id, storage_object_dir)
+      group = @bag_inventory.group(group_id)
+      return nil? if group.nil? or group.files.empty?
+      target_dir = @bag_pathname.join('data',group_id)
+      group.files.each do |file|
+        catalog_entry = @signature_catalog.signature_hash[file.signature]
+        source = storage_object_dir.join(catalog_entry.storage_path)
+        file.instances.each do |instance|
+          target = target_dir.join(instance.path)
+          target.parent.mkpath
+          FileUtils.symlink source, target
+        end
+      end
+      true
+    end
+
+    # @return [Boolean] create BagIt manifests and tag files.  Return true if successful
+    def create_tagfiles
+      create_payload_manifests
+      create_bag_info_txt
+      create_bagit_txt
+      create_tagfile_manifests
+      true
+    end
+
+    # @api internal
+    # @return [void] Using the checksum information from the inventory, create BagIt manifest files for the payload
+    def create_payload_manifests
+      manifest_pathname = Hash.new
+      manifest_file = Hash.new
+      manifest_types =  [:md5, :sha1, :sha256]
+      manifest_types.each do |type|
+        manifest_pathname[type] = @bag_pathname.join("manifest-#{type.to_s}.txt")
+        manifest_file[type] = manifest_pathname[type].open('w')
+      end
+      @bag_inventory.groups.each do |group|
+        group.files.each do |file|
+          fixity = file.signature.fixity
+          file.instances.each do |instance|
+            data_path = File.join('data', group.group_id, instance.path)
+            manifest_types.each do |type|
+              manifest_file[type].puts("#{fixity[type]} #{data_path}") if fixity[type]
+            end
+          end
+        end
+      end
+    ensure
+      manifest_types.each do |type|
+        if manifest_file[type]
+          manifest_file[type].close
+          manifest_pathname[type].delete if
+              manifest_pathname[type].exist? and manifest_pathname[type].size == 0
+        end
+      end
+    end
+
+    # @api internal
+    # @return [void] Generate the bag-info.txt tag file
+    def create_bag_info_txt
+      @bag_pathname.join("bag-info.txt").open('w') do |f|
+        f.puts "External-Identifier: #{@bag_inventory.package_id}"
+        f.puts "Payload-Oxum: #{@bag_inventory.byte_count}.#{@bag_inventory.file_count}"
+        f.puts "Bag-Size: #{@bag_inventory.human_size}"
+      end
+    end
+
+    # @api internal
+    # @return [void] create BagIt tag manifest files containing checksums for all files in the bag's root directory
+    def create_tagfile_manifests()
+      manifest_pathname = Hash.new
+      manifest_file = Hash.new
+      manifest_types =  [:md5, :sha1, :sha256]
+      manifest_types.each do |type|
+        manifest_pathname[type] = @bag_pathname.join("tagmanifest-#{type.to_s}.txt")
+        manifest_file[type] = manifest_pathname[type].open('w')
+      end
+      @bag_pathname.children.each do |file|
+        unless file.directory? || file.basename.to_s[0, 11] == 'tagmanifest'
+          signature = FileSignature.new.signature_from_file(file)
+          fixity = signature.fixity
+          manifest_types.each do |type|
+            manifest_file[type].puts("#{fixity[type]} #{file.basename}") if fixity[type]
+          end
+        end
+      end
+    ensure
+      manifest_types.each do |type|
+        if manifest_file[type]
+          manifest_file[type].close
+          manifest_pathname[type].delete if
+              manifest_pathname[type].exist? and manifest_pathname[type].size == 0
+        end
+      end
+    end
+
+    # @return [Boolean] Create a tar file containing the bag
+    def create_tarfile(tar_pathname=nil)
+      bag_name = @bag_pathname.basename
+      bag_parent = @bag_pathname.parent
+      tar_pathname ||= bag_parent.join("#{bag_name}.tar")
+      tar_cmd="cd '#{bag_parent}'; tar --dereference --force-local -cf  '#{tar_pathname}' '#{bag_name}'"
+      begin
+        shell_execute(tar_cmd)
+      rescue
+        shell_execute(tar_cmd.sub('--force-local',''))
+      end
+      raise "Unable to create tarfile #{tar_pathname}" unless tar_pathname.exist?
+      return true
+
+    end
+
+    # Executes a system command in a subprocess.
+    # The method will return stdout from the command if execution was successful.
+    # The method will raise an exception if if execution fails.
+    # The exception's message will contain the explaination of the failure.
+    # @param [String] command the command to be executed
+    # @return [String] stdout from the command if execution was successful
+    def shell_execute(command)
+      status, stdout, stderr = systemu(command)
+      if (status.exitstatus != 0)
+        raise stderr
+      end
+      return stdout
+    rescue
+      msg = "Command failed to execute: [#{command}] caused by <STDERR = #{stderr.split($/).join('; ')}>"
+      msg << " STDOUT = #{stdout.split($/).join('; ')}" if (stdout && (stdout.length > 0))
+      raise msg
+    end
+
+  end
+
+end

data/lib/moab/config.rb

@@ -0,0 +1,21 @@
+require 'moab'
+
+module Moab
+
+  #class Configuration < Confstruct::Configuration
+  #
+  #  def configure(*args, &block)
+  #    super(*args, &block)
+  #
+  #    # Whatever you want to do after configuration
+  #    # Something.initialize(self.repository_home)
+  #  end
+  #end
+
+  # @return [Confstruct::Configuration] the configuration data
+  Config = Confstruct::Configuration.new do
+      repository_home  nil
+      path_method :druid_tree
+  end
+
+end

data/lib/moab/exceptions.rb

@@ -0,0 +1,18 @@
+module Moab
+  class ObjectNotFoundException < RuntimeError
+
+  end
+
+  class FileNotFoundException < RuntimeError
+
+  end
+
+  class InvalidMetadataException < RuntimeError
+
+  end
+
+  class ValidationException < RuntimeError
+
+  end
+
+end

data/lib/moab/file_group.rb

@@ -0,0 +1,244 @@
+require 'moab'
+
+module Moab
+
+  # A container for a standard subset of a digital objects {FileManifestation} objects
+  # Used to segregate depositor content from repository metadata files
+  # This is a child element of {FileInventory}, which contains a full example
+  #
+  # ====Data Model
+  # * {FileInventory} = container for recording information about a collection of related files
+  #   * <b>{FileGroup} [1..*] = subset allow segregation of content and metadata files</b>
+  #     * {FileManifestation} [1..*] = snapshot of a file's filesystem characteristics
+  #       * {FileSignature} [1] = file fixity information
+  #       * {FileInstance} [1..*] = filepath and timestamp of any physical file having that signature
+  #
+  # @note Copyright (c) 2012 by The Board of Trustees of the Leland Stanford Junior University.
+  #   All rights reserved.  See {file:LICENSE.rdoc} for details.
+  class FileGroup < Serializable
+
+    include HappyMapper
+
+    # The name of the XML element used to serialize this objects data
+    tag 'fileGroup'
+
+    # (see Serializable#initialize)
+    def initialize(opts={})
+      @signature_hash = OrderedHash.new
+      @data_source = ""
+      super(opts)
+    end
+
+    # @attribute
+    # @return [String] The name of the file group
+    attribute :group_id, String, :tag => 'groupId', :key => true
+
+    # @attribute
+    # @return [String] The directory location or other source of this groups file data
+    attribute :data_source, String, :tag => 'dataSource'
+
+    # @attribute
+    # @return [Integer] The total number of data files (dynamically calculated)
+    attribute :file_count, Integer, :tag => 'fileCount', :on_save => Proc.new {|i| i.to_s}
+
+    def file_count
+      files.inject(0) { |sum, manifestation| sum + manifestation.file_count }
+    end
+
+    # @attribute
+    # @return [Integer] The total size (in bytes) of all data files (dynamically calculated)
+    attribute :byte_count, Integer, :tag => 'byteCount', :on_save => Proc.new {|i| i.to_s}
+
+    def byte_count
+      files.inject(0) { |sum, manifestation| sum + manifestation.byte_count }
+    end
+
+    # @attribute
+    # @return [Integer] The total disk usage (in 1 kB blocks) of all data files (estimating du -k result) (dynamically calculated)
+    attribute :block_count, Integer, :tag => 'blockCount', :on_save => Proc.new {|i| i.to_s}
+
+    def block_count
+      files.inject(0) { |sum, manifestation| sum + manifestation.block_count }
+    end
+
+    # @return [Array<String>] The data fields to include in summary reports
+    def summary_fields
+      %w{group_id file_count byte_count block_count}
+    end
+
+
+    # @attribute
+    # @return [Array<FileManifestation>] The set of files comprising the group
+    has_many :files, FileManifestation, :tag => 'file'
+
+    def files
+      @signature_hash.values
+    end
+
+    # @return [OrderedHash<FileSignature, FileManifestation>] The actual in-memory store for the collection
+    #   of {FileManifestation} objects that are contained in this file group.
+    attr_accessor :signature_hash
+
+    # @api internal
+    # @return [OrderedHash<String,FileSignature>] An index of file paths,
+    #   used to test for existence of a filename in this file group
+    def path_hash
+      path_hash = OrderedHash.new
+      @signature_hash.each do |signature,manifestation|
+        manifestation.instances.each do |instance|
+          path_hash[instance.path] = signature
+        end
+      end
+      path_hash
+    end
+
+    # @return [Array<String>] The list of file paths in this group
+    def path_list
+      files.collect{|file| file.instances.collect{|instance| instance.path}}.flatten
+    end
+
+    # @api internal
+    # @param signature_subset [Array<FileSignature>] The signatures used to select the entries to return
+    # @return [OrderedHash<String,FileSignature>] A pathname,signature hash containing a subset of the filenames in this file group
+    def path_hash_subset(signature_subset)
+      path_hash = OrderedHash.new
+      signature_subset.each do |signature|
+        manifestation = @signature_hash[signature]
+        manifestation.instances.each do |instance|
+          path_hash[instance.path] = signature
+        end
+      end
+      path_hash
+    end
+
+    # @param manifestiation_array [Array<FileManifestation>] The collection of {FileManifestation} objects
+    #    that are to be added to this file group.  Used by HappyMapper when deserializing a {FileInventory} file
+    # Add the array of {FileManifestation} objects to this file group.
+    def files=(manifestiation_array)
+      manifestiation_array.each do |manifestiation|
+        add_file(manifestiation)
+     end
+    end
+
+    # @api internal
+    # @param manifestation [FileManifestation] The file manifestation to be added
+    # @return [void] Add a single {FileManifestation} object to this group
+    def add_file(manifestation)
+      manifestation.instances.each do |instance|
+        add_file_instance(manifestation.signature, instance)
+      end
+    end
+
+    # @api internal
+    # @param signature [FileSignature] The signature of the file instance to be added
+    # @param instance [FileInstance] The pathname and datetime of the file instance to be added
+    # @return [void] Add a single {FileSignature},{FileInstance} key/value pair to this group.
+    #   Data is actually stored in the {#signature_hash}
+    def add_file_instance(signature,instance)
+      if @signature_hash.has_key?(signature)
+        manifestation = @signature_hash[signature]
+      else
+        manifestation = FileManifestation.new
+        manifestation.signature = signature
+        @signature_hash[signature] = manifestation
+      end
+      manifestation.instances << instance
+    end
+
+    # @param path [String] The path of the file to be removed
+    # @return [void] Remove a file from the inventory
+    # for example, the manifest inventory does not contain a file entry for itself
+    def remove_file_having_path(path)
+      signature = self.path_hash[path]
+      @signature_hash.delete(signature)
+    end
+
+    # @return [Pathname] The full path used as the basis of the relative paths reported
+    #   in {FileInstance} objects that are children of the {FileManifestation} objects contained in this file group
+    attr_accessor :base_directory
+
+    def base_directory=(basepath)
+      @base_directory = Pathname.new(basepath).expand_path
+    end
+
+    # @api internal
+    # @param pathname [Pathname] The file path to be tested
+    # @return [Boolean] Test whether the given path is contained within the {#base_directory}
+    def is_descendent_of_base?(pathname)
+      raise("base_directory has not been set") if @base_directory.nil?
+      is_descendent = false
+      pathname.expand_path.ascend {|ancestor| is_descendent ||= (ancestor == @base_directory)}
+      raise("#{pathname} is not a descendent of #{@base_directory}") unless is_descendent
+      is_descendent
+    end
+
+    # @param  directory [Pathame,String] The directory whose children are to be added to the file group
+    # @param signatures_from_bag [Hash<Pathname,Signature>] The fixity data already calculated for the files
+    # @param recursive [Boolean] if true, descend into child directories
+    # @return [FileGroup] Harvest a directory (using digest hash for fixity data) and add all files to the file group
+    def group_from_bagit_subdir(directory, signatures_from_bag, recursive=true)
+      @signatures_from_bag = signatures_from_bag
+      group_from_directory(directory, recursive)
+    end
+
+    # @api internal
+    # @param directory [Pathname,String] The location of the files to harvest
+    # @param recursive [Boolean] if true, descend into child directories
+    # @return [FileGroup] Harvest a directory and add all files to the file group
+    def group_from_directory(directory, recursive=true)
+      self.base_directory = directory
+      @data_source = @base_directory.to_s
+      harvest_directory(directory, recursive)
+      self
+    rescue Exception # Errno::ENOENT
+      @data_source = directory.to_s
+      self
+    end
+
+    # @api internal
+    # @param path [Pathname,String] pathname of the directory to be harvested
+    # @param recursive [Boolean] if true, also harvest subdirectories
+    # @param validated [Boolean] if true, path is verified to be descendant of (#base_directory)
+    # @return [void]  Traverse a directory tree and add all files to the file group
+    #   Note that unlike Find.find and Dir.glob, Pathname passes through symbolic links
+    # @see http://stackoverflow.com/questions/3974087/how-to-make-rubys-find-find-follow-symlinks
+    # @see http://stackoverflow.com/questions/357754/can-i-traverse-symlinked-directories-in-ruby-with-a-glob
+    def harvest_directory(path, recursive, validated=nil)
+      pathname=Pathname.new(path).expand_path
+      validated ||= is_descendent_of_base?(pathname)
+      pathname.children.sort.each do |child|
+        if child.basename.to_s == ".DS_Store"
+          next
+        elsif child.directory?
+          harvest_directory(child,recursive, validated) if recursive
+        else
+          add_physical_file(child, validated)
+        end
+      end
+      nil
+    end
+
+    # @api internal
+    # @param pathname [Pathname, String] The location of the file to be added
+    # @param validated [Boolean] if true, path is verified to be descendant of (#base_directory)
+    # @return [void] Add a single physical file's data to the array of files in this group.
+    #   If fixity data was supplied in bag manifests, then utilize that data.
+    def add_physical_file(pathname, validated=nil)
+      pathname=Pathname.new(pathname).expand_path
+      validated ||= is_descendent_of_base?(pathname)
+      instance = FileInstance.new.instance_from_file(pathname, @base_directory)
+      if @signatures_from_bag && @signatures_from_bag[pathname]
+        signature = @signatures_from_bag[pathname]
+        unless signature.complete?
+          signature = signature.normalized_signature(pathname)
+        end
+      else
+        signature = FileSignature.new.signature_from_file(pathname)
+      end
+      add_file_instance(signature,instance)
+    end
+
+  end
+
+end
+