Class: OAI::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/oai/client.rb

Overview

A OAI::Client provides a client api for issuing OAI-PMH verbs against a OAI-PMH server. The 6 OAI-PMH verbs translate directly to methods you can call on a OAI::Client object. Verb arguments are passed as a hash:

client = OAI::Client.new 'http://www.pubmedcentral.gov/oai/oai.cgi'
record = client.get_record :identifier => 'oai:pubmedcentral.gov:13901'
for identifier in client.list_identifiers :metadata_prefix => 'oai_dc'
  puts identifier.

It is worth noting that the api uses methods and parameter names with underscores in them rather than studly caps. So above list_identifiers and metadata_prefix are used instead of the listIdentifiers and metadataPrefix used in the OAI-PMH specification.

Also, the from and until arguments which specify dates should be passed in as Date or DateTime objects depending on the granularity supported by the server.

For detailed information on the arguments that can be used please consult the OAI-PMH docs at:

http://www.openarchives.org/OAI/openarchivesprotocol.html

Instance Method Summary collapse

Constructor Details

#initialize(base_url, options = {}) ⇒ Client

The constructor which must be passed a valid base url for an oai service:

client = OAI::Client.new 'http://www.pubmedcentral.gov/oai/oai.cgi'

If you want to see debugging messages on STDERR use:

client = OAI::Client.new 'http://example.com', :debug => true

By default OAI verbs called on the client will return REXML::Element objects for metadata records, however if you wish you can use the :parser option to indicate you want to use ‘libxml’ instead, and get back XML::Node objects

client = OAI::Client.new 'http://example.com', :parser => 'libxml'

HIGH PERFORMANCE

If you want to supercharge this api install libxml-ruby >= 0.3.8 and use the :parser option when you construct your OAI::Client.



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/oai/client.rb', line 74

def initialize(base_url, options={})
  @base = URI.parse base_url
  @debug = options.fetch(:debug, false)
  @parser = options.fetch(:parser, 'rexml')
  @follow_redirects = options.fetch(:redirects, true)
  
  # load appropriate parser
  case @parser
  when 'libxml'
    begin
      require 'rubygems'
      require 'xml/libxml'
    rescue
      raise OAI::Exception.new("xml/libxml not available")
    end
  when 'rexml'
    require 'rexml/document'
    require 'rexml/xpath'
  else
    raise OAI::Exception.new("unknown parser: #{@parser}")
  end
end

Instance Method Details

#get_record(opts = {}) ⇒ Object

Equivalent to a GetRecord request. You must supply an identifier argument. You should get back a OAI::GetRecordResponse object which you can extract a OAI::Record object from.



125
126
127
 
# File 'lib/oai/client.rb', line 125

def get_record(opts={})
  return OAI::GetRecordResponse.new(do_request('GetRecord', opts))
end

#identify ⇒ Object

Equivalent to a Identify request. You’ll get back a OAI::IdentifyResponse object which is essentially just a wrapper around a REXML::Document for the response. If you are created your client using the libxml parser then you will get an XML::Node object instead.



102
103
104
 
# File 'lib/oai/client.rb', line 102

def identify
  return OAI::IdentifyResponse.new(do_request('Identify'))
end

#list_identifiers(opts = {}) ⇒ Object

Equivalent to a ListIdentifiers request. Pass in :from, :until arguments as Date or DateTime objects as appropriate depending on the granularity supported by the server.



117
118
119
 
# File 'lib/oai/client.rb', line 117

def list_identifiers(opts={})
  return OAI::ListIdentifiersResponse.new(do_request('ListIdentifiers', opts)) 
end

#list_metadata_formats(opts = {}) ⇒ Object

Equivalent to a ListMetadataFormats request. A ListMetadataFormatsResponse object is returned to you.



109
110
111
 
# File 'lib/oai/client.rb', line 109

def list_metadata_formats(opts={})
  return OAI::ListMetadataFormatsResponse.new(do_request('ListMetadataFormats', opts))
end

#list_records(opts = {}) ⇒ Object

Equivalent to the ListRecords request. A ListRecordsResponse will be returned which you can use to iterate through records

for record in client.list_records
  puts record.metadata
end



136
137
138
 
# File 'lib/oai/client.rb', line 136

def list_records(opts={})
  return OAI::ListRecordsResponse.new(do_request('ListRecords', opts))
end

#list_sets(opts = {}) ⇒ Object

Equivalent to the ListSets request. A ListSetsResponse object will be returned which you can use for iterating through the OAI::Set objects

for set in client.list_sets
  puts set
end



148
149
150
 
# File 'lib/oai/client.rb', line 148

def list_sets(opts={})
  return OAI::ListSetsResponse.new(do_request('ListSets', opts))
end