moab-versioning 1.3.0

data/lib/stanford/dor_metadata.rb

@@ -0,0 +1,49 @@
+require 'moab_stanford'
+
+module Stanford
+
+  # Stanford-specific utility methods for interfacing with DOR metadata files
+  #
+  # ====Data Model
+  # * <b>{DorMetadata} = utility methods for interfacing with Stanford metadata files (esp contentMetadata)</b>
+  #   * {ContentInventory} [1..1] = utilities for transforming contentMetadata to versionInventory and doing comparsions
+  #   * {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.
+  class DorMetadata
+
+    # @return [String] The digital object identifier (druid)
+    attr_accessor :digital_object_id
+
+    # @return [Integer] \@versionId = The ordinal version number
+    attr_accessor :version_id
+
+    # @param digital_object_id [String] The digital object identifier
+    # @param version_id [Integer] The ordinal version number
+    # @return [Stanford::DorMetadata]
+    def initialize(digital_object_id, version_id=nil)
+      @digital_object_id = digital_object_id
+      @version_id = version_id
+    end
+
+    # @api internal
+    # @param directory [String] The location of the directory to be inventoried
+    # @param version_id (see #initialize)
+    # @return [FileInventory]  Inventory of the files under the specified directory
+    def inventory_from_directory(directory, version_id=nil)
+      version_id ||= @version_id
+      version_inventory = FileInventory.new(:type=>'version',:digital_object_id=>@digital_object_id, :version_id=>version_id)
+      content_metadata = IO.read(File.join(directory,'contentMetadata.xml'))
+      content_group = ContentInventory.new.group_from_cm(content_metadata, 'preserve' )
+      version_inventory.groups << content_group
+      metadata_group = FileGroup.new(:group_id=>'metadata').group_from_directory(directory)
+      version_inventory.groups << metadata_group
+      version_inventory
+    end
+
+
+
+  end
+
+end

data/lib/stanford/storage_repository.rb

@@ -0,0 +1,46 @@
+require 'moab_stanford'
+
+module Stanford
+
+  # A class to represent the SDR repository store
+  #
+  # ====Data Model
+  # * <b>{StorageRepository} = represents a digital object repository storage node</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 StorageRepository < Moab::StorageRepository
+
+    # @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
+    def storage_object_pathname(object_id)
+      case Moab::Config.path_method.to_s
+        when 'druid_tree'
+          repository_home.join(druid_tree(object_id))
+        when 'druid'
+          repository_home.join(object_id.split(/:/)[-1])
+      end
+    end
+
+    # @param object_id [String] The identifier of the digital object whose path is requested
+    # @return [String] the druid tree directory path based on the given object identifier.
+    def druid_tree(object_id)
+      syntax_msg = "Identifier has invalid suri syntax: #{object_id}"
+      raise syntax_msg + "nil or empty" if object_id.to_s.empty?
+      identifier = object_id.split(':')[-1]
+      raise syntax_msg if  identifier.to_s.empty?
+      # The object identifier must be in the SURI format, otherwise an exception is raised:
+      # e.g. druid:aannnaannnn or aannnaannnn
+      # where 'a' is an alphabetic character
+      # where 'n' is a numeric character
+      if identifier =~ /^([a-z]{2})(\d{3})([a-z]{2})(\d{4})$/
+        return File.join( $1, $2, $3, $4, identifier)
+      else
+        raise syntax_msg
+      end
+    end
+
+
+  end
+
+end

data/lib/stanford/storage_services.rb

