Bio/DB/BiblioI.pm

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