Summary

Bio::DB::Registry - Access to the Open Bio Database Access registry scheme

Package variables

Included modules

Inherit

Bio::Root::Root

Synopsis

    use Bio::DB::Registry();

    $registry = new Bio::DB::Registry();

    @available_services = $registry->services;

    $db = $registry->get_database('embl');
    # $db is a Bio::DB::SeqI implementing class

    $seq = $db->get_Seq_by_acc("J02231");

Description

This module provides access to the Open Bio Database Access (OBDA)
scheme, which provides a single cross-language and cross-platform
specification of how to get to databases. These databases may be
accessible through the Web, they may be BioSQL databases, or
they may be local, indexed flatfile databases.
If the user or system administrator has not installed the default init
file, seqdatabase.ini, in /etc/bioinformatics or ${HOME}/.bioinformatics
then creating the first Registry object copies the default settings from
the net. The Registry object will attempt to store these settings in
${HOME}/.bioinformatics/seqdatabase.ini.
Users can specify one or more custom locations for the init file by
setting $OBDA_SEARCH_PATH to those directories, where multiple
directories should be separated by ';'.
Please see the OBDA Access HOWTO for more information
(http://bioperl.org/HOWTOs).

Methods

Methods description

 Title   : _load_registry
 Usage   :
 Function: Looks for seqdatabase.ini files in the expected locations and
           in the directories specified by $OBDA_SEARCH_PATH. If no files
           are found it downloads a default file from www.open-bio.org
 Returns : nothing
 Args    : none

 Title   : get_database
 Usage   : my $db = $registry->get_database($dbname);
 Function: Retrieve a Database object which implements Bio::DB::SeqI interface
 Returns : Bio::DB::SeqI object
 Args    : string describing the name of the database

 Title   : services
 Usage   : my @available = $registry->services();
 Function: returns list of possible services
 Returns : list of strings
 Args    : none

 Title   : _get_ini_files
 Usage   :
 Function: To find all the seqdatabase.ini files
 Returns : list of seqdatabase.ini paths
 Args    : $home

Methods code

BEGIN {

    $OBDA_SPEC_VERSION = 1.0;
    if (defined $ENV{OBDA_SEARCH_PATH}) {
        $OBDA_SEARCH_PATH = $ENV{OBDA_SEARCH_PATH} || '';

}

sub new {

    my ($class,@args) = shift;
    my $self = $class->SUPER::new(@args);
    # open files in order
    $self->{'_dbs'} = {};
    $self->_load_registry();
    return $self;

}

sub _load_registry {

   my ($self) = @_;
   my $home = "";
   defined $ENV{"HOME"} ? $home = $ENV{"HOME"} 
     : $home = (getpwuid($>))[7]; # ActiveState has no getpwuid()
   my @ini_files = _get_ini_files($home);

   unless (@ini_files) {
      $self->warn("No seqdatabase.ini file found in ~/.bioinformatics/\nnor in /etc/bioinformatics/ nor in directory specified by\n$OBDA_SEARCH_PATH. Using web to get database registry from\n$fallbackRegistryURL");

      # Last gasp. Try to use HTTPget module to retrieve the registry from
      # the web...
      my $f = Bio::Root::HTTPget::getFH($fallbackRegistryURL);

      # store the default registry file
      mkdir "$home/.bioinformatics" unless -e "$home/.bioinformatics";
      open(F,">$home/.bioinformatics/seqdatabase.ini");
      print F while (<$f>);
      close F;

      $self->warn("Stored the default registry configuration in\n" .
		  "$home/.bioinformatics/seqdatabase.ini");

      push @ini_files,"$home/.bioinformatics/seqdatabase.ini";
   }

   my ($db,$hash) = ();
   foreach my $file (@ini_files) {
      open FH,"$file";
      while( <FH> ) {
	 if (/^VERSION=([\d\.]+)/) {
	    if ($1 > $OBDA_SPEC_VERSION or !$1) {
	       $self->throw("Do not know about this version [$1] > $OBDA_SPEC_VERSION");
	       last;
	    }
	    next;
         }
	 next if( /^#/ );
	 next if( /^\s/ );
	 if ( /^\[(\w+)\]/ ) {
	    $db = $1;
	    next;
	 }
	 my ($tag,$value) = split('=',$_);
	 $value =~ s/\s//g;
	 $tag =~ s/\s//g;
	 $hash->{$db}->{"\L$tag"} = lc $value;
      }
   }

   foreach my $db( keys %{$hash} ) {
      if ( !exists $self->{'_dbs'}->{$db} ) {
	 my $failover = Bio::DB::Failover->new();
	 $self->{'_dbs'}->{$db} = $failover;
      }
      my $class;
      if (defined $implement{$hash->{$db}->{'protocol'}}) {
	 $class = $implement{$hash->{$db}->{'protocol'}};
      } else {
	 $self->warn("Registry does not support protocol " .
		     $hash->{$db}->{'protocol'});
	 next;
      }
      eval "require $class";
      if ($@) {
	 $self->verbose && $self->warn("Couldn't load $class");
	 next;
      } else {
	 eval {
	    my $randi = $class->new_from_registry( %{$hash->{$db}} );
	    $self->{'_dbs'}->{$db}->add_database($randi); };
	 if ($@) {
	    $self->warn("Couldn't call new_from_registry on [$class]\n$@");
	 }
      }
   }

}

sub get_database {

    my ($self,$dbname) = @_;

    $dbname = lc $dbname;
    if( !defined $dbname ) {
	$self->warn("must get_database with a database name");
	return undef;
    }
    if( !exists $self->{'_dbs'}->{$dbname} ) {
	$self->warn("No database with name $dbname in Registry");
	return undef;
    }
    return $self->{'_dbs'}->{$dbname};

}

sub services {

    my ($self) = @_;
    return () unless ( defined $self->{'_dbs'} &&
		       ref( $self->{'_dbs'} ) =~ /HASH/i);
    return keys %{$self->{'_dbs'}};

}

sub _get_ini_files {

   my $home = shift;
   my @ini_files = ();
   my $file = "";
   if ( $OBDA_SEARCH_PATH ) {
      foreach my $dir ( split /;/,$OBDA_SEARCH_PATH ) {
	 $file = $dir . "/" . "seqdatabase.ini";
	 next unless -e $file;
	 push @ini_files,$file;
      }
   }
   push @ini_files,"$home/.bioinformatics/seqdatabase.ini" 
     if ( -e "$home/.bioinformatics/seqdatabase.ini" );
   push @ini_files,"/etc/bioinformatics/seqdatabase.ini"
     if ( -e "/etc/bioinformatics/seqdatabase.ini" );
   @ini_files;

}

General documentation

Ewan Birney originally wrote this class.

Report bugs to the Bioperl bug tracking system to help us keep track
the bugs and their resolution. Bug reports can be submitted via email
or the web:

    bioperl-bugs@bio.perl.org
    http://bugzilla.bioperl.org/

The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _