fieldhand 0.1.0

data/lib/fieldhand/set.rb

@@ -0,0 +1,28 @@
+module Fieldhand
+  # A set is an optional construct for grouping items for the purpose of selective harvesting.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#Set
+  class Set
+    attr_reader :element
+
+    def initialize(element)
+      @element = element
+    end
+
+    def to_s
+      spec
+    end
+
+    def spec
+      @spec ||= element.setSpec.text
+    end
+
+    def name
+      @name ||= element.setName.text
+    end
+
+    def descriptions
+      @descriptions ||= element.locate('setDescription')
+    end
+  end
+end

data/spec/fieldhand/arguments_spec.rb

@@ -0,0 +1,94 @@
+require 'fieldhand/arguments'
+require 'fieldhand/set'
+require 'fieldhand/metadata_format'
+require 'ox'
+require 'date'
+require 'time'
+
+module Fieldhand
+  RSpec.describe Arguments do
+    describe '#to_query' do
+      it 'returns a metadata prefix of "oai_dc" by default' do
+        arguments = described_class.new
+
+        expect(arguments.to_query).to eq('metadataPrefix' => 'oai_dc')
+      end
+
+      it 'allows overriding the metadata prefix' do
+        arguments = described_class.new(:metadata_prefix => 'xoai')
+
+        expect(arguments.to_query).to eq('metadataPrefix' => 'xoai')
+      end
+
+      it 'allows overriding the metadata prefix with a Metadata Format' do
+        element = ::Ox.parse('<metadataFormat><metadataPrefix>xoai</metadataPrefix></metadataFormat>')
+        format = MetadataFormat.new(element)
+        arguments = described_class.new(:metadata_prefix => format)
+
+        expect(arguments.to_query).to eq('metadataPrefix' => 'xoai')
+      end
+
+      it 'allows passing a resumption token' do
+        arguments = described_class.new(:resumption_token => 'foo')
+
+        expect(arguments.to_query).to include('resumptionToken' => 'foo')
+      end
+
+      it 'allows passing a from datestamp' do
+        arguments = described_class.new(:from => '2001-01-01')
+
+        expect(arguments.to_query).to include('from' => '2001-01-01')
+      end
+
+      it 'converts a Date from datestamp to a string' do
+        arguments = described_class.new(:from => ::Date.new(2001, 1, 1))
+
+        expect(arguments.to_query).to include('from' => '2001-01-01')
+      end
+
+      it 'converts a Time from datestamp to a string' do
+        arguments = described_class.new(:from => ::Time.utc(2001, 1, 1, 0, 0, 0))
+
+        expect(arguments.to_query).to include('from' => '2001-01-01T00:00:00Z')
+      end
+
+      it 'allows passing an until datestamp' do
+        arguments = described_class.new(:until => '2001-01-01')
+
+        expect(arguments.to_query).to include('until' => '2001-01-01')
+      end
+
+      it 'converts a Date until datestamp to a string' do
+        arguments = described_class.new(:until => ::Date.new(2001, 1, 1))
+
+        expect(arguments.to_query).to include('until' => '2001-01-01')
+      end
+
+      it 'converts a Time until datestamp to a string' do
+        arguments = described_class.new(:until => ::Time.utc(2001, 1, 1, 0, 0, 0))
+
+        expect(arguments.to_query).to include('until' => '2001-01-01T00:00:00Z')
+      end
+
+      it 'allows passing a set spec' do
+        arguments = described_class.new(:set => 'A')
+
+        expect(arguments.to_query).to include('set' => 'A')
+      end
+
+      it 'allows passing a Set as a set spec' do
+        element = ::Ox.parse('<set><setSpec>A</setSpec></set>')
+        set = Set.new(element)
+        arguments = described_class.new(:set => set)
+
+        expect(arguments.to_query).to include('set' => 'A')
+      end
+
+      it 'raises an error when given unknown arguments' do
+        arguments = described_class.new(:foo => 'bar')
+
+        expect { arguments.to_query }.to raise_error(::ArgumentError)
+      end
+    end
+  end
+end

data/spec/fieldhand/datestamp_spec.rb

@@ -0,0 +1,38 @@
+require 'fieldhand/datestamp'
+
+module Fieldhand
+  RSpec.describe Datestamp do
+    describe '.parse' do
+      it 'parses date-granularity datestamps into Dates' do
+        expect(described_class.parse('2001-01-01')).
+          to eq(::Date.new(2001, 1, 1))
+      end
+
+      it 'parses time-granularity datestamps into Times' do
+        expect(described_class.parse('2001-01-01T00:00:00Z')).
+          to eq(::Time.utc(2001, 1, 1, 0, 0, 0))
+      end
+    end
+
+    describe '.unparse' do
+      it 'unparses Dates into date-granularity datestamps' do
+        expect(described_class.unparse(::Date.new(2001, 1, 1))).
+          to eq('2001-01-01')
+      end
+
+      it 'unparses Times into time-granularity datestamps' do
+        expect(described_class.unparse(::Time.utc(2001, 1, 1, 0, 0, 0))).
+          to eq('2001-01-01T00:00:00Z')
+      end
+
+      it 'unparses non UTC Times into time-granularity datestamps' do
+        expect(described_class.unparse(::Time.parse('2001-01-01 01:00:00 +0100'))).
+          to eq('2001-01-01T00:00:00Z')
+      end
+
+      it 'unparses strings into themselves' do
+        expect(described_class.unparse('2001-01-01')).to eq('2001-01-01')
+      end
+    end
+  end
+end

data/spec/fieldhand/header_spec.rb

@@ -0,0 +1,38 @@
+require 'fieldhand/header'
+require 'ox'
+
+module Fieldhand
+  RSpec.describe Header do
+    describe '#deleted?' do
+      it 'is true when the status is deleted' do
+        element = ::Ox.parse('<header status="deleted"/>')
+        header = described_class.new(element)
+
+        expect(header).to be_deleted
+      end
+
+      it 'is false when there is no status' do
+        element = ::Ox.parse('<header/>')
+        header = described_class.new(element)
+
+        expect(header).not_to be_deleted
+      end
+    end
+
+    describe '#datestamp' do
+      it 'supports time-granularity datestamps' do
+        element = ::Ox.parse('<header><datestamp>2001-01-01T00:00:00Z</datestamp></header>')
+        header = described_class.new(element)
+
+        expect(header.datestamp).to eq(::Time.utc(2001, 1, 1, 0, 0, 0))
+      end
+
+      it 'supports date-granularity datestamps' do
+        element = ::Ox.parse('<header><datestamp>2001-01-01</datestamp></header>')
+        header = described_class.new(element)
+
+        expect(header.datestamp).to eq(::Date.new(2001, 1, 1))
+      end
+    end
+  end
+end

data/spec/fieldhand/identify_spec.rb

@@ -0,0 +1,43 @@
+require 'fieldhand/identify'
+require 'ox'
+
+module Fieldhand
+  RSpec.describe Identify do
+    describe '#base_url' do
+      it 'returns the base URL as a URI' do
+        element = ::Ox.parse(<<-XML)
+          <Identify>
+            <baseURL>http://www.example.com/oai</baseURL>
+          </Identify>
+        XML
+        identify = described_class.new(element)
+
+        expect(identify.base_url).to eq(URI('http://www.example.com/oai'))
+      end
+    end
+
+    describe '#earliest_datestamp' do
+      it 'supports time datestamps' do
+        element = ::Ox.parse(<<-XML)
+          <Identify>
+            <earliestDatestamp>1990-02-01T12:00:00Z</earliestDatestamp>
+          </Identify>
+        XML
+        identify = described_class.new(element)
+
+        expect(identify.earliest_datestamp).to eq(::Time.utc(1990, 2, 1, 12, 0, 0))
+      end
+
+      it 'supports date datestamps' do
+        element = ::Ox.parse(<<-XML)
+          <Identify>
+            <earliestDatestamp>1990-02-01</earliestDatestamp>
+          </Identify>
+        XML
+        identify = described_class.new(element)
+
+        expect(identify.earliest_datestamp).to eq(::Date.new(1990, 2, 1))
+      end
+    end
+  end
+end

data/spec/fieldhand/metadata_format_spec.rb

@@ -0,0 +1,15 @@
+require 'fieldhand/metadata_format'
+require 'ox'
+
+module Fieldhand
+  RSpec.describe MetadataFormat do
+    describe '#to_s' do
+      it 'returns the prefix' do
+        element = ::Ox.parse('<metadataFormat><metadataPrefix>xoai</metadataPrefix></metadataFormat>')
+        format = described_class.new(element)
+
+        expect(format.to_s).to eq('xoai')
+      end
+    end
+  end
+end

data/spec/fieldhand/paginator_spec.rb

@@ -0,0 +1,84 @@
+require 'fieldhand/paginator'
+
+module Fieldhand
+  RSpec.describe Paginator do
+    describe '#items' do
+      it 'raises a Bad Argument Error if returned from the repository' do
+        stub_oai_request('http://www.example.com/oai?verb=Identify&bad=Argument',
+                         'bad_argument_error.xml')
+        paginator = described_class.new('http://www.example.com/oai')
+
+        expect { paginator.items('Identify', 'Identify', 'bad' => 'Argument').first }.
+          to raise_error(BadArgumentError)
+      end
+
+      it 'raises a Bad Resumption Token Error if returned from the repository' do
+        stub_oai_request('http://www.example.com/oai?verb=ListRecords&resumptionToken=foo',
+                         'bad_resumption_token_error.xml')
+        paginator = described_class.new('http://www.example.com/oai')
+
+        expect { paginator.items('ListRecords', 'ListRecords/record', 'resumptionToken' => 'foo').first }.
+          to raise_error(BadResumptionTokenError)
+      end
+
+      it 'raises a Bad Verb Error if returned from the repository' do
+        stub_oai_request('http://www.example.com/oai?verb=Bad',
+                         'bad_verb_error.xml')
+        paginator = described_class.new('http://www.example.com/oai')
+
+        expect { paginator.items('Bad', 'Bad').first }.
+          to raise_error(BadVerbError)
+      end
+
+      it 'raises a Cannot Disseminate Format Error if returned from the repository' do
+        stub_oai_request('http://www.example.com/oai?verb=ListRecords&metadataPrefix=bad',
+                         'cannot_disseminate_format_error.xml')
+        paginator = described_class.new('http://www.example.com/oai')
+
+        expect { paginator.items('ListRecords', 'ListRecords/record', 'metadataPrefix' => 'bad').first }.
+          to raise_error(CannotDisseminateFormatError)
+      end
+
+      it 'raises an ID Does Not Exist Error if returned from the repository' do
+        stub_oai_request('http://www.example.com/oai?verb=GetRecord&metadataPrefix=oai_dc&identifier=bad',
+                         'id_does_not_exist_error.xml')
+        paginator = described_class.new('http://www.example.com/oai')
+
+        expect {
+          paginator.items('GetRecord', 'GetRecord/record', 'metadataPrefix' => 'oai_dc', 'identifier' => 'bad').first
+        }.to raise_error(IdDoesNotExistError)
+      end
+
+      it 'raises a No Records Match Error if returned from the repository' do
+        stub_oai_request('http://www.example.com/oai?verb=ListRecords&metadataPrefix=oai_dc&from=2999-01-01',
+                         'no_records_match_error.xml')
+        paginator = described_class.new('http://www.example.com/oai')
+
+        expect {
+          paginator.
+            items('ListRecords', 'ListRecords/record', 'metadataPrefix' => 'oai_dc', 'from' => '2999-01-01').
+            first
+        }.to raise_error(NoRecordsMatchError)
+      end
+
+      it 'raises a No Metadata Formats Error if returned from the repository' do
+        stub_oai_request('http://www.example.com/oai?verb=ListMetadataFormats&identifier=bad',
+                         'no_metadata_formats_error.xml')
+        paginator = described_class.new('http://www.example.com/oai')
+
+        expect {
+          paginator.items('ListMetadataFormats', 'ListMetadataFormats/metadataFormat', 'identifier' => 'bad').first
+        }.to raise_error(NoMetadataFormatsError)
+      end
+
+      it 'raises a No Set Hierarchy Error if returned from the repository' do
+        stub_oai_request('http://www.example.com/oai?verb=ListSets',
+                         'no_set_hierarchy_error.xml')
+        paginator = described_class.new('http://www.example.com/oai')
+
+        expect { paginator.items('ListSets', 'ListSets/set').first }.
+          to raise_error(NoSetHierarchyError)
+      end
+    end
+  end
+end

data/spec/fieldhand/record_spec.rb

@@ -0,0 +1,38 @@
+require 'fieldhand/record'
+require 'ox'
+
+module Fieldhand
+  RSpec.describe Record do
+    describe '#deleted?' do
+      it 'is true when the record has a deleted status' do
+        element = ::Ox.parse('<record><header status="deleted"/></record>')
+        record = described_class.new(element)
+
+        expect(record).to be_deleted
+      end
+
+      it 'is false when the record does not have a status' do
+        element = ::Ox.parse('<record><header/></record>')
+        record = described_class.new(element)
+
+        expect(record).not_to be_deleted
+      end
+    end
+
+    describe '#about' do
+      it 'returns an empty array if there are no about elements' do
+        element = ::Ox.parse('<record/>')
+        record = described_class.new(element)
+
+        expect(record.about).to be_empty
+      end
+
+      it 'returns about sections when present' do
+        element = ::Ox.parse('<record><about/><about/></record>')
+        record = described_class.new(element)
+
+        expect(record.about.size).to eq(2)
+      end
+    end
+  end
+end

