moab-versioning 1.3.0

data/lib/moab/storage_repository.rb

@@ -0,0 +1,57 @@
+require 'moab'
+
+module Moab
+
+  # A class to represent the SDR repository store
+  #
+  # ====Data Model
+  # * <b>{StorageRepository} = represents a digital object repository storage node</b>
+  #   * {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
+  #       * {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.
+  class StorageRepository
+
+   # @return [Pathname] The location of the root directory of the repository storage node
+    def repository_home
+      Pathname.new(Moab::Config.repository_home)
+    end
+
+    # @param object_id [String] The identifier of the digital object whose version is desired
+    # @return [StorageObject] The representation of the desired object storage directory
+    def storage_object(object_id, create=false)
+      object_pathname = storage_object_pathname(object_id)
+      if object_pathname.exist?
+        StorageObject.new(object_id, object_pathname)
+      elsif create
+        object_pathname.mkpath
+        StorageObject.new(object_id, object_pathname)
+      else
+        raise Moab::ObjectNotFoundException, "No object found for #{object_id} at #{object_pathname}"
+      end
+    end
+
+    # @param object_id [String] The identifier of the digital object whose version is desired
+    # @return [Pathname] The location of the desired object's home directory (default=pairtree)
+    def storage_object_pathname(object_id)
+      #todo This method should be customized, or overridden in a subclass
+      # for a more sophisticated pairtree implementation see https://github.com/microservices/pairtree
+      path_segments = object_id.scan(/..?/) << object_id
+      object_path = path_segments.join(File::SEPARATOR).gsub(/:/,'_')
+      repository_home.join(object_path)
+    end
+
+    # @param druid [String] The object identifier
+    # @return [void] transfer the object to the preservation repository
+    def store_new_object_version(druid, bag_pathname )
+      storage_object = self.storage_object(druid, create=true)
+      new_version = storage_object.ingest_bag(bag_pathname)
+      new_version
+    end
+
+  end
+
+end

data/lib/moab/storage_services.rb

