branch-1-6/Bio/DB/LocationI.pm

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