data/spec/fieldhand/repository_spec.rb

@@ -0,0 +1,191 @@
+require 'fieldhand/repository'
+
+module Fieldhand
+  RSpec.describe Repository do
+    describe '#metadata_formats' do
+      it 'returns the supported metadata formats for this repository' do
+        stub_oai_request('http://www.example.com/oai?verb=ListMetadataFormats', 'list_metadata_formats.xml')
+        repository = described_class.new('http://www.example.com/oai')
+        formats = repository.metadata_formats.to_a
+
+        expect(formats.size).to eq(1)
+      end
+
+      it 'populates metadata formats with the right information' do
+        stub_oai_request('http://www.example.com/oai?verb=ListMetadataFormats', 'list_metadata_formats.xml')
+        repository = described_class.new('http://www.example.com/oai')
+        format = repository.metadata_formats.first
+
+        expect(format).to have_attributes(:prefix => 'oai_dc',
+                                          :schema => URI('http://www.openarchives.org/OAI/2.0/oai_dc.xsd'),
+                                          :namespace => URI('http://www.openarchives.org/OAI/2.0/oai_dc/'))
+      end
+
+      it 'raises an error if the connection times out' do
+        stub_request(:get, 'http://www.example.com/oai?verb=ListMetadataFormats').
+          to_timeout
+        repository = described_class.new('http://www.example.com/oai')
+
+        expect { repository.metadata_formats.to_a }.to raise_error(NetworkError)
+      end
+
+      it 'raises an error if the connection resets' do
+        stub_request(:get, 'http://www.example.com/oai?verb=ListMetadataFormats').
+          to_raise(::Errno::ECONNRESET)
+        repository = described_class.new('http://www.example.com/oai')
+
+        expect { repository.metadata_formats.to_a }.to raise_error(NetworkError)
+      end
+
+      it 'raises an error if the host is unreachable' do
+        stub_request(:get, 'http://www.example.com/oai?verb=ListMetadataFormats').
+          to_raise(::Errno::EHOSTUNREACH)
+        repository = described_class.new('http://www.example.com/oai')
+
+        expect { repository.metadata_formats.to_a }.to raise_error(NetworkError)
+      end
+
+      it 'supports an optional identifier argument' do
+        stub_oai_request('http://www.example.com/oai?verb=ListMetadataFormats&identifier=foobar',
+                         'list_metadata_formats.xml')
+        repository = described_class.new('http://www.example.com/oai')
+
+        repository.metadata_formats('foobar').to_a
+      end
+    end
+
+    describe '#sets' do
+      it 'returns the sets for this repository' do
+        stub_oai_request('http://www.example.com/oai?verb=ListSets', 'list_sets_2.xml')
+        repository = described_class.new('http://www.example.com/oai')
+        set_b = repository.sets.first
+
+        expect(set_b).to have_attributes(:spec => 'B', :name => 'Set B.')
+      end
+
+      it 'paginates over all sets for this repository' do
+        stub_oai_request('http://www.example.com/oai?verb=ListSets', 'list_sets_1.xml')
+        stub_oai_request('http://www.example.com/oai?verb=ListSets&resumptionToken=foobar', 'list_sets_2.xml')
+        repository = described_class.new('http://www.example.com/oai')
+        sets = repository.sets.to_a
+
+        expect(sets.size).to eq(2)
+      end
+
+      it 'raises an error if the connection times out while consuming' do
+        stub_request(:get, 'http://www.example.com/oai?verb=ListSets').to_timeout
+        repository = described_class.new('http://www.example.com/oai')
+
+        expect { repository.sets.to_a }.to raise_error(NetworkError)
+      end
+    end
+
+    describe '#records' do
+      it 'defaults to using a metadata prefix of oai_dc' do
+        stub_oai_request('http://www.example.com/oai?verb=ListRecords&metadataPrefix=oai_dc', 'list_records_1.xml')
+        repository = described_class.new('http://www.example.com/oai')
+
+        repository.records.first
+      end
+
+      it 'returns all records for this repository' do
+        stub_oai_request('http://www.example.com/oai?verb=ListRecords&metadataPrefix=oai_dc', 'list_records_1.xml')
+        stub_oai_request('http://www.example.com/oai?verb=ListRecords&resumptionToken=foobar', 'list_records_2.xml')
+        repository = described_class.new('http://www.example.com/oai')
+        records = repository.records(:metadata_prefix => 'oai_dc').to_a
+
+        expect(records.size).to eq(4)
+      end
+
+      it 'populates records with the right information' do
+        stub_oai_request('http://www.example.com/oai?verb=ListRecords&metadataPrefix=oai_dc', 'list_records_1.xml')
+        repository = described_class.new('http://www.example.com/oai')
+        record = repository.records.first
+
+        expect(record).to have_attributes(:identifier => 'oai:oai.datacite.org:32355',
+                                          :datestamp => ::Time.xmlschema('2011-07-07T11:19:03Z'),
+                                          :sets => %w[TIB TIB.DAGST])
+      end
+
+      it 'populates deleted records with the right information' do
+        stub_oai_request('http://www.example.com/oai?verb=ListRecords&metadataPrefix=oai_dc', 'list_records_2.xml')
+        repository = described_class.new('http://www.example.com/oai')
+        record = repository.records.first
+
+        expect(record).to have_attributes(:status => 'deleted',
+                                          :datestamp => ::Time.xmlschema('2011-03-04T14:18:47Z'),
+                                          :sets => %w[BL BL.WAP])
+      end
+
+      it 'supports passing extra arguments to the request' do
+        stub_oai_request('http://www.example.com/oai?verb=ListRecords&metadataPrefix=oai_dc&from=2001-01-01&until=2002-01-01',
+                         'list_records_2.xml')
+        repository = described_class.new('http://www.example.com/oai')
+
+        repository.records(:from => '2001-01-01', :until => '2002-01-01')
+      end
+    end
+
+    describe '#identifiers' do
+      it 'defaults to a metadata prefix of "oai_dc"' do
+        stub_oai_request('http://www.example.com/oai?verb=ListIdentifiers&metadataPrefix=oai_dc',
+                         'list_identifiers.xml')
+        repository = described_class.new('http://www.example.com/oai')
+
+        repository.identifiers.first
+      end
+
+      it 'returns all headers from the repository' do
+        stub_oai_request('http://www.example.com/oai?verb=ListIdentifiers&metadataPrefix=oai_dc',
+                         'list_identifiers.xml')
+        repository = described_class.new('http://www.example.com/oai')
+        headers = repository.identifiers(:metadata_prefix => 'oai_dc').to_a
+
+        expect(headers.size).to eq(2)
+      end
+    end
+
+    describe '#identify' do
+      it 'returns information about the repository' do
+        stub_oai_request('http://www.example.com/oai?verb=Identify', 'identify.xml')
+        repository = described_class.new('http://www.example.com/oai')
+        identify = repository.identify
+
+        expect(identify).to have_attributes(:name => 'DataCite MDS',
+                                            :base_url => URI('http://oai.datacite.org/oai'),
+                                            :protocol_version => '2.0',
+                                            :earliest_datestamp => ::Time.xmlschema('2011-01-01T00:00:00Z'),
+                                            :deleted_record => 'persistent',
+                                            :granularity => 'YYYY-MM-DDThh:mm:ssZ',
+                                            :admin_emails => %w[admin@datacite.org],
+                                            :compression => %w[gzip deflate])
+      end
+
+      it 'supports HTTPS repositories' do
+        stub_oai_request('https://www.example.com/oai?verb=Identify', 'identify.xml')
+        repository = described_class.new('https://www.example.com/oai')
+
+        expect(repository.identify).not_to be_nil
+      end
+    end
+
+    describe '#get' do
+      it 'defaults to a metadata prefix of "oai_dc"' do
+        stub_oai_request('http://www.example.com/oai?verb=GetRecord&metadataPrefix=oai_dc&identifier=oai:oai.datacite.org:32356',
+                         'get_record.xml')
+        repository = described_class.new('http://www.example.com/oai')
+
+        repository.get('oai:oai.datacite.org:32356')
+      end
+
+      it 'fetches the record by identifier' do
+        stub_oai_request('http://www.example.com/oai?verb=GetRecord&metadataPrefix=oai_dc&identifier=oai:oai.datacite.org:32356',
+                         'get_record.xml')
+        repository = described_class.new('http://www.example.com/oai')
+
+        expect(repository.get('oai:oai.datacite.org:32356', :metadata_prefix => 'oai_dc')).
+          to have_attributes(:identifier => 'oai:oai.datacite.org:32356')
+      end
+    end
+  end
+end