Bio/DB/ReferenceI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::DB::ReferenceI
   4 #
   5 # Cared for by Chris Fields <cjfields at uiuc dot edu>
   6 #
   7 # Copyright Chris Fields
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10 #
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::DB::ReferenceI - A RandomAccessI-like abstract interface for
  16 retrieving Reference data from a sequence database and returning
  17 Bio::Annotation::Reference objects
  18
  19 =head1 SYNOPSIS
  20
  21   #
  22   # get a database object somehow using a concrete class
  23   #
  24
  25   $ref = $db->get_Reference_by_id('123456');
  26
  27   #
  28   # $ref is a Bio::Annotation::Reference object
  29   #
  30
  31 =head1 DESCRIPTION
  32
  33 This is a pure interface class - in other words, all this does is define
  34 methods which other (concrete) classes will actually implement.
  35
  36 The Bio::DB::ReferenceI class defines methods used to retrieve reference data
  37 from a sequence.  This is returned in the form of Bio::Annotation::Reference
  38 objects.
  39
  40 At the moment it is just the ability to make Bio::Annotation::Reference
  41 objects from a name or unique id (id), an accession number (acc), and so on.
  42
  43 =head1 CONTACT
  44
  45 Ewan Birney originally wrote Bio::DB::RandomAccessI, from which this class
  46 is based.
  47
  48 =head2 Mailing Lists
  49
  50 User feedback is an integral part of the
  51 evolution of this and other Bioperl modules. Send
  52 your comments and suggestions preferably to one
  53 of the Bioperl mailing lists. Your participation
  54 is much appreciated.
  55
  56   bioperl-l@lists.open-bio.org               - General discussion
  57   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
  58
  59 =head2 Reporting Bugs
  60
  61 Report bugs to the Bioperl bug tracking system to
  62 help us keep track the bugs and their resolution.
  63 Bug reports can be submitted via the web.
  64
  65   http://bugzilla.open-bio.org/
  66
  67 =head1 AUTHOR
  68
  69 Email cjfields at uiuc dot edu
  70
  71 =head1 APPENDIX
  72
  73 The rest of the documentation details each of the
  74 object methods. Internal methods are usually
  75 preceded with a _
  76
  77 =cut
  78
  79 # Let the code begin...
  80
  81 package Bio::DB::ReferenceI;
  82
  83 use strict;
  84
  85 =head2 get_Reference_by_id
  86
  87  Title   : get_Reference_by_id
  88  Usage   : $ref = $db->get_Reference_by_id('123456')
  89  Function: Gets a Bio::Annotation::Reference-implementing object by its name (id)
  90  Returns : a Bio::Annotation::Reference object or undef if not found
  91  Args    : the id (as a string) of a sequence
  92
  93 =cut
  94
  95 sub get_Reference_by_id{
  96    my ($self,@args) = @_;
  97    $self->throw_not_implemented();
  98 }
  99
 100 =head2 get_Reference_by_acc
 101
 102  Title   : get_Reference_by_acc
 103  Usage   : $ref = $db->get_Reference_by_acc('X77802');
 104  Function: Gets a Bio::Annotation::Reference object by accession number
 105  Returns : A Bio::Annotation::Reference object or undef if not found
 106  Args    : accession number (as a string)
 107  Throws  : "more than one sequences correspond to this accession"
 108             if the accession maps to multiple primary ids and
 109             method is called in a scalar context
 110
 111 =cut
 112
 113 sub get_Reference_by_acc{
 114    my ($self,@args) = @_;
 115    $self->throw_not_implemented();
 116 }
 117
 118 =head2 get_Reference_by_version
 119
 120  Title   : get_Reference_by_version
 121  Usage   : $ref = $db->get_Reference_by_version('X77802.1');
 122  Function: Gets a Bio::Annotation::Reference object by sequence version
 123  Returns : A Bio::Annotation::Reference object
 124  Args    : accession.version (as a string)
 125  Throws  : "acc.version does not exist" exception
 126
 127 =cut
 128
 129 sub get_Reference_by_version{
 130    my ($self,@args) = @_;
 131    $self->throw_not_implemented();
 132 }
 133
 134 ## End of Package
 135
 136 1;