@@ -0,0 +1,66 @@
+require 'moab_stanford'
+
+module Stanford
+
+  # An interface class to support access to SDR storage via a RESTful server
+  class StorageServices < Moab::StorageServices
+
+    # @return [StorageRepository] an instance of the interface to SDR storage
+    @@repository = Stanford::StorageRepository.new
+
+    # @param new_content_metadata [String] The content metadata to be compared to the base
+    # @param object_id [String] The digital object identifier of the object whose version inventory is the basis of the comparison
+    # @param subset [String] Speciifes which subset of files to list in the inventories extracted from the contentMetadata (all|preserve|publish|shelve)
+    # @param base_version [Integer] The ID of the version whose inventory is the basis of, if nil use latest version
+    # @return [FileInventoryDifference] The report of differences between the content metadata and the specified version
+    def self.compare_cm_to_version(new_content_metadata, object_id, subset, base_version=nil)
+      new_inventory = ContentInventory.new.inventory_from_cm(new_content_metadata, object_id, subset)
+      begin
+        # ObjectNotFoundException is raised if the object does not exist in storage
+        base_version ||= self.current_version(object_id)
+        # FileNotFoundException is raised if object exists but has no contentMetadata file
+        base_cm_pathname = self.retrieve_file('metadata', 'contentMetadata.xml', object_id, base_version)
+        base_inventory = ContentInventory.new.inventory_from_cm(base_cm_pathname.read, object_id, subset, base_version)
+      rescue Moab::ObjectNotFoundException, Moab::FileNotFoundException
+        # Create a skeletal FileInventory object, containing no file entries
+        storage_object = StorageObject.new(object_id, 'dummy')
+        base_version = StorageObjectVersion.new(storage_object,0)
+        base_inventory = base_version.file_inventory('version')
+      end
+      diff = FileInventoryDifference.new.compare(base_inventory, new_inventory)
+      metadata_diff = diff.group_difference('metadata')
+      diff.group_differences.delete(metadata_diff) if metadata_diff
+      diff
+    end
+
+    # @param new_content_metadata [String] The content metadata to be compared to the current signtature catalog
+    # @param object_id [String] The digital object identifier of the object whose signature catalog is to be used
+    # @param version_id [Integer] The ID of the version whose signature catalog is to be used, if nil use latest version
+    # @return [FileInventory] The versionAddtions report showing which files are new or modified in the content metadata
+    def self.cm_version_additions(new_content_metadata, object_id, version_id=nil)
+      new_inventory = ContentInventory.new.inventory_from_cm(new_content_metadata, object_id, 'preserve')
+      begin
+        # ObjectNotFoundException is raised if the object does not exist in storage
+        version_id ||= self.current_version(object_id)
+        storage_object_version = @@repository.storage_object(object_id).find_object_version(version_id)
+        signature_catalog = storage_object_version.signature_catalog
+      rescue Moab::ObjectNotFoundException
+        storage_object = StorageObject.new(object_id, 'dummy')
+        base_version = StorageObjectVersion.new(storage_object,0)
+        signature_catalog = base_version.signature_catalog
+      end
+      signature_catalog.version_additions(new_inventory)
+    end
+
+    # @param object_id [String] The digital object identifier of the object whose contentMetadata is to be remediated
+    # @param version_id [Integer] The ID of the version whose file data is to be used, if nil use latest version
+    # @return [String] Returns a remediated copy of the contentMetadata with fixity data filled in
+    def self.cm_remediate(object_id, version_id=nil)
+      cm = self.retrieve_file('metadata', 'contentMetadata.xml', object_id, version_id)
+      group = self.retrieve_file_group('content', object_id, version_id)
+      ContentInventory.new.remediate_content_metadata(cm,group)
+    end
+
+  end
+
+end

data/lib/tasks/yard.rake

@@ -0,0 +1,34 @@
+desc "Generate RDoc"
+task :doc => ['doc:generate']
+
+namespace :doc do
+  project_root = File.expand_path(File.join(File.dirname(__FILE__), '..', '..'))
+  doc_destination = File.join(project_root, 'doc')
+
+  begin
+    require 'yard'
+    require 'yard/rake/yardoc_task'
+
+    YARD::Rake::YardocTask.new(:generate) do |yt|
+      yt.files   =  Dir.glob(File.join(project_root, 'lib', '*.rb')) + 
+                    Dir.glob(File.join(project_root, 'lib', 'serializer', '*.rb')) +
+                    Dir.glob(File.join(project_root, 'lib', 'moab', '*.rb')) +
+                    Dir.glob(File.join(project_root, 'lib', 'stanford', '*.rb')) +
+                    ['-'] +
+                   [ File.join(project_root, 'LICENSE.rdoc') ]
+                   
+      yt.options = ['--output-dir', doc_destination, '--hide-void-return']
+    end
+  rescue LoadError
+    desc "Generate YARD Documentation"
+    task :generate do
+      abort "Please install the YARD gem to generate rdoc."
+    end
+  end
+
+  desc "Remove generated documentation"
+  task :clean do
+    rm_r doc_destination if File.exists?(doc_destination)
+  end
+
+end

