Bio/DB/Failover.pm

   1 # $Id$
   2
   3 # POD documentation - main docs before the code
   4
   5 =head1 NAME
   6
   7 Bio::DB::Failover - A Bio::DB::RandomAccessI compliant class which
   8 wraps a prioritized list of DBs
   9
  10 =head1 SYNOPSIS
  11
  12     $failover = Bio::DB::Failover->new();
  13
  14     $failover->add_database($db);
  15
  16     # fail over Bio::DB::RandomAccessI.pm
  17
  18     # this will check each database in priority, returning when
  19     # the first one succeeds
  20
  21     $seq = $failover->get_Seq_by_id($id);
  22
  23 =head1 DESCRIPTION
  24
  25 This module provides fail over access to a set of Bio::DB::RandomAccessI
  26 objects.
  27
  28 =head1 CONTACT
  29
  30 Ewan Birney E<lt>birney@ebi.ac.ukE<gt> originally wrote this class.
  31
  32 =head2 Reporting Bugs
  33
  34 Report bugs to the Bioperl bug tracking system to help us keep track
  35 the bugs and their resolution. Bug reports can be submitted via the
  36 web:
  37
  38   http://bugzilla.open-bio.org/
  39
  40 =head1 APPENDIX
  41
  42 The rest of the documentation details each of the object
  43 methods. Internal methods are usually preceded with a _
  44
  45 =cut
  46
  47 # Let the code begin...
  48
  49 package Bio::DB::Failover;
  50
  51 use strict;
  52
  53 use base qw(Bio::Root::Root Bio::DB::RandomAccessI);
  54
  55 sub new {
  56     my ($class,@args) = @_;
  57
  58     my $self = $class->SUPER::new(@args);
  59
  60     $self->{'_database'} = [];
  61     return $self;
  62 }
  63
  64 =head2 add_database
  65
  66  Title   : add_database
  67  Usage   : add_database(%db)
  68  Function: Adds a database to the Failover object
  69  Returns : Count of number of databases
  70  Args    : Array of db resources
  71  Throws  : Not a RandomAccessI exception
  72
  73 =cut
  74
  75 sub add_database {
  76         my ($self,@db) = @_;
  77         for my $db ( @db ) {
  78                 if ( !ref $db || !$db->isa('Bio::DB::RandomAccessI') ) {
  79                         $self->throw("Database object $db is a not a Bio::DB::RandomAccessI");
  80                         next;
  81                 }
  82
  83                 push(@{$self->{'_database'}},$db);
  84         }
  85         scalar @{$self->{'_database'}};
  86 }
  87
  88
  89 =head2 get_Seq_by_id
  90
  91  Title   : get_Seq_by_id
  92  Usage   : $seq = $db->get_Seq_by_id('ROA1_HUMAN')
  93  Function: Gets a Bio::Seq object by its name
  94  Returns : a Bio::Seq object
  95  Args    : the id (as a string) of a sequence
  96  Throws  : "no id" exception
  97
  98 =cut
  99
 100 sub get_Seq_by_id {
 101         my ($self,$id) = @_;
 102
 103         if( !defined $id ) {
 104                 $self->throw("no id is given!");
 105         }
 106
 107         foreach my $db ( @{$self->{'_database'}} ) {
 108                 my $seq;
 109
 110                 eval {
 111                         $seq = $db->get_Seq_by_id($id);
 112                 };
 113                 $self->warn($@) if $@;
 114                 if ( defined $seq ) {
 115                         return $seq;
 116                 } else {
 117                         $self->warn("No sequence retrieved by database " . ref($db));
 118                 }
 119         }
 120
 121         return;
 122 }
 123
 124 =head2 get_Seq_by_acc
 125
 126  Title   : get_Seq_by_acc
 127  Usage   : $seq = $db->get_Seq_by_acc('X77802');
 128  Function: Gets a Bio::Seq object by accession number
 129  Returns : A Bio::Seq object
 130  Args    : accession number (as a string)
 131  Throws  : "no id" exception
 132
 133 =cut
 134
 135 sub get_Seq_by_acc {
 136         my ($self,$id) = @_;
 137
 138         if( !defined $id ) {
 139                 $self->throw("no id is given!");
 140         }
 141
 142         foreach my $db ( @{$self->{'_database'}} ) {
 143                 my $seq;
 144                 eval {
 145                         $seq = $db->get_Seq_by_acc($id);
 146                 };
 147                 $self->warn($@) if $@;
 148                 if ( defined $seq ) {
 149                         return $seq;
 150                 } else {
 151                         $self->warn("No sequence retrieved by database " . ref($db));
 152                 }
 153         }
 154         return;
 155 }
 156
 157 =head2 get_Seq_by_version
 158
 159  Title   : get_Seq_by_version
 160  Usage   : $seq = $db->get_Seq_by_acc('X77802.2');
 161  Function: Gets a Bio::Seq object by versioned accession number
 162  Returns : A Bio::Seq object
 163  Args    : accession number (as a string)
 164  Throws  : "acc does not exist" exception
 165
 166 =cut
 167
 168 sub get_Seq_by_version {
 169         my ($self,$id) = @_;
 170
 171         if( !defined $id ) {
 172                 $self->throw("no acc is given!");
 173         }
 174
 175         foreach my $db ( @{$self->{'_database'}} ) {
 176                 my $seq;
 177                 eval {
 178                         $seq = $db->get_Seq_by_version($id);
 179                 };
 180                 $self->warn($@) if $@;
 181                 if ( defined $seq ) {
 182                         return $seq;
 183                 } else {
 184                         $self->warn("No sequence retrieved by database " . ref($db));
 185                 }
 186         }
 187         return;
 188 }
 189
 190 ## End of Package
 191
 192 1;
 193
 194 __END__