moab-versioning 1.3.0

data/lib/moab/file_group_difference.rb

@@ -0,0 +1,336 @@
+require 'moab'
+
+module Moab
+
+  # Performs analysis and reports the differences between two matching {FileGroup} objects.
+  # The descending elements of the report hold a detailed breakdown of file-level differences, organized by change type.
+  # This stanza is a child element of {FileInventoryDifference}, the documentation of which contains a full example.
+  #
+  # In order to determine the detailed nature of the differences that are present between the two manifests,
+  # this algorithm first compares the sets of file signatures present in the groups being compared,
+  # then uses the result of that operation for subsequent analysis of filename correspondences.
+  #
+  # For the first step, a Ruby Hash is extracted from each of the of the two groups, with an array of
+  # {FileSignature} object used as hash keys, and the corresponding {FileInstance} arrays as the hash values.
+  # The set of keys from the basis hash can be compared against the keys from the other hash using {Array} operators:
+  # * <i>matching</i>  = basis_array & other_array
+  # * <i>basis_only</i> = basis_array - other_array
+  # * <i>other_only</i> = other_array - basis_array
+  #
+  # For the second step of the comparison, the matching and non-matching sets of hash entries
+  # are further categorized as follows:
+  # * <i>identical</i> = signature and file path is the same in both basis and other file group
+  # * <i>renamed</i> = signature is unchanged, but the path has moved
+  # * <i>modified</i> = path is present in both groups, but the signature has changed
+  # * <i>deleted</i> = signature and path are only in the basis inventory
+  # * <i>added</i> = signature and path are only in the other inventor
+  #
+  # ====Data Model
+  # * {FileInventoryDifference} = compares two {FileInventory} instances based on file signatures and pathnames
+  #   * <b>{FileGroupDifference} [1..*] = performs analysis and reports differences between two matching {FileGroup} objects</b>
+  #     * {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
+  #
+  # @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 FileGroupDifference < Serializable
+    include HappyMapper
+
+    # The name of the XML element used to serialize this objects data
+    tag 'fileGroupDifference'
+
+    # (see Serializable#initialize)
+    def initialize(opts={})
+      @subsets = Array.new
+      super(opts)
+    end
+
+    # @attribute
+    # @return [String] The name of the file group
+    attribute :group_id, String, :tag => 'groupId', :key => true
+
+    # @attribute
+    # @return [Integer] the total number of differences found between the two inventories that were compared  (dynamically calculated)
+    attribute :difference_count, Integer, :tag => 'differenceCount', :on_save => Proc.new { |i| i.to_s }
+
+    def difference_count
+      @renamed + @modified + @deleted +@added
+    end
+
+    # @attribute
+    # @return [Integer] How many files were unchanged
+    attribute :identical, Integer, :on_save => Proc.new { |n| n.to_s }
+
+    # @attribute
+    # @return [Integer] How many files were renamed
+    attribute :renamed, Integer, :on_save => Proc.new { |n| n.to_s }
+
+    # @attribute
+    # @return [Integer] How many files were modified
+    attribute :modified, Integer, :on_save => Proc.new { |n| n.to_s }
+
+    # @attribute
+    # @return [Integer] How many files were deleted
+    attribute :deleted, Integer, :on_save => Proc.new { |n| n.to_s }
+
+    # @attribute
+    # @return [Integer] How many files were added
+    attribute :added, Integer, :on_save => Proc.new { |n| n.to_s }
+
+    # @attribute
+    # @return [Array<FileGroupDifferenceSubset>] A set of Arrays (one for each change type),
+    #    each of which contains an collection of file-level differences having that change type.
+    has_many :subsets, FileGroupDifferenceSubset, :tag => 'subset'
+
+    # @param change [String] the change type to search for
+    # @return [FileGroupDifferenceSubset] Find a specified subset of changes
+    def subset(change)
+      @subsets.find{ |subset| subset.change == change}
+    end
+
+    # @return [Array<String>] The data fields to include in summary reports
+    def summary_fields
+      %w{group_id difference_count identical renamed modified deleted added}
+    end
+
+
+    # @api internal
+    # @return [FileGroupDifference] Clone just this element for inclusion in a versionMetadata structure
+    def summary()
+      FileGroupDifference.new(
+          :group_id => @group_id,
+          :identical => @identical,
+          :renamed => @renamed,
+          :modified => @modified,
+          :deleted => @deleted,
+          :added => @added
+      )
+    end
+
+
+    # @return [Hash<Symbol,Array>] Sets of filenames grouped by change type for use in performing file or metadata operations
+    def file_deltas()
+      # The hash to be returned
+      deltas = Hash.new
+      # Container for a files whose checksums matched across versions, but may have copies removed, added, or renamed
+      copied = Hash.new {|hash, key| hash[key] = {:basis=>Array.new , :other=>Array.new} }
+      # Capture the filename data
+      @subsets.each  do |subset|
+        case subset.change
+          when "added"
+            deltas[:added] = subset.files.collect {|file| file.other_path}
+          when "deleted"
+            deltas[:deleted] = subset.files.collect {|file| file.basis_path}
+          when "modified"
+            deltas[:modified] = subset.files.collect {|file| file.basis_path}
+          when "identical"
+            subset.files.each  do |instance|
+              signature = instance.signatures[0]
+              copied[signature][:basis] << instance.basis_path
+              copied[signature][:other] << instance.basis_path
+            end
+          when "renamed"
+            subset.files.each  do |instance|
+              signature = instance.signatures[0]
+              copied[signature][:basis] << instance.basis_path unless (instance.basis_path.nil? or instance.basis_path.empty?)
+              copied[signature][:other] << instance.other_path unless (instance.other_path.nil? or instance.other_path.empty?)
+            end
+        end
+      end
+      deltas[:copied] = copied.values
+      deltas
+    end
+
+    # @api internal
+    # @param basis_hash [Hash] The first hash being compared
+    # @param other_hash [Hash] The second hash being compared
+    # @return [Array] Compare the keys of two hashes and return the intersection
+    def matching_keys(basis_hash, other_hash)
+      basis_hash.keys & other_hash.keys
+    end
+
+    # @api internal
+    # @param (see #matching_keys)
+    # @return [Array] Compare the keys of two hashes and return the keys unique to the first hash
+    def basis_only_keys(basis_hash, other_hash)
+      basis_hash.keys - other_hash.keys
+    end
+
+    # @api internal
+    # @param (see #matching_keys)
+    # @return [Array] Compare the keys of two hashes and return the keys unique to the second hash
+    def other_only_keys(basis_hash, other_hash)
+      other_hash.keys - basis_hash.keys
+    end
+
+    # @api internal
+    # @param basis_group [FileGroup] The file group that is the basis of the comparison
+    # @param other_group [FileGroup] The file group that is compared against the basis group
+    # @return [FileGroupDifference] Compare two file groups and return a differences report
+    def compare_file_groups(basis_group, other_group)
+      @group_id = basis_group.group_id
+      compare_matching_signatures(basis_group, other_group)
+      compare_non_matching_signatures(basis_group, other_group)
+      self
+    end
+
+    # @api internal
+    # @param (see #compare_file_groups)
+    # @return [void] For signatures that are present in both groups,
+    #   report which file instances are identical or renamed
+    def compare_matching_signatures(basis_group, other_group)
+      matching_signatures = matching_keys(basis_group.signature_hash, other_group.signature_hash)
+      tabulate_unchanged_files(matching_signatures, basis_group.signature_hash, other_group.signature_hash)
+      tabulate_renamed_files(matching_signatures, basis_group.signature_hash, other_group.signature_hash)
+    end
+
+    # @api internal
+    # @param (see #compare_file_groups)
+    # @return [void] For signatures that are present in only one or the other group,
+    #   report which file instances are modified, deleted, or added
+    def compare_non_matching_signatures(basis_group, other_group)
+      basis_only_signatures = basis_only_keys(basis_group.signature_hash, other_group.signature_hash)
+      other_only_signatures = other_only_keys(basis_group.signature_hash, other_group.signature_hash)
+      basis_path_hash = basis_group.path_hash_subset(basis_only_signatures)
+      other_path_hash = other_group.path_hash_subset(other_only_signatures)
+      tabulate_modified_files(basis_path_hash, other_path_hash)
+      tabulate_deleted_files(basis_path_hash, other_path_hash)
+      tabulate_added_files(basis_path_hash, other_path_hash)
+    end
+
+    # @api internal
+    # @param matching_signatures [Array<FileSignature>] The file signature of the file manifestations being compared
+    # @param basis_signature_hash [OrderedHash<FileSignature, FileManifestation>]
+    #   Signature to file path mapping from the file group that is the basis of the comparison
+    # @param other_signature_hash [OrderedHash<FileSignature, FileManifestation>]
+    #   Signature to file path mapping from the file group that is the being compared to the basis group
+    # @return [FileGroupDifferenceSubset]
+    #   Container for reporting the set of file-level differences of type 'identical'
+    def tabulate_unchanged_files(matching_signatures, basis_signature_hash, other_signature_hash)
+      unchanged_files = Array.new
+      matching_signatures.each do |signature|
+        basis_paths = basis_signature_hash[signature].paths
+        other_paths = other_signature_hash[signature].paths
+        matching_paths = basis_paths & other_paths
+        matching_paths.each do |path|
+          fid = FileInstanceDifference.new(:change => 'identical')
+          fid.basis_path = path
+          fid.other_path = "same"
+          fid.signatures << signature
+          unchanged_files << fid
+        end
+      end
+      unchanged_subset = FileGroupDifferenceSubset.new(:change => 'identical')
+      unchanged_subset.files = unchanged_files
+      @subsets << unchanged_subset
+      @identical = unchanged_subset.count
+      unchanged_subset
+    end
+
+
+    # @api internal
+    # @param matching_signatures [Array<FileSignature>] The file signature of the file manifestations being compared
+    # @param basis_signature_hash [OrderedHash<FileSignature, FileManifestation>]
+    #   Signature to file path mapping from the file group that is the basis of the comparison
+    # @param other_signature_hash [OrderedHash<FileSignature, FileManifestation>]
+    #   Signature to file path mapping from the file group that is the being compared to the basis group
+    # @return [FileGroupDifferenceSubset]
+    #   Container for reporting the set of file-level differences of type 'renamed'
+    def tabulate_renamed_files(matching_signatures, basis_signature_hash, other_signature_hash)
+      renamed_files = Array.new
+      matching_signatures.each do |signature|
+        basis_paths = basis_signature_hash[signature].paths
+        other_paths = other_signature_hash[signature].paths
+        basis_only_paths = basis_paths - other_paths
+        other_only_paths = other_paths - basis_paths
+        maxsize = [basis_only_paths.size, other_only_paths.size].max
+        (0..maxsize-1).each do |n|
+          fid = FileInstanceDifference.new(:change => 'renamed')
+          fid.basis_path = basis_only_paths[n]
+          fid.other_path = other_only_paths[n]
+          fid.signatures << signature
+          renamed_files << fid
+        end
+      end
+      renamed_subset = FileGroupDifferenceSubset.new(:change => 'renamed')
+      renamed_subset.files = renamed_files
+      @subsets << renamed_subset
+      @renamed = renamed_subset.count
+      renamed_subset
+    end
+
+
+    # @api internal
+    # @param basis_path_hash [OrderedHash<String,FileSignature>]
+    #   The file paths and associated signatures for manifestations appearing only in the basis group
+    # @param other_path_hash [OrderedHash<String,FileSignature>]
+    #   The file paths and associated signatures for manifestations appearing only in the other group
+    # @return [FileGroupDifferenceSubset]
+    #   Container for reporting the set of file-level differences of type 'modified'
+    def tabulate_modified_files(basis_path_hash, other_path_hash)
+      modified_files = Array.new
+      matching_keys(basis_path_hash, other_path_hash).each do |path|
+        fid = FileInstanceDifference.new(:change => 'modified')
+        fid.basis_path = path
+        fid.other_path = "same"
+        fid.signatures << basis_path_hash[path]
+        fid.signatures << other_path_hash[path]
+        modified_files << fid
+      end
+      modified_subset = FileGroupDifferenceSubset.new(:change => 'modified')
+      modified_subset.files = modified_files
+      @subsets << modified_subset
+      @modified = modified_subset.count
+      modified_subset
+    end
+
+    # @api internal
+    # @param basis_path_hash [OrderedHash<String,FileSignature>]
+    #   The file paths and associated signatures for manifestations appearing only in the basis group
+    # @param other_path_hash [OrderedHash<String,FileSignature>]
+    #   The file paths and associated signatures for manifestations appearing only in the other group
+    # @return [FileGroupDifferenceSubset]
+    #   Container for reporting the set of file-level differences of type 'deleted'
+    def tabulate_deleted_files(basis_path_hash, other_path_hash)
+      deleted_files = Array.new
+      basis_only_keys(basis_path_hash, other_path_hash).each do |path|
+        fid = FileInstanceDifference.new(:change => 'deleted')
+        fid.basis_path = path
+        fid.other_path = ""
+        fid.signatures << basis_path_hash[path]
+        deleted_files << fid
+      end
+      deleted_subset = FileGroupDifferenceSubset.new(:change => 'deleted')
+      deleted_subset.files = deleted_files
+      @subsets << deleted_subset
+      @deleted = deleted_subset.count
+      deleted_subset
+    end
+
+    # @api internal
+    # @param basis_path_hash [OrderedHash<String,FileSignature>]
+    #   The file paths and associated signatures for manifestations appearing only in the basis group
+    # @param other_path_hash [OrderedHash<String,FileSignature>]
+    #   The file paths and associated signatures for manifestations appearing only in the other group
+    # @return [FileGroupDifferenceSubset]
+    #   Container for reporting the set of file-level differences of type 'added'
+    def tabulate_added_files(basis_path_hash, other_path_hash)
+      added_files = Array.new
+      other_only_keys(basis_path_hash, other_path_hash).each do |path|
+        fid = FileInstanceDifference.new(:change => 'added')
+        fid.basis_path = ""
+        fid.other_path = path
+        fid.signatures << other_path_hash[path]
+        added_files << fid
+      end
+      added_subset = FileGroupDifferenceSubset.new(:change => 'added')
+      added_subset.files = added_files
+      @subsets << added_subset
+      @added = added_subset.count
+      added_subset
+    end
+
+  end
+
+end