@@ -0,0 +1,104 @@
+require 'moab'
+
+module Moab
+
+  # An interface class to support access to SDR storage via a RESTful server
+  #
+  # ====Data Model
+  # * {StorageRepository} = represents a digital object repository storage node
+  #   * <b>{StorageServices} = supports application layer access to the repository's objects, data, and metadata</b>
+  #   * {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
+  #       * {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.
+  class StorageServices
+
+    # @return [StorageRepository] an instance of the interface to SDR storage
+    @@repository = Moab::StorageRepository.new
+
+    # @param object_id [String] The digital object identifier of the object
+    # @return [String] the location of the storage object
+    def self.object_path(object_id)
+      @@repository.storage_object(object_id).object_pathname.to_s
+    end
+
+    # @param object_id [String] The digital object identifier of the object
+    # @param [Integer] version_id The ID of the version, if nil use latest version
+    # @return [String] the location of the storage object version
+    def self.object_version_path(object_id,version_id=nil)
+      @@repository.storage_object(object_id).find_object_version(version_id).version_pathname.to_s
+    end
+
+    # @param object_id [String] The digital object identifier
+    # @return [Integer] The version number of the currently highest version
+    def self.current_version(object_id)
+      @@repository.storage_object(object_id).current_version_id
+    end
+
+    # @param [String] object_id The digital object identifier of the object
+    # @return [Pathname] Pathname object containing the full path for the specified file
+    def self.version_metadata(object_id)
+      self.retrieve_file('metadata', 'versionMetadata.xml', object_id)
+    end
+
+    # @param [String] object_id The digital object identifier of the object
+    # @param [Integer] version_id The ID of the version, if nil use latest version
+    # @return [FileInventory] the file inventory for the specified object version
+    def self.retrieve_file_group(file_category, object_id, version_id=nil)
+      storage_object_version = @@repository.storage_object(object_id).find_object_version(version_id)
+      if file_category =~ /manifest/
+        inventory_type = file_category = 'manifests'
+      else
+        inventory_type = 'version'
+      end
+      inventory = storage_object_version.file_inventory(inventory_type)
+      inventory.group(file_category)
+    end
+
+    # @param [String] file_category The category of file ('content', 'metdata', or 'manifest')
+    # @param [String] file_id The name of the file (path relative to base directory)
+    # @param [String] object_id The digital object identifier of the object
+    # @param [Integer] version_id The ID of the version, if nil use latest version
+    # @return [Pathname] Pathname object containing the full path for the specified file
+    def self.retrieve_file(file_category, file_id, object_id, version_id=nil)
+      storage_object_version = @@repository.storage_object(object_id).find_object_version(version_id)
+      file_pathname = storage_object_version.find_filepath(file_category, file_id)
+    end
+
+    # @param [String] file_category The category of file ('content', 'metdata', or 'manifest')
+    # @param [FileSignature] file_signature The signature of the file
+    # @param [String] object_id The digital object identifier of the object
+    # @param [Integer] version_id The ID of the version, if nil use latest version
+    # @return [Pathname] Pathname object containing the full path for the specified file
+    def self.retrieve_file_using_signature(file_category, file_signature, object_id, version_id=nil)
+      storage_object_version = @@repository.storage_object(object_id).find_object_version(version_id)
+      file_pathname = storage_object_version.find_filepath_using_signature(file_category, file_signature)
+    end
+
+    # @param [String] file_category The category of file ('content', 'metdata', or 'manifest')
+    # @param [String] file_id The name of the file (path relative to base directory)
+    # @param [String] object_id The digital object identifier of the object
+    # @param [Integer] version_id The ID of the version, if nil use latest version
+    # @return [FileSignature] The signature of the file
+    def self.retrieve_file_signature(file_category, file_id, object_id, version_id=nil)
+      storage_object_version = @@repository.storage_object(object_id).find_object_version(version_id)
+      file_pathname = storage_object_version.find_signature(file_category, file_id)
+    end
+
+    # @param [String] object_id The digital object identifier of the object
+    # @param [Object] base_version_id The identifier of the base version to be compared
+    # @param [Object] compare_version_id The identifier of the version to be compared to the base version
+    # @return [FileInventoryDifference] The report of the version differences
+    def self.version_differences(object_id, base_version_id,compare_version_id)
+      base_version = @@repository.storage_object(object_id).storage_object_version(base_version_id)
+      compare_version = @@repository.storage_object(object_id).storage_object_version(compare_version_id)
+      base_inventory=base_version.file_inventory('version')
+      compare_inventory=compare_version.file_inventory('version')
+      FileInventoryDifference.new.compare(base_inventory,compare_inventory)
+    end
+
+  end
+
+end

data/lib/moab/verification_result.rb

@@ -0,0 +1,83 @@
+require 'moab'
+
+module Moab
+
+  class VerificationResult
+
+    # @return [String] The name of the entity that was verified
+    attr_accessor :entity
+
+    # @return [Boolean] The true/false outcome of the verification
+    attr_accessor :verified
+
+    # @return [Hash] The details of the comparisons that were made
+    attr_accessor :details
+
+    # @return [Array<VerificationResult>] The subentities, if any, on which this verification is based
+    attr_accessor :subentities
+
+    # @param entity [Object] The name of the entity being verified
+    def initialize(entity)
+      @entity = entity
+      @verified = false
+      @details = nil
+      @subentities = Array.new
+    end
+
+    # @param entity [Symbol] The name of the entity being verified
+    # @param expected [Object] The expected value
+    # @param found [Object] The found value
+    # @return [VerificationResult] The result of comparing the expected and found values
+    def self.verify_value(entity, expected, found)
+      result = VerificationResult.new(entity.to_s)
+      result.verified = (expected == found)
+      result.details = {'expected' => expected, 'found' => found}
+      result
+    end
+
+    # @param entity [Symbol] The name of the entity being verified
+    # @param expression [Object] The expression that will be evaluated as true or false
+    # @param details [Object] optional details that could be reported
+    # @return [VerificationResult] The result of evaluating the expression
+    def self.verify_truth(entity,expression,details=nil)
+      result = VerificationResult.new(entity.to_s)
+      result.verified = !(expression.nil? or (expression == false))
+      result.details = details
+      result
+    end
+
+    # @param verbose [Boolean] If true, always provide all details of the verification
+    # @return [String] The verification result serialized to JSON
+    def to_json(verbose=false)
+      JSON.pretty_generate(to_hash(verbose))
+    end
+
+    # @param verbose [Boolean] If true, always provide all details of the verification
+    # @param level [Integer] Used to test the depth of recursion
+    # @return [OrderedHash] The verification result serialized to a hash
+    def to_hash(verbose=false,level=0)
+      hash = OrderedHash.new
+      hash['verified'] = @verified
+      if (verbose or @verified == false)
+        hash['details'] = @details ? @details : subentities_to_hash(verbose,level)
+      end
+      if level > 0
+        hash
+      else
+        {@entity => hash}
+      end
+    end
+
+    # @param verbose [Boolean] If true, always provide all details of the verification
+    # @param level [Integer] Used to increment the depth of recursion
+    # @return [OrderedHash] The verification result of subentities serialized to a hash
+    def subentities_to_hash(verbose,level)
+      hash = OrderedHash.new
+      @subentities.each do |s|
+       hash[s.entity] = s.to_hash(verbose, level+1)
+      end
+      hash
+    end
+
+  end
+end

