fieldhand 0.1.0

data/lib/fieldhand.rb

@@ -0,0 +1 @@
+require 'fieldhand/repository'

data/lib/fieldhand/arguments.rb

@@ -0,0 +1,42 @@
+require 'fieldhand/datestamp'
+
+module Fieldhand
+  # A class for converting Fieldhand arguments into OAI-PMH query parameters.
+  class Arguments
+    VALID_KEYS = {
+      :metadata_prefix => 'metadataPrefix',
+      :resumption_token => 'resumptionToken',
+      :from => 'from',
+      :until => 'until',
+      :set => 'set'
+    }.freeze
+
+    attr_reader :options
+
+    def initialize(options = {})
+      @options = options
+    end
+
+    def to_query
+      options.inject(defaults) do |query, (key, value)|
+        raise ::ArgumentError, "unknown argument: #{key}" unless VALID_KEYS.key?(key)
+
+        query[VALID_KEYS.fetch(key)] = convert_value(key, value)
+
+        query
+      end
+    end
+
+    def defaults
+      { 'metadataPrefix' => 'oai_dc' }
+    end
+
+    private
+
+    def convert_value(key, value)
+      return value.to_s unless key == :from || key == :until
+
+      Datestamp.unparse(value)
+    end
+  end
+end

data/lib/fieldhand/datestamp.rb

@@ -0,0 +1,28 @@
+require 'date'
+require 'time'
+
+module Fieldhand
+  # A class to handle datestamps of varying granularity.
+  class Datestamp
+    def self.parse(datestamp)
+      if datestamp.size == 10
+        ::Date.strptime(datestamp)
+      else
+        ::Time.xmlschema(datestamp)
+      end
+    end
+
+    def self.unparse(datestamp)
+      case datestamp
+      when ::String
+        datestamp
+      when ::Date
+        datestamp.strftime
+      when ::Time
+        datestamp.utc.xmlschema
+      else
+        datestamp.xmlschema
+      end
+    end
+  end
+end

data/lib/fieldhand/header.rb

@@ -0,0 +1,42 @@
+require 'fieldhand/datestamp'
+
+module Fieldhand
+  # Contains the unique identifier of the item and properties necessary for selective harvesting. The header consists of
+  # the following parts:
+  #
+  # * the unique identifier -- the unique identifier of an item in a repository;
+  # * the datestamp -- the date of creation, modification or deletion of the record for the purpose of selective
+  #   harvesting.
+  # * zero or more setSpec elements -- the set membership of the item for the purpose of selective harvesting.
+  # * an optional status attribute with a value of deleted indicates the withdrawal of availability of the specified
+  #   metadata format for the item, dependent on the repository support for deletions.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#header
+  class Header
+    attr_reader :element
+
+    def initialize(element)
+      @element = element
+    end
+
+    def deleted?
+      status == 'deleted'
+    end
+
+    def status
+      element['status']
+    end
+
+    def identifier
+      @identifier ||= element.identifier.text
+    end
+
+    def datestamp
+      @datestamp ||= Datestamp.parse(element.datestamp.text)
+    end
+
+    def sets
+      @sets ||= element.locate('setSpec/^String')
+    end
+  end
+end

data/lib/fieldhand/identify.rb

@@ -0,0 +1,51 @@
+require 'fieldhand/datestamp'
+require 'uri'
+
+module Fieldhand
+  # Information about a repository.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#Identify
+  class Identify
+    attr_reader :element
+
+    def initialize(element)
+      @element = element
+    end
+
+    def name
+      @name ||= element.repositoryName.text
+    end
+
+    def base_url
+      @base_url ||= URI(element.baseURL.text)
+    end
+
+    def protocol_version
+      @protocol_version ||= element.protocolVersion.text
+    end
+
+    def earliest_datestamp
+      @earliest_datestamp ||= Datestamp.parse(element.earliestDatestamp.text)
+    end
+
+    def deleted_record
+      @deleted_record ||= element.deletedRecord.text
+    end
+
+    def granularity
+      @granularity ||= element.granularity.text
+    end
+
+    def admin_emails
+      @admin_emails ||= element.locate('adminEmail/^String')
+    end
+
+    def compression
+      @compression ||= element.locate('compression/^String')
+    end
+
+    def descriptions
+      @descriptions ||= element.locate('description')
+    end
+  end
+end

