Bio/DB/ReferenceI.pm

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