data/lib/moab/file_group_difference_subset.rb

@@ -0,0 +1,45 @@
+require 'moab'
+
+module Moab
+
+  # A container for reporting a set of file-level differences of the type specified by the change attribute
+  #
+  # ====Data Model
+  # * {FileInventoryDifference} = compares two {FileInventory} instances based on file signatures and pathnames
+  #   * {FileGroupDifference} [1..*] = performs analysis and reports differences between two matching {FileGroup} objects
+  #     * <b>{FileGroupDifferenceSubset} [1..5] = collects a set of file-level differences of a give change type</b>
+  #       * {FileInstanceDifference} [1..*] = contains difference information at the file level
+  #         * {FileSignature} [1..2] = contains the file signature(s) of two file instances being compared
+  #
+  # @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 FileGroupDifferenceSubset < Serializable
+    include HappyMapper
+
+    # The name of the XML element used to serialize this objects data
+    tag 'subset'
+
+    # (see Serializable#initialize)
+    def initialize(opts={})
+      @files = Array.new
+      super(opts)
+    end
+
+    # @attribute
+    # @return [String] The type of change (identical|renamed|modified|deleted|added)
+    attribute :change, String, :key => true
+
+    # @attribute
+    # @return [Integer] How many files were changed
+    attribute :count, Integer, :on_save => Proc.new { |n| n.to_s }
+
+    def count
+      files.size
+    end
+
+    # @attribute
+    # @return [Array<FileInstanceDifference>] The set of file instances having this type of change
+    has_many :files, FileInstanceDifference, :tag=>'file'
+
+  end
+end