data/lib/fieldhand/logger.rb

@@ -0,0 +1,28 @@
+require 'logger'
+require 'rbconfig'
+
+module Fieldhand
+  # A default null logger for discarding log messages.
+  module Logger
+    module_function
+
+    def null
+      ::Logger.new(null_device)
+    end
+
+    # Determine the null device on this platform, a backport of more recent Rubies' File::NULL
+    # See https://github.com/marcandre/backports/blob/v3.8.0/lib/backports/1.9.3/file/null.rb
+    def null_device
+      platform = ::RUBY_PLATFORM
+      platform = ::RbConfig::CONFIG['host_os'] if platform == 'java'
+
+      case platform
+      when /mswin|mingw/i then 'NUL'
+      when /amiga/i then 'NIL:'
+      when /openvms/i then 'NL:'
+      else
+        '/dev/null'
+      end
+    end
+  end
+end

data/lib/fieldhand/metadata_format.rb

@@ -0,0 +1,30 @@
+require 'uri'
+
+module Fieldhand
+  # A metadata format supported by the repository.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#ListMetadataFormats
+  class MetadataFormat
+    attr_reader :element
+
+    def initialize(element)
+      @element = element
+    end
+
+    def to_s
+      prefix
+    end
+
+    def prefix
+      @prefix ||= element.metadataPrefix.text
+    end
+
+    def schema
+      @schema ||= URI(element.schema.text)
+    end
+
+    def namespace
+      @namespace ||= URI(element.metadataNamespace.text)
+    end
+  end
+end

data/lib/fieldhand/paginator.rb

@@ -0,0 +1,90 @@
+require 'fieldhand/logger'
+require 'ox'
+require 'cgi'
+require 'net/http'
+require 'uri'
+
+module Fieldhand
+  NetworkError = ::Class.new(::StandardError)
+  ProtocolError = ::Class.new(::StandardError)
+  BadArgumentError = ::Class.new(ProtocolError)
+  BadResumptionTokenError = ::Class.new(ProtocolError)
+  BadVerbError = ::Class.new(ProtocolError)
+  CannotDisseminateFormatError = ::Class.new(ProtocolError)
+  IdDoesNotExistError = ::Class.new(ProtocolError)
+  NoRecordsMatchError = ::Class.new(ProtocolError)
+  NoMetadataFormatsError = ::Class.new(ProtocolError)
+  NoSetHierarchyError = ::Class.new(ProtocolError)
+
+  # An abstraction over interactions with an OAI-PMH repository, handling requests, responses and paginating over
+  # results using a resumption token.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#FlowControl
+  class Paginator
+    ERROR_CODES = {
+      'badArgument' => BadArgumentError,
+      'badResumptionToken' => BadResumptionTokenError,
+      'badVerb' => BadVerbError,
+      'cannotDisseminateFormat' => CannotDisseminateFormatError,
+      'idDoesNotExist' => IdDoesNotExistError,
+      'noRecordsMatch' => NoRecordsMatchError,
+      'noMetadataFormats' => NoMetadataFormatsError,
+      'noSetHierarchy' => NoSetHierarchyError
+    }.freeze
+
+    attr_reader :uri, :logger, :http
+
+    def initialize(uri, logger = Logger.null)
+      @uri = uri.is_a?(::URI) ? uri : URI(uri)
+      @logger = logger
+      @http = ::Net::HTTP.new(@uri.host, @uri.port)
+      @http.use_ssl = true if @uri.scheme == 'https'
+    end
+
+    def items(verb, path, query = {}) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      return enum_for(:items, verb, path, query) unless block_given?
+
+      loop do
+        document = ::Ox.parse(request(query.merge('verb' => verb)))
+
+        document.root.locate('error').each do |error|
+          convert_error(error)
+        end
+
+        document.root.locate(path).each do |item|
+          yield item
+        end
+
+        resumption_token = document.root.locate('?/resumptionToken/^String').first
+        break unless resumption_token
+
+        logger.debug('Fieldhand') { "Resumption token for #{verb}: #{resumption_token}" }
+        query = { 'resumptionToken' => resumption_token }
+      end
+    end
+
+    private
+
+    def request(query = {})
+      request_uri = uri.dup
+      request_uri.query = encode_query(query)
+
+      logger.info('Fieldhand') { "GET #{request_uri}" }
+      http.get(request_uri.request_uri).body
+    rescue ::Timeout::Error => e
+      raise NetworkError, "timeout requesting #{query}: #{e}"
+    rescue => e
+      raise NetworkError, "error requesting #{query}: #{e}"
+    end
+
+    def convert_error(error)
+      return unless ERROR_CODES.key?(error['code'])
+
+      raise ERROR_CODES.fetch(error['code']), error.text
+    end
+
+    def encode_query(query = {})
+      query.map { |k, v| ::CGI.escape(k) << '=' << ::CGI.escape(v) }.join('&')
+    end
+  end
+end

