|
0
|
1 # $Id: BiblioI.pm,v 1.5 2002/10/22 07:45:13 lapp Exp $
|
|
|
2 #
|
|
|
3 # BioPerl module for Bio::DB::BiblioI
|
|
|
4 #
|
|
|
5 # Cared for by Martin Senger <senger@ebi.ac.uk>
|
|
|
6 # For copyright and disclaimer see below.
|
|
|
7 #
|
|
|
8
|
|
|
9 # POD documentation - main docs before the code
|
|
|
10
|
|
|
11 =head1 NAME
|
|
|
12
|
|
|
13 Bio::DB::BiblioI - An interface to a Bibliographic Query Service
|
|
|
14
|
|
|
15 =head1 SYNOPSIS
|
|
|
16
|
|
|
17 This is an interface module - you do not instantiate it.
|
|
|
18 Use I<Bio::Biblio> module:
|
|
|
19
|
|
|
20 use Bio::Biblio;
|
|
|
21 my $biblio = new Bio::Biblio (@args);
|
|
|
22
|
|
|
23 =head1 DESCRIPTION
|
|
|
24
|
|
|
25 This interface describes the methods for accessing a bibliographic
|
|
|
26 repository, for quering it and for retrieving citations from it. The
|
|
|
27 retrieved citations are in XML format and can be converted to perl
|
|
|
28 objects using I<Bio::Biblio::IO>.
|
|
|
29
|
|
|
30 The interface complies (with some simplifications) with the
|
|
|
31 specification described in the B<OpenBQS> project. Its home page is at
|
|
|
32 http://industry.ebi.ac.uk/openBQS
|
|
|
33
|
|
|
34 =head1 FEEDBACK
|
|
|
35
|
|
|
36 =head2 Mailing Lists
|
|
|
37
|
|
|
38 User feedback is an integral part of the evolution of this and other
|
|
|
39 Bioperl modules. Send your comments and suggestions preferably to
|
|
|
40 the Bioperl mailing list. Your participation is much appreciated.
|
|
|
41
|
|
|
42 bioperl-l@bioperl.org - General discussion
|
|
|
43 http://bioperl.org/MailList.shtml - About the mailing lists
|
|
|
44
|
|
|
45 =head2 Reporting Bugs
|
|
|
46
|
|
|
47 Report bugs to the Bioperl bug tracking system to help us keep track
|
|
|
48 of the bugs and their resolution. Bug reports can be submitted via
|
|
|
49 email or the web:
|
|
|
50
|
|
|
51 bioperl-bugs@bioperl.org
|
|
|
52 http://bugzilla.bioperl.org/
|
|
|
53
|
|
|
54 =head1 AUTHOR
|
|
|
55
|
|
|
56 Martin Senger (senger@ebi.ac.uk)
|
|
|
57
|
|
|
58 =head1 COPYRIGHT
|
|
|
59
|
|
|
60 Copyright (c) 2002 European Bioinformatics Institute. All Rights Reserved.
|
|
|
61
|
|
|
62 This module is free software; you can redistribute it and/or modify
|
|
|
63 it under the same terms as Perl itself.
|
|
|
64
|
|
|
65 =head1 DISCLAIMER
|
|
|
66
|
|
|
67 This software is provided "as is" without warranty of any kind.
|
|
|
68
|
|
|
69 =head1 APPENDIX
|
|
|
70
|
|
|
71 This is actually the main documentation...
|
|
|
72
|
|
|
73 If you try to call any of these methods directly on this
|
|
|
74 Bio::DB::BiblioI object you will get a I<not implemented> error
|
|
|
75 message. You need to call them on a Bio::Biblio object.
|
|
|
76
|
|
|
77 =cut
|
|
|
78
|
|
|
79
|
|
|
80 # Let the code begin...
|
|
|
81
|
|
|
82 package Bio::DB::BiblioI;
|
|
|
83 use vars qw(@ISA $VERSION $Revision);
|
|
|
84 use strict;
|
|
|
85 use Bio::Root::RootI;
|
|
|
86
|
|
|
87 @ISA = qw(Bio::Root::RootI);
|
|
|
88
|
|
|
89 BEGIN {
|
|
|
90 $VERSION = do { my @r = (q$Revision: 1.5 $ =~ /\d+/g); sprintf "%d.%-02d", @r };
|
|
|
91 $Revision = q$Id: BiblioI.pm,v 1.5 2002/10/22 07:45:13 lapp Exp $;
|
|
|
92 }
|
|
|
93
|
|
|
94 # -----------------------------------------------------------------------------
|
|
|
95
|
|
|
96 =head2 get_collection_id
|
|
|
97
|
|
|
98 Usage : my $collection_id = $biblio->get_collection_id;
|
|
|
99 Returns : string identifying a query collection
|
|
|
100 represented by the $biblio object
|
|
|
101 Args : none
|
|
|
102
|
|
|
103 Every query collection is uniquely identify-able by its collection
|
|
|
104 ID. The returned value can be used to populate another $biblio object
|
|
|
105 and then to access that collection.
|
|
|
106
|
|
|
107 =cut
|
|
|
108
|
|
|
109 sub get_collection_id {
|
|
|
110 my ($self,@args) = @_;
|
|
|
111 $self->throw_not_implemented();
|
|
|
112 }
|
|
|
113
|
|
|
114
|
|
|
115 # -----------------------------------------------------------------------------
|
|
|
116
|
|
|
117 =head2 get_count
|
|
|
118
|
|
|
119 Usage : my $count = $biblio->get_count;
|
|
|
120 Returns : integer
|
|
|
121 Args : none, or a string identifying a query collection
|
|
|
122
|
|
|
123 It returns a number of citations in the query collection represented
|
|
|
124 by the calling $biblio object, or in the collection whose ID is given
|
|
|
125 as an argument.
|
|
|
126
|
|
|
127 =cut
|
|
|
128
|
|
|
129 sub get_count { shift->throw_not_implemented(); }
|
|
|
130
|
|
|
131 # -----------------------------------------------------------------------------
|
|
|
132
|
|
|
133 =head2 find
|
|
|
134
|
|
|
135 Usage : my $new_biblio = $biblio->find ($keywords, $attrs);
|
|
|
136 my $new_biblio = $biblio->find ('perl', 'abstract');
|
|
|
137 my $new_biblio = $biblio->find ( [ 'perl', 'Java' ] );
|
|
|
138 Returns : new Bio::Biblio object representing a new query
|
|
|
139 collection
|
|
|
140 Args : $keywords - what to look for (mandatory)
|
|
|
141 - a comma-delimited list of keywords, or
|
|
|
142 - an array reference with keywords as elements
|
|
|
143 $attrs - where to look in (optional)
|
|
|
144 - a comma-delimited list of attribute names, or
|
|
|
145 - an array reference with attribute names as elements
|
|
|
146
|
|
|
147 This is the main query method. It looks for the $keywords in a default
|
|
|
148 set of attributes, or - if $attrs given - only in the given
|
|
|
149 attributes.
|
|
|
150
|
|
|
151 Because it returns a new Bio::Biblio object which can be again queried
|
|
|
152 it is possible to chain together several invocations:
|
|
|
153
|
|
|
154 $biblio->find ('Brazma')->find ('Robinson')->get_collection_id;
|
|
|
155
|
|
|
156 =cut
|
|
|
157
|
|
|
158 sub find { shift->throw_not_implemented; }
|
|
|
159
|
|
|
160 # -----------------------------------------------------------------------------
|
|
|
161
|
|
|
162 # TBD: AFAIK this method is not implemented on the server side.
|
|
|
163 # Let's comment it out for the time being...
|
|
|
164 #sub query { shift->throw_not_implemented(); }
|
|
|
165
|
|
|
166 # -----------------------------------------------------------------------------
|
|
|
167
|
|
|
168 =head2 reset_retrieval
|
|
|
169
|
|
|
170 Usage : $biblio->reset_retrieval;
|
|
|
171 Returns : nothing
|
|
|
172 Args : none
|
|
|
173
|
|
|
174 It sets an iterator stored in the $biblio object back to its
|
|
|
175 beginning. After this, the retrieval methods I<has_next>, I<get_next>
|
|
|
176 and I<get_more> start to iterate the underlying query collection
|
|
|
177 again from its start.
|
|
|
178
|
|
|
179 It throws an exception if this object does not represent any query
|
|
|
180 result (e.i. it does not contain a collection ID). Note that a
|
|
|
181 collection ID is created automatically when this object was returned
|
|
|
182 by a I<find> method, or it can be assigned in a constructor using
|
|
|
183 argument I<-collection_id>.
|
|
|
184
|
|
|
185 =cut
|
|
|
186
|
|
|
187 sub reset_retrieval { shift->throw_not_implemented; }
|
|
|
188
|
|
|
189 # -----------------------------------------------------------------------------
|
|
|
190
|
|
|
191 =head2 get_next
|
|
|
192
|
|
|
193 Usage : my $citation = $biblio->get_next;
|
|
|
194 Returns : a citation in an XML format
|
|
|
195 Args : none
|
|
|
196
|
|
|
197 It returns the next available citation from the underlying query
|
|
|
198 collection. It throws an exception if there are no more citations. In
|
|
|
199 order to avoid this use it together with the I<has_next> method:
|
|
|
200
|
|
|
201 my $result = $biblio->find ('brazma', 'authors');
|
|
|
202 while ( $result->has_next ) {
|
|
|
203 print $result->get_next;
|
|
|
204 }
|
|
|
205
|
|
|
206 It also throws an exception if this object does not represent any
|
|
|
207 query result - see explanation in the I<reset_retrieval> elsewhere in
|
|
|
208 this document.
|
|
|
209
|
|
|
210 =cut
|
|
|
211
|
|
|
212 sub get_next { shift->throw_not_implemented; }
|
|
|
213
|
|
|
214 # -----------------------------------------------------------------------------
|
|
|
215
|
|
|
216 =head2 get_more
|
|
|
217
|
|
|
218 Usage : my $r_citations = $biblio->get_more (5);
|
|
|
219 Returns : an array reference - each element has a citation
|
|
|
220 in an XML format
|
|
|
221 Args : an integer 'how_many' citations to return;
|
|
|
222 default is 1 - but it is assigned with warning
|
|
|
223
|
|
|
224 It returns the next I<how_many> available citations from the
|
|
|
225 underlying query collection. It does not throw any exception if
|
|
|
226 'how_many' is more than currently available - it simply returns
|
|
|
227 less. However, it throws an exception if used again without calling
|
|
|
228 first I<reset_retrieval>.
|
|
|
229
|
|
|
230 It also throws an exception if this object does not represent any
|
|
|
231 query result - see explanation in method I<reset_retrieval> elsewhere
|
|
|
232 in this document.
|
|
|
233
|
|
|
234 =cut
|
|
|
235
|
|
|
236 sub get_more { shift->throw_not_implemented; }
|
|
|
237
|
|
|
238 # -----------------------------------------------------------------------------
|
|
|
239
|
|
|
240 =head2 has_next
|
|
|
241
|
|
|
242 Usage : my $is = $biblio->has_next;
|
|
|
243 Returns : 1 or undef
|
|
|
244 Args : none
|
|
|
245
|
|
|
246 It returns 1 if there is a next citation available in the underlying
|
|
|
247 query collection. Otherwise it returns undef.
|
|
|
248
|
|
|
249 It throws an exception if this object does not represent any query
|
|
|
250 result - see explanation in method I<reset_retrieval> elsewhere in
|
|
|
251 this document.
|
|
|
252
|
|
|
253 =cut
|
|
|
254
|
|
|
255 sub has_next { shift->throw_not_implemented; }
|
|
|
256
|
|
|
257 # -----------------------------------------------------------------------------
|
|
|
258
|
|
|
259 =head2 get_all_ids
|
|
|
260
|
|
|
261 Usage : my $r_ids = $biblio->get_all_ids;
|
|
|
262 Returns : an array reference - each element has
|
|
|
263 a citation identifier
|
|
|
264 Args : none
|
|
|
265
|
|
|
266 The identifiers of all citations in the underlying query collection
|
|
|
267 are returned. A usual pattern is to use them then in the I<get_by_id>
|
|
|
268 method:
|
|
|
269
|
|
|
270 my $biblio = $repository->find ('brazma')->find ('robinson');
|
|
|
271 foreach my $id ( @{ $biblio->get_all_ids } ) {
|
|
|
272 print $biblio->get_by_id ($id);
|
|
|
273 }
|
|
|
274
|
|
|
275 It throws an exception if this object does not represent any query
|
|
|
276 result - see explanation in method I<reset_retrieval> elsewhere in
|
|
|
277 this document.
|
|
|
278
|
|
|
279 =cut
|
|
|
280
|
|
|
281 sub get_all_ids { shift->throw_not_implemented; }
|
|
|
282
|
|
|
283 # -----------------------------------------------------------------------------
|
|
|
284
|
|
|
285 =head2 get_by_id
|
|
|
286
|
|
|
287 Usage : my $citation = $biblio->get_by_id ('94033980');
|
|
|
288 Returns : a citation in an XML format
|
|
|
289 Args : a citation identifier
|
|
|
290 (e.g. for MEDLINE it is a MedlineID
|
|
|
291 - at least for the time being)
|
|
|
292
|
|
|
293 It returns a citation - disregarding if the citation is or is not in
|
|
|
294 the underlying query collection (of course, it must be in the
|
|
|
295 repository).
|
|
|
296
|
|
|
297 =cut
|
|
|
298
|
|
|
299 sub get_by_id { shift->throw_not_implemented; }
|
|
|
300
|
|
|
301 # -----------------------------------------------------------------------------
|
|
|
302
|
|
|
303 =head2 get_all
|
|
|
304
|
|
|
305 Usage : my $all = $biblio->get_all;
|
|
|
306 Returns : a (big) string with all citations in an XML format
|
|
|
307 Args : none
|
|
|
308
|
|
|
309 It returns an XML valid string (which means that individual citations
|
|
|
310 are also surrounded by a "set" XML tag) representing all citations
|
|
|
311 from the underlying query collection.
|
|
|
312
|
|
|
313 Note that some servers may limit the number of citations which can be
|
|
|
314 returned by this method. In such case you need either to refine
|
|
|
315 further your query collection (using I<find> method) or to retrieve
|
|
|
316 results by iteration (methods I<has_next>, I<get_next>, I<get_more>).
|
|
|
317
|
|
|
318 It throws an exception if this object does not represent any query
|
|
|
319 result - see explanation in method I<reset_retrieval> elsewhere in
|
|
|
320 this document.
|
|
|
321
|
|
|
322 =cut
|
|
|
323
|
|
|
324 sub get_all { shift->throw_not_implemented; }
|
|
|
325
|
|
|
326 # -----------------------------------------------------------------------------
|
|
|
327
|
|
|
328 =head2 exists
|
|
|
329
|
|
|
330 Usage : my $exists = $biblio->exists;
|
|
|
331 Returns : 1 or undef
|
|
|
332 Args : none
|
|
|
333
|
|
|
334 It returns 1 if the underlying query collection represented by the
|
|
|
335 $biblio object still exists (on the server side).
|
|
|
336
|
|
|
337 If you have a collection ID (e.g. stored or printed in a previous
|
|
|
338 session) but you do not have anymore a C<Bio::Biblio> object representing
|
|
|
339 it this is how you can check the collection existence:
|
|
|
340
|
|
|
341 use Bio::Biblio;
|
|
|
342 print
|
|
|
343 new Bio::Biblio (-collection_id => '1014324148861')->exists;
|
|
|
344
|
|
|
345 It throws an exception if this object does not represent any query
|
|
|
346 result - see explanation in method I<reset_retrieval> elsewhere in
|
|
|
347 this document.
|
|
|
348
|
|
|
349 =cut
|
|
|
350
|
|
|
351 sub exists { shift->throw_not_implemented; }
|
|
|
352
|
|
|
353 # -----------------------------------------------------------------------------
|
|
|
354
|
|
|
355 =head2 destroy
|
|
|
356
|
|
|
357 Usage : $biblio->destroy;
|
|
|
358 Returns : nothing
|
|
|
359 Args : none
|
|
|
360
|
|
|
361 It sends a message to the remote server to forget (or free, or destroy
|
|
|
362 - whatever server choose to do) the query collection represented by
|
|
|
363 this object.
|
|
|
364
|
|
|
365 It throws an exception if this object does not represent any query
|
|
|
366 collection.
|
|
|
367
|
|
|
368 =cut
|
|
|
369
|
|
|
370 sub destroy { shift->throw_not_implemented; }
|
|
|
371
|
|
|
372 # -----------------------------------------------------------------------------
|
|
|
373
|
|
|
374 =head2 get_vocabulary_names
|
|
|
375
|
|
|
376 Usage : print join ("\n", @{ $biblio->get_vocabulary_names });
|
|
|
377 Returns : an array reference - each element has a name
|
|
|
378 of a controlled vocabulary
|
|
|
379 Args : none
|
|
|
380
|
|
|
381 The controlled vocabularies allow to introspect bibliographic
|
|
|
382 repositories and to find what citation resource types (such as journal
|
|
|
383 and book articles, patents or technical reports) are provided by the
|
|
|
384 repository, what attributes they have, eventually what attribute
|
|
|
385 values are allowed.
|
|
|
386
|
|
|
387 This method returns names of all available controlled
|
|
|
388 vocabularies. The names can than be used in other methods dealing with
|
|
|
389 vocabularies: I<contains>, I<get_entry_description>,
|
|
|
390 I<get_all_values>, and I<get_all_entries>.
|
|
|
391
|
|
|
392 =cut
|
|
|
393
|
|
|
394 sub get_vocabulary_names { shift->throw_not_implemented; }
|
|
|
395
|
|
|
396 # -----------------------------------------------------------------------------
|
|
|
397
|
|
|
398 =head2 contains
|
|
|
399
|
|
|
400 Usage : my $yes = $biblio->contains ($vocabulary_name, $value);
|
|
|
401 Returns : 1 or undef
|
|
|
402 Args : $vocabulary_name defines a vocabulary where to look,
|
|
|
403 and a $value defines what to look for
|
|
|
404
|
|
|
405 It returns 1 if the given controlled vocabulary contains the given
|
|
|
406 value.
|
|
|
407
|
|
|
408 For example, when you know, that a vocabulary
|
|
|
409 C<MEDLINE/JournalArticle/properties> contains value C<COUNTRY> you can
|
|
|
410 use it in the I<find> method:
|
|
|
411
|
|
|
412 $biblio->find ('United States', 'COUNTRY');
|
|
|
413
|
|
|
414 =cut
|
|
|
415
|
|
|
416 sub contains { shift->throw_not_implemented; }
|
|
|
417
|
|
|
418 # -----------------------------------------------------------------------------
|
|
|
419
|
|
|
420 =head2 get_entry_description
|
|
|
421
|
|
|
422 Usage : $biblio->get_entry_description ($voc_name, $value);
|
|
|
423 Returns : a string with a desciption
|
|
|
424 Args : $voc_name defines a vocabulary where to look,
|
|
|
425 and a $value defines whose description to return
|
|
|
426
|
|
|
427 Each vocabulary entry has its value (mandatory attribute), and can
|
|
|
428 have a description (optional attribute). The description may be just a
|
|
|
429 human readable explanation of an attribute, or it can have more exact
|
|
|
430 meaning. For example, the server implementation of the bibliographic
|
|
|
431 query service provided by the EBI puts into attribute descriptions
|
|
|
432 words I<queryable> and/or I<retrievable> to distinguish the role of
|
|
|
433 the attributes.
|
|
|
434
|
|
|
435 It throws an exception if either vocabulary or value do not exist.
|
|
|
436
|
|
|
437 =cut
|
|
|
438
|
|
|
439 sub get_entry_description { shift->throw_not_implemented; }
|
|
|
440
|
|
|
441 # -----------------------------------------------------------------------------
|
|
|
442
|
|
|
443 =head2 get_all_values
|
|
|
444
|
|
|
445 Usage : $biblio->get_all_values ($vocabulary_name);
|
|
|
446 Returns : an array reference - each element has a value (scalar)
|
|
|
447 from the given controlled vocabulary
|
|
|
448 Args : $vocabulary_name defines a vocabulary whose values
|
|
|
449 are being returned
|
|
|
450
|
|
|
451 It returns all values of the given vocabulary. It throws an exception
|
|
|
452 if the vocabulary does not exist.
|
|
|
453
|
|
|
454 =cut
|
|
|
455
|
|
|
456 sub get_all_values { shift->throw_not_implemented; }
|
|
|
457
|
|
|
458 # -----------------------------------------------------------------------------
|
|
|
459
|
|
|
460 =head2 get_all_entries
|
|
|
461
|
|
|
462 Usage : $biblio->get_all_entries ($vocabulary_name);
|
|
|
463 Returns : a hash reference - keys are vocabulary values
|
|
|
464 and values are their descriptions
|
|
|
465 Args : $vocabulary_name defines a vocabulary whose entries
|
|
|
466 are being returned
|
|
|
467
|
|
|
468 It returns pairs of values and their descriptions of the whole
|
|
|
469 vocabulary. It throws an exception if the vocabulary does not exist.
|
|
|
470
|
|
|
471 This is one way how to get it and print it:
|
|
|
472
|
|
|
473 my $name = 'MEDLINE2002/JournalArticle/properties';
|
|
|
474 use Data::Dumper;
|
|
|
475 print Data::Dumper->Dump ( [$biblio->get_all_entries ($name)],
|
|
|
476 ['All entries']);
|
|
|
477
|
|
|
478 =cut
|
|
|
479
|
|
|
480 sub get_all_entries { shift->throw_not_implemented; }
|
|
|
481
|
|
|
482 # -----------------------------------------------------------------------------
|
|
|
483
|
|
|
484 =head2 VERSION and Revision
|
|
|
485
|
|
|
486 Usage : print $Bio::DB::BiblioI::VERSION;
|
|
|
487 print $Bio::DB::BiblioI::Revision;
|
|
|
488
|
|
|
489 =cut
|
|
|
490
|
|
|
491 1;
|
|
|
492 __END__
|
|
|
493
|