data/lib/tools/api_doc_generator.rb

@@ -0,0 +1,396 @@
+#$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require 'rubygems'
+require 'hashery/orderedhash'
+require 'pathname'
+require 'yard'
+include YARD
+require 'moab_stanford'
+include Serializer
+include Moab
+include Stanford
+
+class String
+  def snake_case
+    self.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
+        gsub(/([a-z\d])([A-Z])/, '\1_\2').
+        tr("-", "_").
+        downcase
+  end
+end
+
+class Symbol
+  def snake_case
+    self.to_s.snake_case
+  end
+end
+
+class ApiClass
+  attr_accessor :class_name
+  attr_accessor :yard_class
+  attr_accessor :mhash
+  attr_accessor :ruby_class
+  attr_accessor :xml_tag
+  attr_accessor :description
+  attr_accessor :model
+
+  def self.class_hash=(class_hash)
+    @@class_hash = class_hash
+  end
+
+  def self.rootpath=(rootpath)
+    @@rootpath = rootpath
+  end
+
+  def initialize(class_name)
+    @class_name = class_name
+    @yard_class = @@class_hash[class_name]
+    if yard_class.nil?
+      raise "class_hash[#{class_name}] is Nil"
+    end
+    @mhash = categorize_members(@yard_class)
+    if @yard_class.path.include?('::')
+      ruby_module = Object::const_get(yard_class.path.split(/::/)[0])
+      @ruby_class = ruby_module.const_get(yard_class.name)
+    else
+      @ruby_class = Object::const_get(yard_class.path)
+    end
+
+    if @ruby_class.respond_to?(:tag_name)
+      @xml_tag = "<#{ruby_class.tag_name}>"
+    else
+      @xml_tag = '-'
+    end
+    docstring_all = confluence_translate(yard_class.docstring.all.split(/@/)[0])
+    docstring_parts = docstring_all.split(/h4. Data Model\n/)
+    @description = docstring_parts[0]
+    @model = docstring_parts.size > 1 ? docstring_parts[1] : nil
+  end
+
+  def categorize_members(yard_class)
+    mhash = {
+        :class_attributes => OrderedHash.new,
+        :instance_attributes => OrderedHash.new,
+        :class_methods => Array.new,
+        :instance_methods => Array.new
+    }
+    yard_class.children.each do |member|
+      attr_symbol = member.name.to_s.gsub(/=$/, '').to_sym
+      if member.name == :initialize
+        mhash[:constructor] = member
+      elsif yard_class.class_attributes[attr_symbol]
+        mhash[:class_attributes][attr_symbol] = yard_class.class_attributes[attr_symbol]
+      elsif yard_class.instance_attributes[attr_symbol]
+        mhash[:instance_attributes][attr_symbol] = yard_class.instance_attributes[attr_symbol]
+      elsif member.scope == :class
+        mhash[:class_methods] << member
+      elsif member.scope == :instance
+        mhash[:instance_methods] << member
+      end
+    end
+    mhash
+  end
+
+  def title
+    title = "\n{anchor:#{yard_class.name}}\n"
+    title << "h3. Class #{yard_class.path}"
+    title
+  end
+
+  def description
+    description = "\nh4. Description\n\n"
+    description << @description
+    description
+  end
+
+  def model
+    model = "\nh4. Data Model\n\n"
+    model << @model
+    model
+  end
+
+  def xml_example
+    xml_example = String.new
+    if yard_class.docstring.has_tag?('example')
+      xml_example << "\nh4. XML Example\n"
+      xml_example << "{code:lang=xml}\n"
+      filename = yard_class.docstring.tag('example').name.split(/[:)}]/)[2]
+      example = IO.read(File.join(@@rootpath, filename))
+      xml_example << example
+      xml_example << "{code}\n"
+    end
+    xml_example
+  end
+
+  def instance_attributes_table(mode=:all)
+    table = String.new
+    table <<  "\\\\\n||XML Element||Ruby Class||Inherits From||\n"
+    table << "|#{xml_tag}|[##{class_name}]|#{yard_class.superclass}|\n"
+    table << "\\\\\n||XML Child Node||Ruby Attribute||Data Type||Description||\n"
+    xml_names = xml_name_hash
+    @mhash[:instance_attributes].values.each do |attribute|
+      read = attribute[:read]
+      return_tag = read.docstring.tag(:return)
+      ruby_name = read.name.to_s
+      xml_name = xml_names[ruby_name] ? xml_names[ruby_name] : "-"
+      data_type = return_tag.types[0]
+      description = confluence_translate(return_tag.text.gsub(/\n/, ' '))
+      table_row = "|#{xml_name}|#{ruby_name}|#{data_type}|#{description.gsub(/\|/, '\\|')}|\n"
+      case mode
+        when :xml
+          if  xml_name != '-'
+            table << table_row
+          end
+        when :ruby
+          if  xml_name == '-'
+            table << table_row
+          end
+        else
+          table << table_row
+      end
+    end
+    table
+  end
+
+  def xml_name_hash
+    xml_name_hash = Hash.new
+    if @ruby_class.respond_to?(:attributes)
+      @ruby_class.attributes.each do |attribute|
+        xml_name_hash[attribute.name.to_s] = "@#{attribute.tag}"
+      end
+    end
+    if @ruby_class.respond_to?(:elements)
+      @ruby_class.elements.each do |element|
+        if element.options.size == 0 or element.options[:single]
+          xml_name_hash[element.name.to_s] = "<#{element.tag}>"
+        else
+          xml_name_hash[element.name.to_s] = "<#{element.tag}> \\[1..\\*]"
+        end
+      end
+    end
+    xml_name_hash
+  end
+
+  def methods_documentation
+
+    methods_documentation = String.new
+    
+    #methods_documentation ""
+    #methods_documentation "h4. Constructor"
+    #method = mhash[:constructor]
+    #methods_documentation_method(method, yard_class) if method
+
+    methods =mhash[:class_methods]
+    if methods.size > 0
+      methods_documentation << "\nh4. Class Methods\n"
+      methods.each do |method|
+        methods_documentation << method_documentation(method)
+      end
+    end
+
+    methods =mhash[:instance_methods]
+    if methods.size > 0
+      public_methods = Array.new
+      methods.each do |method|
+        if method.docstring.has_tag?(:api) && method.docstring.tag(:api).text == 'external'
+          public_methods << method
+        end
+      end
+      if public_methods.size > 0
+        methods_documentation << "\nh4. Instance Methods\n"
+        public_methods.each do |method|
+          methods_documentation << method_documentation(method)
+        end
+      end
+    end
+    methods_documentation
+  end
+
+  def method_documentation(method)
+
+    method_documentation = String.new
+    if method.nil?
+      raise "method is nil"
+    end
+    method_documentation << "\nh5. #{method.path}\n"
+
+    method_documentation << "||Method||Return Type||Description||\n"
+    if method.name == :initialize
+      return_type = @yard_class.name
+      description = 'constructor'
+    else
+      return_tag = method.docstring.tag(:return)
+      if return_tag.nil?
+        raise "#{method.name} return tag is nil"
+      end
+      return_type = return_tag.types[0]
+      description = confluence_translate(return_tag.text.gsub(/\n/, ' '))
+    end
+    method_documentation << "|#{method.name}|#{return_type}|#{example.description}|\n"
+
+    if method.respond_to?(:docstring)
+      params = method.docstring.tags(:param)
+      if params && params.size > 0
+        method_documentation << "\n||Parameter||Data Type||Description||\n"
+        params.each do |p|
+          description = confluence_translate(p.text.gsub(/\n/, ' '))
+          method_documentation << "|#{p.name}|#{p.types.join(', ')}|#{example.description}|\n"
+        end
+      end
+    end
+
+    method_documentation << "{code:lang=none|title=Ruby Source Code}\n"
+    method_documentation << method.source
+    method_documentation << "{code}\n"
+
+    if method.docstring.has_tag?('example')
+      method_documentation << "\n{code:lang=none|title=Usage Example}\n"
+      filename = method.docstring.tag('example').name.split(/[:)}]/)[2]
+      example = IO.read(File.join(@@rootpath, filename))
+      method_documentation << example
+      method_documentation << "{code}\n"
+    end
+    method_documentation
+  end
+
+  def confluence_translate(input)
+    map = OrderedHash.new
+    map[/\|/] = "\\|"
+    map[/====/] = "h4. "
+    map[/\*/] = "\\*"
+    map[/\n\s{6}\\\*\s/] = "\n****\s"
+    map[/\n\s{4}\\\*\s/] = "\n***\s"
+    map[/\n\s{2}\\\*\s/] = "\n**\s"
+    map[/\n\\\*\s/] = "\n*\s"
+    map[/<[\/]*b>/] = "*"
+    map[/<[\/]*i>/] = "_"
+    map[/\[/] = "\\["
+    map[/\{#/] = "[#"
+    map[/\{http/] = "[http"
+    map[/\{/] = "[#"
+    map[/\}/] = "]"
+    output = input
+    map.each do |regex, replacement|
+      output.gsub!(regex, replacement)
+    end
+    output
+  end
+
+end
+
+
+class ApiDoc < ApiClass
+  attr_accessor :ios
+  attr_accessor :classes
+
+  def process_doc(ios)
+    @ios = ios
+    parse_model
+
+    output component
+    output model
+    output description
+    output xml_example
+    output xml_nodes
+    classes_detail
+  end
+
+  def component
+    component = "h2. Component:  #{yard_class.name}\n"
+    component
+  end
+
+  def xml_nodes
+    nodes = "\nh4. XML Nodes\n"
+    @classes.each do |cls|
+      nodes << cls.instance_attributes_table(mode=:xml)
+    end
+    nodes
+  end
+
+  def classes_detail
+    @classes.each do |cls|
+      output cls.title
+      output cls.description if cls != self
+      output cls.methods_documentation
+    end
+  end
+
+  def parse_model
+    @classes = Array.new
+    @classes << self
+    if @model
+      model.lines.each do |line|
+        matches = line.scan(/\[#(.*)?\]/)
+        if matches.size > 0
+          match = matches[0][0].split(/\]/)[0]
+          if match != class_name
+            @classes << ApiClass.new(match)
+          end
+        end
+      end
+    end
+
+  end
+
+  def output(string)
+    @ios.puts  string
+  end
+
+
+end
+
+
+class DocGenerator
+
+  def initialize(rootpath)
+    @rootpath = rootpath
+  end
+
+  def generate_docs(apis)
+    temp_pathname = Pathname(@rootpath).join('api', 'temp')
+    ApiClass.class_hash = get_class_hash
+    ApiClass.rootpath = @rootpath
+    apis.each do |api_name|
+      doc_pathname = temp_pathname.join(api_name + "_confluence.txt")
+      doc_pathname.parent.mkpath
+      #puts doc_pathname.to_s
+      #unless doc_pathname.exist?
+        begin
+          @constructor_params = Array.new
+          @indent = 0
+          ios = doc_pathname.open("w")
+          api_doc = ApiDoc.new(api_name)
+          api_doc.process_doc(ios)
+        ensure
+          ios.close
+        end
+      #end
+    end
+  end
+
+  def get_class_hash()
+    class_hash = Hash.new
+    yardoc = File.join(@rootpath, '.yardoc')
+    Registry.load!(yardoc) # loads all objects into memory
+    class_array = Registry.all(:class) # Array
+    class_array.each do |cls|
+      class_hash[cls.name.to_s] = cls
+    end
+    class_hash
+  end
+
+end
+
+apis = Array.new
+apis << 'FileInventory'
+apis << 'SignatureCatalog'
+apis << 'FileInventoryDifference'
+apis << 'VersionMetadata'
+apis << 'Serializable'
+apis << 'StorageObject'
+apis << 'StorageRepository'
+apis << 'DorMetadata'
+
+sg = DocGenerator.new(File.expand_path(File.join(File.dirname(__FILE__), '..', '..')))
+sg.generate_docs(apis)