data/lib/fieldhand/record.rb

@@ -0,0 +1,46 @@
+require 'fieldhand/header'
+
+module Fieldhand
+  # A record is metadata expressed in a single format.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#Record
+  class Record
+    attr_reader :element
+
+    def initialize(element)
+      @element = element
+    end
+
+    def deleted?
+      header.deleted?
+    end
+
+    def status
+      header.status
+    end
+
+    def identifier
+      header.identifier
+    end
+
+    def datestamp
+      header.datestamp
+    end
+
+    def sets
+      header.sets
+    end
+
+    def metadata
+      @metadata ||= element.locate('metadata[0]').first
+    end
+
+    def about
+      @about ||= element.locate('about')
+    end
+
+    def header
+      @header ||= Header.new(element.header)
+    end
+  end
+end

data/lib/fieldhand/repository.rb

@@ -0,0 +1,95 @@
+require 'fieldhand/arguments'
+require 'fieldhand/header'
+require 'fieldhand/identify'
+require 'fieldhand/logger'
+require 'fieldhand/metadata_format'
+require 'fieldhand/paginator'
+require 'fieldhand/record'
+require 'fieldhand/set'
+require 'uri'
+
+module Fieldhand
+  # A repository is a network accessible server that can process the 6 OAI-PMH requests.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html
+  class Repository
+    attr_reader :uri, :logger
+
+    def initialize(uri, logger = Logger.null)
+      @uri = uri.is_a?(::URI) ? uri : URI(uri)
+      @logger = logger
+    end
+
+    def identify
+      paginator.
+        items('Identify', 'Identify').
+        map { |identify| Identify.new(identify) }.
+        first
+    end
+
+    def metadata_formats(identifier = nil)
+      return enum_for(:metadata_formats, identifier) unless block_given?
+
+      arguments = {}
+      arguments['identifier'] = identifier if identifier
+
+      paginator.
+        items('ListMetadataFormats', 'ListMetadataFormats/metadataFormat', arguments).
+        each do |format|
+          yield MetadataFormat.new(format)
+        end
+    end
+
+    def sets
+      return enum_for(:sets) unless block_given?
+
+      paginator.
+        items('ListSets', 'ListSets/set').
+        each do |set|
+          yield Set.new(set)
+        end
+    end
+
+    def records(arguments = {})
+      return enum_for(:records, arguments) unless block_given?
+
+      query = Arguments.new(arguments).to_query
+
+      paginator.
+        items('ListRecords', 'ListRecords/record', query).
+        each do |record|
+          yield Record.new(record)
+        end
+    end
+
+    def identifiers(arguments = {})
+      return enum_for(:identifiers, arguments) unless block_given?
+
+      query = Arguments.new(arguments).to_query
+
+      paginator.
+        items('ListIdentifiers', 'ListIdentifiers/header', query).
+        each do |header|
+          yield Header.new(header)
+        end
+    end
+
+    def get(identifier, arguments = {})
+      query = {
+        'identifier' => identifier,
+        'metadataPrefix' => arguments.fetch(:metadata_prefix, 'oai_dc')
+      }
+
+      paginator.
+        items('GetRecord', 'GetRecord/record', query).
+        map { |record| Record.new(record) }.
+        first
+    end
+
+    private
+
+    def paginator
+      @paginator ||= Paginator.new(uri, logger)
+    end
+  end
+end