data/lib/moab/version_metadata.rb

@@ -0,0 +1,38 @@
+require 'moab'
+
+module Moab
+
+  # The descriptive information about a digital object's collection of versions
+  #
+  # ====Data Model
+  # * <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
+  #
+  # @example {include:file:spec/fixtures/data/jq937jp0017/v3/metadata/versionMetadata.xml}
+  # @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 VersionMetadata < Manifest
+
+    include HappyMapper
+
+    # The name of the XML element used to serialize this objects data
+    tag 'versionMetadata'
+
+    # (see Serializable#initialize)
+    def initialize(opts={})
+      @versions = Array.new
+      super(opts)
+    end
+
+    # @attribute
+    # @return [String] The digital object identifier
+    attribute :digital_object_id, String, :tag => 'objectId'
+
+    # @attribute
+    # @return [Array<VersionMetadataEntry>] An array of version metadata entries, one per version
+    has_many :versions, VersionMetadataEntry, :tag => 'version'
+
+  end
+
+end

data/lib/moab/version_metadata_entry.rb

@@ -0,0 +1,64 @@
+  require 'moab'
+
+module Moab
+
+  # The descriptive attributes of a digital object version.
+  #
+  # ====Data Model
+  # * {VersionMetadata} = descriptive information about a digital object's versions
+  #   * <b>{VersionMetadataEntry} [1..*] = attributes of a digital object version</b>
+  #     * {VersionMetadataEvent} [1..*] = object version lifecycle events with timestamps
+  #
+  # @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 VersionMetadataEntry < Serializable
+
+    include HappyMapper
+
+    # The name of the XML element used to serialize this objects data
+    tag 'version'
+
+    # (see Serializable#initialize)
+    def initialize(opts={})
+      @events = Array.new
+      super(opts)
+    end
+
+    # @attribute
+    # @return [Integer] The object version number (A sequential integer)
+    attribute :version_id, Integer, :tag => 'versionId', :key => true, :on_save => Proc.new {|n| n.to_s}
+
+    # @attribute
+    # @return [String] "an external version label that increments the most significant digit for major revisions,
+    # second digit for minor revisions, and third for admin? e.g., 1.0, 1.1, 2.0, 2.0.1 etc.
+    # This should be dynamically derivable across the set of versions
+    attribute :label, String
+
+    # @attribute
+    # @return [String] "major|minor|admin"
+    attribute :significance, String
+
+    # @attribute
+    # @return [String] A free text external description of why the version was created
+    element :description, String
+
+    # @attribute
+    # @return [String] An internal annotation summarizing the changes (optional)
+    element :note, String
+
+    # @attribute
+    # @return [FileGroupDifference] Summary of content file differences since previous version
+    element :content_changes, FileGroupDifference, :tag => 'fileGroupDifference'
+
+    # @attribute
+    # @return [FileGroupDifference]   Summary of metadata file differences since previous version
+    element :metadata_changes, FileGroupDifference, :tag => 'fileGroupDifference'
+
+    # @attribute
+    # @return [Array<VersionMetadataEvent>] Array of events with timestamps that track lifecycle stages
+    has_many :events, VersionMetadataEvent, :tag => 'event'
+
+  end
+
+end
+

