|
26 | 26 |
|
27 | 27 | module OAI |
28 | 28 |
|
29 | | - # A OAI::Client provides a client api for issuing OAI-PMH verbs against |
| 29 | + # A `OAI::Client` provides a client api for issuing OAI-PMH verbs against |
30 | 30 | # a OAI-PMH server. The 6 OAI-PMH verbs translate directly to methods you |
31 | | - # can call on a OAI::Client object. Verb arguments are passed as a hash: |
| 31 | + # can call on a `OAI::Client` object. Verb arguments are passed as a hash: |
32 | 32 | # |
| 33 | + # ```ruby |
33 | 34 | # client = OAI::Client.new 'http://www.pubmedcentral.gov/oai/oai.cgi' |
34 | 35 | # record = client.get_record :identifier => 'oai:pubmedcentral.gov:13901' |
35 | 36 | # for identifier in client.list_identifiers |
36 | 37 | # puts identifier |
37 | 38 | # end |
| 39 | + # ``` |
38 | 40 | # |
39 | | - # It is worth noting that the api uses methods and parameter names with |
40 | | - # underscores in them rather than studly caps. So above list_identifiers |
41 | | - # and metadata_prefix are used instead of the listIdentifiers and |
42 | | - # metadataPrefix used in the OAI-PMH specification. |
| 41 | + # It is worth noting that the API uses methods and parameter names with |
| 42 | + # underscores in them rather than studly caps. So above `list_identifiers` |
| 43 | + # and `metadata_prefix` are used instead of the `listIdentifiers` and |
| 44 | + # `metadataPrefix` used in the OAI-PMH specification. |
43 | 45 | # |
44 | 46 | # Also, the from and until arguments which specify dates should be passed |
45 | | - # in as Date or DateTime objects depending on the granularity supported |
| 47 | + # in as `Date` or `DateTime` objects depending on the granularity supported |
46 | 48 | # by the server. |
47 | 49 | # |
48 | 50 | # For detailed information on the arguments that can be used please consult |
49 | | - # the OAI-PMH docs at: |
50 | | - # |
51 | | - # http://www.openarchives.org/OAI/openarchivesprotocol.html |
| 51 | + # the OAI-PMH docs at |
| 52 | + # <http://www.openarchives.org/OAI/openarchivesprotocol.html>. |
52 | 53 |
|
53 | 54 | class Client |
54 | 55 |
|
55 | 56 | # The constructor which must be passed a valid base url for an oai |
56 | 57 | # service: |
57 | 58 | # |
58 | | - # client = OAI::Client.new 'http://www.pubmedcentral.gov/oai/oai.cgi' |
| 59 | + # client = OAI::Client.new 'http://www.pubmedcentral.gov/oai/oai.cgi' |
59 | 60 | # |
60 | | - # If you want to see debugging messages on STDERR use: |
| 61 | + # If you want to see debugging messages on `STDERR` use: |
61 | 62 | # |
62 | | - # client = OAI::Client.new 'http://example.com', :debug => true |
| 63 | + # client = OAI::Client.new 'http://example.com', :debug => true |
63 | 64 | # |
64 | | - # By default OAI verbs called on the client will return REXML::Element |
| 65 | + # By default OAI verbs called on the client will return `REXML::Element` |
65 | 66 | # objects for metadata records, however if you wish you can use the |
66 | | - # :parser option to indicate you want to use 'libxml' instead, and get |
67 | | - # back XML::Node objects |
| 67 | + # `:parser` option to indicate you want to use `libxml` instead, and get |
| 68 | + # back `XML::Node` objects |
68 | 69 | # |
69 | | - # client = OAI::Client.new 'http://example.com', :parser => 'libxml' |
| 70 | + # client = OAI::Client.new 'http://example.com', :parser => 'libxml' |
70 | 71 | # |
71 | 72 | # You can configure the Faraday HTTP client by providing an alternate |
72 | 73 | # Faraday instance: |
73 | 74 | # |
74 | | - # client = OAI::Client.new 'http://example.com', :http => Faraday.new { |c| } |
| 75 | + # ```ruby |
| 76 | + # client = OAI::Client.new 'http://example.com', :http => Faraday.new {|c|} |
| 77 | + # ``` |
75 | 78 | # |
76 | | - # === HIGH PERFORMANCE |
| 79 | + # ### HIGH PERFORMANCE |
77 | 80 | # |
78 | | - # If you want to supercharge this api install libxml-ruby >= 0.3.8 and |
79 | | - # use the :parser option when you construct your OAI::Client. |
| 81 | + # If you want to supercharge this api install `libxml-ruby >= 0.3.8` and |
| 82 | + # use the `:parser` option when you construct your `OAI::Client`. |
80 | 83 | # |
81 | 84 | def initialize(base_url, options={}) |
82 | 85 | @base = URI.parse base_url |
@@ -113,57 +116,80 @@ def initialize(base_url, options={}) |
113 | 116 | end |
114 | 117 | end |
115 | 118 |
|
116 | | - # Equivalent to a Identify request. You'll get back a OAI::IdentifyResponse |
117 | | - # object which is essentially just a wrapper around a REXML::Document |
118 | | - # for the response. If you created your client using the libxml |
119 | | - # parser then you will get an XML::Node object instead. |
120 | | - |
| 119 | + # Equivalent to a `Identify` request. |
| 120 | + # You'll get back a `OAI::IdentifyResponse` |
| 121 | + # object which is essentially just a wrapper around a `REXML::Document` |
| 122 | + # for the response. If you created your client using the `libxml` |
| 123 | + # parser then you will get an `XML::Node` object instead. |
121 | 124 | def identify |
122 | 125 | OAI::IdentifyResponse.new(do_request('Identify')) |
123 | 126 | end |
124 | 127 |
|
125 | | - # Equivalent to a ListMetadataFormats request. A ListMetadataFormatsResponse |
126 | | - # object is returned to you. |
| 128 | + # Equivalent to a `ListMetadataFormats` request. |
| 129 | + # A `ListMetadataFormatsResponse` object is returned to you. |
127 | 130 |
|
128 | 131 | def list_metadata_formats(opts={}) |
129 | 132 | OAI::ListMetadataFormatsResponse.new(do_request('ListMetadataFormats', opts)) |
130 | 133 | end |
131 | 134 |
|
132 | | - # Equivalent to a ListIdentifiers request. Pass in :from, :until arguments |
133 | | - # as Date or DateTime objects as appropriate depending on the granularity |
134 | | - # supported by the server. |
135 | | - |
| 135 | + # Equivalent to a `ListIdentifiers` request. Pass in `:from`, |
| 136 | + # `:until` arguments as `Date` or `DateTime` objects as appropriate |
| 137 | + # depending on the granularity supported by the server. |
| 138 | + # |
| 139 | + # You can use seamless resumption with this verb, which allows you to |
| 140 | + # mitigate (to some extent) the lack of a `Count` verb: |
| 141 | + # |
| 142 | + # client.list_identifiers.full.count # Don't try this on PubMed though! |
| 143 | + # |
136 | 144 | def list_identifiers(opts={}) |
137 | 145 | do_resumable(OAI::ListIdentifiersResponse, 'ListIdentifiers', opts) |
138 | 146 | end |
139 | 147 |
|
140 | | - # Equivalent to a GetRecord request. You must supply an identifier |
141 | | - # argument. You should get back a OAI::GetRecordResponse object |
142 | | - # which you can extract a OAI::Record object from. |
143 | | - |
| 148 | + # Equivalent to a `GetRecord` request. You must supply an `:identifier` |
| 149 | + # argument. You should get back a `OAI::GetRecordResponse` object |
| 150 | + # which you can extract a `OAI::Record` object from. |
144 | 151 | def get_record(opts={}) |
145 | 152 | OAI::GetRecordResponse.new(do_request('GetRecord', opts)) |
146 | 153 | end |
147 | 154 |
|
148 | | - # Equivalent to the ListRecords request. A ListRecordsResponse |
| 155 | + # Equivalent to the `ListRecords` request. A `ListRecordsResponse` |
149 | 156 | # will be returned which you can use to iterate through records |
150 | 157 | # |
151 | | - # for record in client.list_records |
152 | | - # puts record.metadata |
153 | | - # end |
154 | | - |
| 158 | + # response = client.list_records |
| 159 | + # response.each do |record| |
| 160 | + # puts record.metadata |
| 161 | + # end |
| 162 | + # |
| 163 | + # Alternately, you can use seamless resumption to avoid handling |
| 164 | + # resumption tokens: |
| 165 | + # |
| 166 | + # client.list_records.full.each do |record| |
| 167 | + # puts record.metadata |
| 168 | + # end |
| 169 | + # |
| 170 | + # ### Memory Use |
| 171 | + # `:full` will avoid storing more than one page of records in |
| 172 | + # memory, but your use it in ways that override that behaviour. Be careful |
| 173 | + # to avoid using `client.list_records.full.entries` unless you really want |
| 174 | + # to hold all the records in the feed in memory! |
155 | 175 | def list_records(opts={}) |
156 | 176 | do_resumable(OAI::ListRecordsResponse, 'ListRecords', opts) |
157 | 177 | end |
158 | 178 |
|
159 | | - # Equivalent to the ListSets request. A ListSetsResponse object |
| 179 | + # Equivalent to the `ListSets` request. A `ListSetsResponse` object |
160 | 180 | # will be returned which you can use for iterating through the |
161 | | - # OAI::Set objects |
| 181 | + # `OAI::Set` objects |
162 | 182 | # |
163 | | - # for set in client.list_sets |
164 | | - # puts set |
165 | | - # end |
166 | | - |
| 183 | + # for set in client.list_sets |
| 184 | + # puts set |
| 185 | + # end |
| 186 | + # |
| 187 | + # A large number of sets is not unusual for some OAI-PMH feeds, so |
| 188 | + # using seamless resumption may be preferable: |
| 189 | + # |
| 190 | + # client.list_sets.full.each do |set| |
| 191 | + # puts set |
| 192 | + # end |
167 | 193 | def list_sets(opts={}) |
168 | 194 | do_resumable(OAI::ListSetsResponse, 'ListSets', opts) |
169 | 195 | end |
|
0 commit comments