Bio/DB/Failover.pm

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