data/lib/moab/version_metadata_event.rb

@@ -0,0 +1,47 @@
+require 'moab'
+
+module Moab
+
+  # A container element to record object version lifecycle events with timestamps
+  #
+  # ====Data Model
+  # * {VersionMetadata} = descriptive information about a digital object's versions
+  #   * {VersionMetadataEntry} [1..*] = attributes of a digital object version
+  #     * <b>{VersionMetadataEvent} [1..*] = object version lifecycle events with timestamps</b>
+  #
+  # @see VersionMetadata
+  # @see VersionMetadataEntry
+  # @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 VersionMetadataEvent < Serializable
+
+    include HappyMapper
+
+    # The name of the XML element used to serialize this objects data
+    tag 'event'
+
+    # (see Serializable#initialize)
+    def initialize(opts={})
+      super(opts)
+    end
+
+    # @attribute
+    # @return [String] The type of event
+    attribute :type, String
+
+
+    # @attribute
+    # @return [Time] The date and time of an event
+    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
+
+  end
+
+end

data/lib/moab_stanford.rb

@@ -0,0 +1,18 @@
+require 'moab'
+include Moab
+require 'stanford/content_inventory'
+require 'stanford/dor_metadata'
+require 'stanford/storage_repository'
+require 'stanford/storage_services'
+require 'stanford/active_fedora_object'
+
+# Stanford is a module that isolates classes specific to the Stanford Digital Repository
+#
+# ====Data Model
+# * <b>{DorMetadata} = utility methods for interfacing with Stanford metadata files (esp contentMetadata)</b>
+#   * {ActiveFedoraObject} [1..*] = utility for extracting content or other information from a Fedora Instance
+#
+# @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 Stanford
+end

data/lib/monkey_patches.rb

@@ -0,0 +1,65 @@
+require 'time'
+
+# monkey-patch to fix JSON_pure
+# @see http://prettystatemachine.blogspot.com/2010/09/typeerrors-in-tojson-make-me-briefly.html
+#noinspection RubyUnusedLocalVariable
+class Fixnum
+  # @return [String] The string value of the number
+  def to_json(options = nil)
+    to_s
+  end
+end
+
+# Make the default output from a Time variable be formatted in ISO 8601 format
+class Time
+  # @return [String] The datetime in ISO 8601 format
+  def to_s
+    self.utc.iso8601
+  end
+
+  # @param datetime [Time,String,Nil] The input datetime
+  # @return [void] Store the input datetime as a Time object
+  def self.input(datetime)
+    case datetime
+      when nil
+        nil
+      when String
+        Time.parse(datetime)
+      when Time
+        datetime
+      else
+        raise "unknown time format #{datetime.inspect}"
+    end
+  end
+
+  # @param datetime [Time,String,Nil] The datetime value to output
+  # @return [String] Format the datetime into a ISO 8601 formatted string
+  def self.output(datetime)
+    case datetime
+      when nil
+        nil
+      when String
+        Time.parse(datetime).utc.iso8601
+      when Time
+        datetime.utc.iso8601
+      else
+        raise "unknown time format #{datetime.inspect}"
+    end
+  end
+
+end
+
+# Add methods to Array so that one attribute of a class can be treated as a unique key
+class Array
+  # @return [Array<Object>] An array containing the key fields from a collection of objects
+  def keys
+    self.collect { |e| e.key }
+  end
+
+  # @param key [Object] The key value to search for
+  # @return [Object] The object from the array that has the specified key value
+  def keyfind(key)
+    self.each { |e| return e if key == e.key }
+    nil
+  end
+end