data/lib/moab/file_instance.rb

@@ -0,0 +1,82 @@
+require 'moab'
+
+module Moab
+
+  # The file path and last modification date properties of a file
+  #
+  # ====Data Model
+  # * {FileInventory} = container for recording information about a collection of related files
+  #   * {FileGroup} [1..*] = subset allow segregation of content and metadata files
+  #     * {FileManifestation} [1..*] = snapshot of a file's filesystem characteristics
+  #       * {FileSignature} [1] = file fixity information
+  #       * <b>{FileInstance} [1..*] = filepath and timestamp of any physical file having that signature</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 FileInstance < Serializable
+
+    include HappyMapper
+
+    # The name of the XML element used to serialize this objects data
+    tag 'fileInstance'
+
+    # (see Serializable#initialize)
+    def initialize(opts={})
+      super(opts)
+    end
+
+    # @attribute
+    # @return [String] The id is the filename path, relative to the file group's base directory
+    attribute :path, String, :key => true
+
+    # @attribute
+    # @return [Time] gsub(/\n/,' ')
+    attribute :datetime, Time, :on_save => Proc.new {|t| t.to_s}
+
+    def datetime=(event_datetime)
+      @datetime=Time.input(event_datetime)
+    end
+
+    def datetime
+      Time.output(@datetime)
+    end
+
+
+    # @api internal
+    # @param pathname [Pathname] The location of the physical file
+    # @param base_directory [Pathname] The full path used as the basis of the relative paths reported
+    # @return [FileInstance] Returns a file instance containing a physical file's' properties
+    def instance_from_file(pathname, base_directory)
+      @path = pathname.expand_path.relative_path_from(base_directory.expand_path).to_s
+      @datetime = pathname.mtime.iso8601
+      self
+    end
+
+    # @api internal
+    # @param other [FileInstance] The other file instance being compared to this instance
+    # @return [Boolean] Returns true if self and other have the same path.
+    def eql?(other)
+      self.path == other.path
+    end
+
+    # @api internal
+    # (see #eql?)
+    def ==(other)
+      eql?(other)
+    end
+
+    # @api internal
+    # @return [Fixnum] Compute a hash-code for the path string.
+    # Two file instances with the same relative path will have the same hash code (and will compare using eql?).
+    # @note The hash and eql? methods override the methods inherited from Object.
+    #   These methods ensure that instances of this class can be used as Hash keys.  See
+    #   * {http://www.paulbutcher.com/2007/10/navigating-the-equality-maze/}
+    #   * {http://techbot.me/2011/05/ruby-basics-equality-operators-ruby/}
+    #   Also overriden is {#==} so that equality tests in other contexts will also return the expected result.
+    def hash
+      path.hash
+    end
+
+  end
+
+end