Registry.pm 74.6 KB
Newer Older
1
=head1 LICENSE
Ian Longden's avatar
Ian Longden committed
2

3
  Copyright (c) 1999-2011 The European Bioinformatics Institute and
4
5
6
7
8
9
10
11
12
13
  Genome Research Limited.  All rights reserved.

  This software is distributed under a modified Apache license.
  For license details, please see

    http://www.ensembl.org/info/about/code_licence.html

=head1 CONTACT

  Please email comments or questions to the public Ensembl
14
  developers list at <dev@ensembl.org>.
15
16
17
18
19

  Questions may also be sent to the Ensembl help desk at
  <helpdesk@ensembl.org>.

=cut
Ian Longden's avatar
Ian Longden committed
20
21
22
23
24
25
26

=head1 NAME

Bio::EnsEMBL::Registry

=head1 SYNOPSIS

27
  use Bio::EnsEMBL::Registry;
28

29
30
31
32
33
  my $registry = 'Bio::EnsEMBL::Registry';

  $registry->load_all("configuration_file");

  $gene_adaptor = $registry->get_adaptor( 'Human', 'Core', 'Gene' );
Ian Longden's avatar
Ian Longden committed
34
35
36

=head1 DESCRIPTION

37
38
All Adaptors are stored/registered using this module. This module should
then be used to get the adaptors needed.
Ian Longden's avatar
Ian Longden committed
39

40
41
The registry can be loaded from a configuration file using the load_all
method.
Ian Longden's avatar
Ian Longden committed
42

43
44
45
46
If a filename is passed to load_all then this is used.  Else if the
enviroment variable ENSEMBL_REGISTRY is set to the name on an existing
configuration file, then this is used.  Else if the file .ensembl_init
in your home directory exist, it is used.
Ian Longden's avatar
Ian Longden committed
47

48
49
For the Web server ENSEMBL_REGISTRY should be set in SiteDefs.pm.  This
will then be passed on to load_all.
50
51


52
53
54
55
The registry can also be loaded via the method load_registry_from_db
which given a database host will load the latest versions of the Ensembl
databases from it.

56
57
The four types of registries are for db adaptors, dba adaptors, dna
adaptors and the standard type.
Ian Longden's avatar
Ian Longden committed
58
59
60

=head2 db

61
62
These are registries for backwards compatibility and enable the
subroutines to add other adaptors to connections.
Ian Longden's avatar
Ian Longden committed
63

64
65
66
e.g. get_all_db_adaptors, get_db_adaptor, add_db_adaptor,
remove_db_adaptor are the old DBAdaptor subroutines which are now
redirected to the Registry.
Ian Longden's avatar
Ian Longden committed
67
68

So if before we had
69

70
  my $sfa = $self->adaptor()->db()->get_db_adaptor('blast');
Ian Longden's avatar
Ian Longden committed
71
72

We now want to change this to
73

74
75
  my $sfa =
    Bio::EnsEMBL::Registry->get_adaptor( "human", "core", "blast" );
Ian Longden's avatar
Ian Longden committed
76
77
78
79
80
81


=head2 DBA

These are the stores for the DBAdaptors

82
83
The Registry will create all the DBConnections needed now if you set up
the configuration correctly. So instead of the old commands like
Ian Longden's avatar
Ian Longden committed
84

85
86
  my $db           = Bio::EnsEMBL::DBSQL::DBAdaptor->new(...);
  my $exon_adaptor = $db->get_ExonAdaptor;
Ian Longden's avatar
Ian Longden committed
87
88
89

we should now have just

90
91
  my $exon_adaptor =
    Bio::EnsEMBL::Registry->get_adaptor( "human", "core", "exon" );
Ian Longden's avatar
Ian Longden committed
92
93
94
95


=head2 DNA

96
97
98
This is an internal Registry and allows the configuration of a dnadb.
An example here is to set the est database to get its dna data from the
core database.
Ian Longden's avatar
Ian Longden committed
99

100
101
102
  ## set the est db to use the core for getting dna data.
  # Bio::EnsEMBL::Utils::ConfigRegistry->dnadb_add( "Homo Sapiens",
  #   "core", "Homo Sapiens", "est" );
Ian Longden's avatar
Ian Longden committed
103
104
105
106


=head2 adaptors

107
108
This is the registry for all the general types of adaptors like
GeneAdaptor, ExonAdaptor, Slice Adaptor etc.
Ian Longden's avatar
Ian Longden committed
109
110
111

These are accessed by the get_adaptor subroutine i.e.

112
113
  my $exon_adaptor =
    Bio::EnsEMBL::Registry->get_adaptor( "human", "core", "exon" );
Ian Longden's avatar
Ian Longden committed
114
115
116
117
118
119

=head1 METHODS

=cut


120
121

package Bio::EnsEMBL::Registry;
Ian Longden's avatar
Ian Longden committed
122
use strict;
123
use warnings;
Ian Longden's avatar
Ian Longden committed
124

125
use Bio::EnsEMBL::DBSQL::DBAdaptor;
Ian Longden's avatar
Ian Longden committed
126
127
use Bio::EnsEMBL::Utils::Exception qw( deprecate throw warning );
use Bio::EnsEMBL::Utils::Argument qw(rearrange);
128
use Bio::EnsEMBL::Utils::ConfigRegistry;
129
130
use Bio::EnsEMBL::ApiVersion;

131
use DBI qw(:sql_types);
Ian Longden's avatar
Ian Longden committed
132
133
134

use vars qw(%registry_register);

135
136
# This is a map from group names to Ensembl DB adaptors.  Used by
# load_all() and reset_DBAdaptor().
137
my %group2adaptor = (
138
139
140
141
142
143
144
145
146
147
148
149
150
151
      'blast'      => 'Bio::EnsEMBL::External::BlastAdaptor',
      'compara'    => 'Bio::EnsEMBL::Compara::DBSQL::DBAdaptor',
      'core'       => 'Bio::EnsEMBL::DBSQL::DBAdaptor',
      'estgene'    => 'Bio::EnsEMBL::DBSQL::DBAdaptor',
      'funcgen'    => 'Bio::EnsEMBL::Funcgen::DBSQL::DBAdaptor',
      'regulation' => 'Bio::EnsEMBL::Funcgen::DBSQL::DBAdaptor',
      'haplotype' => 'Bio::EnsEMBL::ExternalData::Haplotype::DBAdaptor',
      'hive'      => 'Bio::EnsEMBL::Hive::DBSQL::DBAdaptor',
      'ontology'  => 'Bio::EnsEMBL::DBSQL::OntologyDBAdaptor',
      'otherfeatures' => 'Bio::EnsEMBL::DBSQL::DBAdaptor',
      'pipeline'      => 'Bio::EnsEMBL::Pipeline::DBSQL::DBAdaptor',
      'snp'       => 'Bio::EnsEMBL::ExternalData::SNPSQL::DBAdaptor',
      'variation' => 'Bio::EnsEMBL::Variation::DBSQL::DBAdaptor',
      'vega'      => 'Bio::EnsEMBL::DBSQL::DBAdaptor'
152
);
153
154


Ian Longden's avatar
Ian Longden committed
155
=head2 load_all
156

157
158
 Will load the registry with the configuration file which is
 obtained from the first in the following and in that order.
159

160
161
  1) If an argument is passed to this method, this is used as the
     name of the configuration file to read.
162

163
164
  2) If the enviroment variable ENSEMBL_REGISTRY is set, this is
     used as the name of the configuration file to read.
Ian Longden's avatar
Ian Longden committed
165

166
167
  3) If the file .ensembl_init exist in the home directory, it is
     used as the configuration file.
Ian Longden's avatar
Ian Longden committed
168

169
170
  Arg [1]    : (optional) string
               Name of file to load the registry from.
171

172
173
  Arg [2]    : (optional) integer
               If not 0, will print out all information.
174

175
  Arg [3]    : (optional) integer
176
177
178
179
180
181
182
183
184
185
186
187
               If not 0, the database connection will not be
               cleared, if 0 or if not set the database connections
               will be cleared (this is the default).

  Arg [4]:     (optional) boolean
               This option will turn off caching for slice features,
               so, every time a set of features is retrieved,
               they will come from the database instead of the
               cache.  This option is only recommended for advanced
               users, specially if you need to store and retrieve
               features.  It might reduce performance when querying
               the database if not used properly.  If in doubt, do
188
               not use it or ask in the developer mailing list.
189

Ian Longden's avatar
Ian Longden committed
190
191
192
  Example    : Bio::EnsEMBL::Registry->load_all();
  Returntype : none
  Exceptions : none
193
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
194
195

=cut
196

197
sub load_all {
198
    my ($class, $config_file, $verbose, $no_clear, $no_cache ) = @_;
199

200
201
202
203
204
205
206
    if ( !defined($config_file) ) {
      if ( defined( $ENV{ENSEMBL_REGISTRY} ) ) {
        $config_file = $ENV{ENSEMBL_REGISTRY};
      } elsif ( defined( $ENV{HOME} ) ) {
        $config_file = $ENV{HOME} . "/.ensembl_init";
      }
    }
207
208
209

    $verbose  ||= 0;
    $no_clear ||= 0;
210
    $no_cache ||= 0;
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240

    if ( !defined($config_file) ) {
        if ($verbose) {
            print( STDERR
                   "No default registry configuration to load.\n" );
        }
    } elsif ( !-e $config_file ) {
        if ($verbose) {
            printf( STDERR "Configuration file '%s' does not exist. "
                      . "Registry configuration not loaded.\n",
                    $config_file );
        }
    } else {
        if ( defined( $registry_register{'seen'} ) ) {
            if ( !$no_clear ) {
                if ($verbose) {
                    print( STDERR "Clearing previously loaded "
                           . "registry configuration\n" );
                }
                $class->clear();
            }
        }
        $registry_register{'seen'} = 1;

        if ($verbose) {
            printf( STDERR
                      "Loading registry configuration from '%s'.\n",
                    $config_file );
        }

241
242
        my $cfg;

243
244
245
        my $test_eval = eval { require Config::IniFiles };

        if ($@ or (!$test_eval)) {
246
247
248
249
250
251
252
253
254
255
256
257
          # The user does not have the 'Config::IniFiles' module.
          if ($verbose) {
            print( STDERR "No Config::IniFiles module found, "
                   . "assuming this is not an ini-file\n" );
          }
          # If the configuration file *is* an ini-file, we can expect a
          # load of compilation errors from the next eval...
        } else {
          # The user has the 'Config::IniFiles' module installed.  See
          # if this is an ini-file or not...
          $cfg = Config::IniFiles->new( -file => $config_file );
        }
258

259
        if ( defined $cfg ) {
260
                  my %default_adaptor_args = ();
261
262
263
264

            if ( $cfg->SectionExists('default') ) {
                # The 'default' section is special.  It contain default
                # values that should be implicit to all other section in
265
266
267
268
269
270
271
272
273
274
275
276
277
                # this configuration file.  Aliases are added if there
                # is also a 'species' setting.

                my $alias = $cfg->val( 'default', 'alias' );
                $cfg->delval( 'default', 'alias' );

                my $species = $cfg->val( 'default', 'species' );

                if ( defined($alias) && defined($species) ) {
                    Bio::EnsEMBL::Utils::ConfigRegistry->add_alias(
                                     -species => $species,
                                     -alias => [ split( /\n/, $alias ) ]
                    );
278
                }
279

280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
                %default_adaptor_args =
                  map { '-' . $_ => $cfg->val( 'default', $_ ) }
                  $cfg->Parameters('default');
            }

            foreach my $section ( $cfg->Sections() ) {
                if ( $section eq 'default' )
                {    # We have already done the 'default' section.
                    next;
                }

                my $group = $cfg->val( $section, 'group' )
                  || $cfg->val( 'default', 'group' );

                if ( !defined($group) ) {
                    printf( STDERR "Key 'group' is undefined "
                              . "for configuration section '%s', "
                              . "skipping this section.\n",
                            $section );
                    next;
                }

                my $adaptor = $group2adaptor{ lc($group) };
                if ( !defined($adaptor) ) {
                    printf( STDERR "Unknown group '%s' "
                              . "for configuration section '%s', "
                              . "skipping this section.\n",
                            $group, $section );
                    next;
                }

311
312
313
314
315
                # Handle aliases.  A section must have both an 'alias'
                # setting and a 'species' setting for aliases to be
                # added.  The 'species' setting might be inherited from
                # the 'default' section.

316
317
318
                my $alias = $cfg->val( $section, 'alias' );
                $cfg->delval( $section, 'alias' );

319
320
321
322
323
324
325
326
327
328
329
                my $species = $cfg->val( $section, 'species' )
                  || $cfg->val( 'default', 'species' );

                if ( defined($alias) && defined($species) ) {
                    Bio::EnsEMBL::Utils::ConfigRegistry->add_alias(
                                     -species => $species,
                                     -alias => [ split( /\n/, $alias ) ]
                    );
                }

                # Fill in the adaptor initialization arguments.
330
331
332
                # We trust the user to provide sensible key-value pairs.
                my %adaptor_args = %default_adaptor_args;
                foreach my $parameter ( $cfg->Parameters($section) ) {
333
334
335
336
337
338
339
340
                  $adaptor_args{ '-' . $parameter } =
                    $cfg->val( $section, $parameter );

                  # when set, do not use the feature cache in the
                  # different adaptors
                  if ($no_cache) {
                    $adaptor_args{'-no_cache'} = 1;
                  }
341
342
343
344
345
346
347
348
                }

                if ($verbose) {
                    printf( "Configuring adaptor '%s' "
                              . "for configuration section '%s'...\n",
                            $adaptor, $section );
                }

349
350
                my $test_eval = eval "require $adaptor";
                if ($@ or (!$test_eval)) { die($@) }
351

352
353
354
355
356
357
358
359
                $adaptor->new(%adaptor_args);

            } ## end foreach my $section ( $cfg->Sections...
        } else {
            # This is probably no ini-file but an old style piece
            # of configuration written in Perl.  We need to try to
            # require() it.

360
361
            my $test_eval = eval { require($config_file) };
            if ($@ or (!$test_eval)) { die($@) }
362
363
364
365
366

            # To make the web code avoid doing this again:
            delete $INC{$config_file};
        }
    } ## end else [ if ( !defined($config_file...
367
    return;
368
} ## end sub load_all
369
370

=head2 clear
371

372
373
374
375
376
 Will clear the registry and disconnect from all databases.

  Example    : Bio::EnsEMBL::Registry->clear();
  Returntype : none
  Exceptions : none
377
  Status     : Stable
378
379
380
381
382
383
384
385
386
387
388

=cut

sub clear{
  my ($self);
  
  foreach my $dba (@{$registry_register{'_DBA'}}){
    if($dba->dbc->connected){
      $dba->dbc->db_handle->disconnect();
    }
  }
Ian Longden's avatar
Ian Longden committed
389
  %registry_register = ();
390
  return;
Ian Longden's avatar
Ian Longden committed
391
392
393
}

#
394
# db adaptors. (for backwards compatibility)
Ian Longden's avatar
Ian Longden committed
395
396
397
398
#

=head2 add_db

399
  Arg [1]    : db (DBAdaptor) to add adaptor to.
Ian Longden's avatar
Ian Longden committed
400
401
402
403
404
  Arg [2]    : name of the name to add the adaptor to in the registry.
  Arg [3]    : The adaptor to be added to the registry.
  Example    : Bio::EnsEMBL::Registry->add_db($db, "lite", $dba);
  Returntype : none
  Exceptions : none
405
  Status     : At Risk.
406
407
408
409
             : This is here for backwards compatibility only and may
             : be removed eventually.  Solution is to make sure the
             : db and the adaptor have the same species and the call
             : is then no longer needed.
Ian Longden's avatar
Ian Longden committed
410

411
=cut
Ian Longden's avatar
Ian Longden committed
412

413
414
sub add_db {
  my ( $class, $db, $name, $adap ) = @_;
Ian Longden's avatar
Ian Longden committed
415

416
  if ( lc( $db->species() ) ne lc( $adap->species ) ) {
417
418
    $registry_register{_SPECIES}{ lc( $db->species() ) }
      { lc( $db->group() ) }{'_special'}{ lc($name) } = $adap;
419
  }
420
  return;
Ian Longden's avatar
Ian Longden committed
421
422
423
424
}

=head2 remove_db

425
  Arg [1]    : db (DBAdaptor) to remove adaptor from.
Ian Longden's avatar
Ian Longden committed
426
427
428
429
  Arg [2]    : name to remove the adaptor from in the registry.
  Example    : my $db = Bio::EnsEMBL::Registry->remove_db($db, "lite");
  Returntype : adaptor
  Exceptions : none
430
  Status     : At Risk.
431
432
433
434
             : This is here for backwards compatibility only and may
             : be removed eventually.  Solution is to make sure the
             : db and the adaptor have the same species and the call
             : is then no longer needed.
Ian Longden's avatar
Ian Longden committed
435
436
437

=cut

438
439
440
441
sub remove_db {
  my ( $class, $db, $name ) = @_;

  my $ret =
442
443
    $registry_register{_SPECIES}{ lc( $db->species() ) }
    { lc( $db->group() ) }{'_special'}{ lc($name) };
Ian Longden's avatar
Ian Longden committed
444

445
446
  $registry_register{_SPECIES}{ lc( $db->species() ) }
    { lc( $db->group() ) }{'_special'}{ lc($name) } = undef;
Ian Longden's avatar
Ian Longden committed
447
448
449
450
451
452

  return $ret;
}

=head2 get_db

453
  Arg [1]    : db (DBAdaptor) to get adaptor from.
Ian Longden's avatar
Ian Longden committed
454
455
456
457
  Arg [2]    : name to get the adaptor for in the registry.
  Example    : my $db = Bio::EnsEMBL::Registry->get_db("Human", "core", "lite");
  Returntype : adaptor
  Exceptions : none
458
  Status     : At Risk.
459
460
461
462
             : This is here for backwards compatibility only and may
             : be removed eventually.  Solution is to make sure the
             : db and the adaptor have the same species then call
             : get_DBAdaptor instead.
Ian Longden's avatar
Ian Longden committed
463
464
465

=cut

466
467
sub get_db {
  my ( $class, $db, $name ) = @_;
Ian Longden's avatar
Ian Longden committed
468

469
470
  my $ret = Bio::EnsEMBL::Registry->get_DBAdaptor( lc( $db->species ),
    lc($name) );
471

472
473
  if ( defined($ret) ) { return $ret }

474
  return $registry_register{_SPECIES}{ lc( $db->species() ) }
475
    { lc( $db->group() ) }{'_special'}{ lc($name) };
Ian Longden's avatar
Ian Longden committed
476
477
478
479
}

=head2 get_all_db_adaptors

480
  Arg [1]    : db (DBAdaptor) to get all the adaptors from.
Ian Longden's avatar
Ian Longden committed
481
482
483
  Example    : my $db = Bio::EnsEMBL::Registry->get_all_db_adaptors($db);
  Returntype : adaptor
  Exceptions : none
484
  Status     : At Risk.
485
486
487
488
             : This is here for backwards compatibility only and
             : may be removed eventually.  Solution is to make
             : sure the dbs all have the same species then call
             : get_all_DBAdaptors(-species => "human");
489

Ian Longden's avatar
Ian Longden committed
490
491
492

=cut

493
494
495
sub get_all_db_adaptors {
  my ( $class, $db ) = @_;
  my %ret = ();
Ian Longden's avatar
Ian Longden committed
496

497
498
  # we now also want to add all the DBAdaptors for the same species.
  # as add_db_adaptor does not add if it is from the same species.
Ian Longden's avatar
Ian Longden committed
499

500
501
502
503
  foreach my $dba ( @{ $registry_register{'_DBA'} } ) {
    if ( lc( $dba->species() ) eq lc( $db->species() ) ) {
      $ret{ $dba->group() } = $dba;
    }
Ian Longden's avatar
Ian Longden committed
504
505
  }

506
  foreach my $key (
507
    keys %{
508
509
510
      $registry_register{_SPECIES}
        { $class->get_alias( $db->species() ) }{ lc( $db->group() ) }
        {'_special'} } )
511
512
  {
    $ret{$key} =
513
514
515
      $registry_register{_SPECIES}
      { $class->get_alias( $db->species() ) }{ lc( $db->group() ) }
      {'_special'}{$key};
516
  }
Ian Longden's avatar
Ian Longden committed
517
518

  return \%ret;
519
} ## end sub get_all_db_adaptors
Ian Longden's avatar
Ian Longden committed
520
521
522
523
524
525
526
527
528
529
530
531
532
533


#
# DBAdaptors
#

=head2 add_DBAdaptor

  Arg [1]    : name of the species to add the adaptor to in the registry.
  Arg [2]    : name of the group to add the adaptor to in the registry.
  Arg [3]    : The DBAaptor to be added to the registry.
  Example    : Bio::EnsEMBL::Registry->add_DBAdaptor("Human", "core", $dba);
  Returntype : none
  Exceptions : none
534
535
  caller     : internal
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
536
537
538

=cut

539
540
sub add_DBAdaptor {
  my ( $class, $species, $group, $adap ) = @_;
Ian Longden's avatar
Ian Longden committed
541

542
543
  if ( !( $class->alias_exists($species) ) ) {
    $class->add_alias( $species, $species );
544
545
  }

Ian Longden's avatar
Ian Longden committed
546
547
  $species = $class->get_alias($species);

548
  $registry_register{_SPECIES}{$species}{ lc($group) }{'_DB'} = $adap;
Ian Longden's avatar
Ian Longden committed
549

550
551
552
553
554
555
  if ( !defined( $registry_register{'_DBA'} ) ) {
    my @list = ();
    push( @list, $adap );
    $registry_register{'_DBA'} = \@list;
  } else {
    push( @{ $registry_register{'_DBA'} }, $adap );
Ian Longden's avatar
Ian Longden committed
556
  }
557
  return;
Ian Longden's avatar
Ian Longden committed
558
559
560
561
562
563
564
565
}



=head2 get_DBAdaptor

  Arg [1]    : name of the species to get the adaptor for in the registry.
  Arg [2]    : name of the group to get the adaptor for in the registry.
566
  Arg [3]    : if set will not give warnings when looking for alias.
Ian Longden's avatar
Ian Longden committed
567
568
569
  Example    : $dba = Bio::EnsEMBL::Registry->get_DBAdaptor("Human", "core");
  Returntype : DBAdaptor
  Exceptions : none
570
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
571
572
573

=cut

574
sub get_DBAdaptor {
575
576
  my ( $class, $species, $group, $no_alias_check ) = @_;
  throw 'Species not defined.' if !defined $species;
577

578
579
580
  #if ( !defined($no_alias_check) or !$no_alias_check ) {
  $species = $class->get_alias( $species, $no_alias_check ) || $species;
  #}
581
  return $registry_register{_SPECIES}{$species}{ lc($group) }{'_DB'};
Ian Longden's avatar
Ian Longden committed
582
583
584
585
}

=head2 get_all_DBAdaptors

586
587
588
589
  Arg [SPECIES]: (optional) string 
                  species name to get adaptors for
  Arg [GROUP]  : (optional) string 
                  group name to get adaptors for
590
591
592
593
594
595
596
597
598
  Example      : 
                @dba =
                  @{ Bio::EnsEMBL::Registry->get_all_DBAdaptors() };

                @human_dbas =
                  @{ Bio::EnsEMBL::Registry->get_all_DBAdaptors(
                    -species => 'human'
                  ) };

599
600
  Returntype   : list of DBAdaptors
  Exceptions   : none
601
  Status       : Stable
Ian Longden's avatar
Ian Longden committed
602
603
604

=cut

605
606
607
608
sub get_all_DBAdaptors {
  my ( $class, @args ) = @_;

  my ( $species, $group ) = rearrange( [qw(SPECIES GROUP)], @args );
Ian Longden's avatar
Ian Longden committed
609

610
  if ( defined($species) ) { $species = $class->get_alias($species) }
611

612
  my @ret;
613
  foreach my $dba ( @{ $registry_register{'_DBA'} } ) {
614
615
616
617
    if ( ( !defined($species) || lc($species) eq lc( $dba->species() ) )
      && ( !defined($group) || lc($group) eq lc( $dba->group() ) ) )
    {
      push( @ret, $dba );
618
619
620
621
    }
  }

  return \@ret;
Ian Longden's avatar
Ian Longden committed
622
623
}

624
625
=head2 get_all_DBAdaptors_by_connection

626
  Arg [1]    : DBConnection used to find DBAdaptors
627
  Returntype : reference to list of DBAdaptors
628
629
630
  Exceptions : none
  Example    : @dba = @{ Bio::EnsEMBL::Registry
                  ->get_all_DBAdaptors_by_connection($dbc) };
631
  Status     : Stable
632
633
634

=cut

635
636
637
sub get_all_DBAdaptors_by_connection {
  my ( $self, $dbc_orig ) = @_;

638
639
  my @return;

640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
  foreach my $dba ( @{ $registry_register{'_DBA'} } ) {
    my $dbc = $dba->dbc();

    if (    defined($dbc)
         && $dbc->can('equals')
         && $dbc->equals($dbc_orig) )
    {
      push( @return, $dba );
    }
  }

  return \@return;
}

=head2 get_all_DBAdaptors_by_dbname

  Arg [1]    : string, name of database
  Returntype : reference to list of DBAdaptors
  Exceptions : none
  Example    : @dba = @{ Bio::EnsEMBL::Registry
                  ->get_all_DBAdaptors_by_dbname($dbname) };
  Status     : Stable

=cut

sub get_all_DBAdaptors_by_dbname {
  my ( $self, $dbname ) = @_;

  my @return;

  foreach my $dba ( @{ $registry_register{'_DBA'} } ) {
    my $dbc = $dba->dbc();

    if ( defined($dbc) && $dbc->dbname() eq $dbname ) {
      push( @return, $dba );
675
676
    }
  }
677

678
679
680
  return \@return;
}

681
682
683
684
685
686
687
688
689
690
691
=head2 remove_DBAdaptor

  Arg [1]    : name of the species to get the adaptor for in the registry.
  Arg [2]    : name of the group to get the adaptor for in the registry.
  Example    : $dba = Bio::EnsEMBL::Registry->remove_DBAdaptor("Human", "core");
  Returntype : none
  Exceptions : none
  Status     : At risk

=cut

692
693
sub remove_DBAdaptor {
  my ( $class, $species, $group ) = @_;
694
695

  $species = $class->get_alias($species);
696
697

  delete $registry_register{_SPECIES}{$species}{$group};
698
  # This will remove the DBAdaptor and all the other adaptors
699

700
  # Now remove if from the _DBA array
701
702
  my $index;

703
  foreach my $i ( 0 .. $#{ $registry_register{'_DBA'} } ) {
704
    my $dba = $registry_register{'_DBA'}->[$i];
Nathan Johnson's avatar
Nathan Johnson committed
705

706
707
708
    if ( ( $dba->species eq $species )
      && $dba->group eq $group )
    {
709
710
711
712
      $index = $i;
      last;
    }
  }
713

714
  # Now remove from _DBA cache
715
716
717
  if ( defined($index) ) {
    splice( @{ $registry_register{'_DBA'} }, $index, 1 );
  }
Nathan Johnson's avatar
Nathan Johnson committed
718

719
  return;
720
} ## end sub remove_DBAdaptor
721

722

Nathan Johnson's avatar
Nathan Johnson committed
723
724
725
726
727
728
729

=head2 reset_DBAdaptor

  Arg [1]:     string - species e.g. homo_sapiens
  Arg [2]:     string - DB group e.g. core
  Arg [3]:     string - new dbname
  Args [4-7]:  string - optional DB parameters, defaults to current db params if omitted
730
  Arg [8]:     hashref - Hash ref of additional parameters e.g. eFG dnadb params for auto selecting dnadb
731
732
  Usage :      $reg->reset_registry_db( 'homo_sapiens', 'core',
                  'homo_sapiens_core_37_35j' );
Nathan Johnson's avatar
Nathan Johnson committed
733
734
735
736
737
738
739
740
  Description: Resets a DB within the registry.
  Exceptions:  Throws if mandatory params not supplied
               Throws if species name is not already seen by the registry
               Throws if no current DB for species/group available
  Status :     At risk

=cut

741
742
743
744
745
sub reset_DBAdaptor {
  my (
    $self, $species, $group, $dbname, $host,
    $port, $user,    $pass,  $params
  ) = @_;
Nathan Johnson's avatar
Nathan Johnson committed
746

747
  # Check mandatory params
748
749
750
751
  if ( !( defined $species && defined $group && defined $dbname ) ) {
    throw(
      'Must provide at least a species, group, and dbname parameter '
        . 'to redefine a DB in the registry' );
Nathan Johnson's avatar
Nathan Johnson committed
752
  }
753

754
  # Validate species here
Nathan Johnson's avatar
Nathan Johnson committed
755
  my $alias = $self->get_alias($species);
756
757
758
  throw("Could not find registry alias for species:\t$species")
    if ( !defined $alias );

759
  # Get all current defaults if not defined
Nathan Johnson's avatar
Nathan Johnson committed
760

761
  my $db = $self->get_DBAdaptor( $alias, $group );
762
  my $class;
Nathan Johnson's avatar
Nathan Johnson committed
763

764
765
766
767
768
769
770
771
772
  if ($db) {
    $class = ref($db);
    $host ||= $db->dbc->host;
    $port ||= $db->dbc->port;
    $user ||= $db->dbc->username;
    $pass ||= $db->dbc->password;
  } else {
    #Now we need to test mandatory params
    $class = $group2adaptor{ lc($group) };
773

774
775
776
777
    if ( !( $host && $user ) ) {
      throw("No comparable $alias $group DB present in Registry. "
          . "You must pass at least a dbhost and dbuser" );
    }
778
  }
Nathan Johnson's avatar
Nathan Johnson committed
779

780
  $self->remove_DBAdaptor( $alias, $group );
Nathan Johnson's avatar
Nathan Johnson committed
781

782
  # ConfigRegistry should automatically add this to the Registry
783
  $db = $class->new(
784
785
786
787
788
789
790
791
    -user    => $user,
    -host    => $host,
    -port    => $port,
    -pass    => $pass,
    -dbname  => $dbname,
    -species => $alias,
    -group   => $group,
    %{$params} );
Nathan Johnson's avatar
Nathan Johnson committed
792
793

  return $db;
794
} ## end sub reset_DBAdaptor
Nathan Johnson's avatar
Nathan Johnson committed
795
796


Ian Longden's avatar
Ian Longden committed
797
798
799
800
801
802
803
804
#
# DNA Adaptors
#

=head2 add_DNAAdaptor

  Arg [1]    : name of the species to add the adaptor to in the registry.
  Arg [2]    : name of the group to add the adaptor to in the registry.
805
806
807
  Arg [3]    : name of the species to get the dna from
  Arg [4]    : name of the group to get the dna from
  Example    : Bio::EnsEMBL::Registry->add_DNAAdaptor("Human", "estgene", "Human", "core");
Ian Longden's avatar
Ian Longden committed
808
809
  Returntype : none
  Exceptions : none
810
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
811
812
813

=cut

814
815
sub add_DNAAdaptor {
  my ( $class, $species, $group, $dnadb_species, $dnadb_group ) = @_;
Ian Longden's avatar
Ian Longden committed
816

817
  $species       = $class->get_alias($species);
818
  $dnadb_species = $class->get_alias($dnadb_species);
819
  if ( $dnadb_group->isa('Bio::EnsEMBL::DBSQL::DBAdaptor') ) {
Ian Longden's avatar
Ian Longden committed
820
    deprecated("");
821
  } else {
822
823
824
    $registry_register{_SPECIES}{$species}{ lc($group) }{'_DNA'} =
      $dnadb_group;
    $registry_register{_SPECIES}{$species}{ lc($group) }{'_DNA2'} =
825
      $dnadb_species;
826
  }
827
  return;
Ian Longden's avatar
Ian Longden committed
828
829
830
831
832
833
834
835
836
}

=head2 get_DNAAdaptor

  Arg [1]    : name of the species to get the adaptor for in the registry.
  Arg [2]    : name of the group to get the adaptor for in the registry.
  Example    : $dnaAdap = Bio::EnsEMBL::Registry->get_DNAAdaptor("Human", "core");
  Returntype : adaptor
  Exceptions : none
837
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
838
839
840

=cut

841
842
sub get_DNAAdaptor {
  my ( $class, $species, $group ) = @_;
Ian Longden's avatar
Ian Longden committed
843
844

  $species = $class->get_alias($species);
845
846
847
848
  my $new_group =
    $registry_register{_SPECIES}{$species}{ lc($group) }{'_DNA'};
  my $new_species =
    $registry_register{_SPECIES}{$species}{ lc($group) }{'_DNA2'};
849
850
851

  if ( defined $new_group ) {
    return $class->get_DBAdaptor( $new_species, $new_group );
852
  }
853

854
  return;
Ian Longden's avatar
Ian Longden committed
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
}

#
# General Adaptors
#

=head2 add_adaptor

  Arg [1]    : name of the species to add the adaptor to in the registry.
  Arg [2]    : name of the group to add the adaptor to in the registry.
  Arg [3]    : name of the type to add the adaptor to in the registry.
  Arg [4]    : The DBAaptor to be added to the registry.
  Arg [5]    : (optional) if set okay to overwrite.
  Example    : Bio::EnsEMBL::Registry->add_adaptor("Human", "core", "Gene", $adap);
  Returntype : none
  Exceptions : none
871
872
  Caller     : internal
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
873
874
875

=cut

876
877
sub add_adaptor {
  my ( $class, $species, $group, $type, $adap, $reset ) = @_;
Ian Longden's avatar
Ian Longden committed
878
879
880

  $species = $class->get_alias($species);

881
882
883
884
885
  # Since the adaptors are not stored initially, only their class paths
  # when the adaptors are obtained, we need to store these instead.  It
  # is not necessarily an error if the registry is overwritten without
  # the reset set but it is an indication that we are overwriting a
  # database which should be a warning for now
Ian Longden's avatar
Ian Longden committed
886

887
888
  if ( defined($reset) )
  {    # JUST REST THE HASH VALUE NO MORE PROCESSING NEEDED
889
890
    $registry_register{_SPECIES}{$species}{ lc($group) }{ lc($type) } =
      $adap;
Ian Longden's avatar
Ian Longden committed
891
892
    return;
  }
893

894
  if (
895
896
897
    defined(
      $registry_register{_SPECIES}{$species}{ lc($group) }{ lc($type) }
    ) )
898
899
900
  {
  # print STDERR (
  #      "Overwriting Adaptor in Registry for $species $group $type\n");
901
902
    $registry_register{_SPECIES}{$species}{ lc($group) }{ lc($type) } =
      $adap;
903
    return;
Ian Longden's avatar
Ian Longden committed
904
  }
905
906
  $registry_register{_SPECIES}{$species}{ lc($group) }{ lc($type) } =
    $adap;
Ian Longden's avatar
Ian Longden committed
907

908
909
  if ( !defined( $registry_register{_SPECIES}{$species}{'list'} ) ) {
    $registry_register{_SPECIES}{$species}{'list'} = [$type];
910
  } else {
911
    push( @{ $registry_register{_SPECIES}{$species}{'list'} }, $type );
Ian Longden's avatar
Ian Longden committed
912
913
  }

914
915
  if ( !defined( $registry_register{_TYPE}{ lc($type) }{$species} ) ) {
    $registry_register{_TYPE}{ lc($type) }{$species} = [$type];
916
  } else {
917
918
    push( @{ $registry_register{_TYPE}{ lc($type) }{$species} },
      $adap );
Ian Longden's avatar
Ian Longden committed
919
  }
920
  return;
921
} ## end sub add_adaptor
Ian Longden's avatar
Ian Longden committed
922
923
924
925
926
927
928
929
930
931


=head2 get_adaptor

  Arg [1]    : name of the species to add the adaptor to in the registry.
  Arg [2]    : name of the group to add the adaptor to in the registry.
  Arg [3]    : name of the type to add the adaptor to in the registry.
  Example    : $adap = Bio::EnsEMBL::Registry->get_adaptor("Human", "core", "Gene");
  Returntype : adaptor
  Exceptions : none
932
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
933
934
935

=cut

936
937
sub get_adaptor {
  my ( $class, $species, $group, $type ) = @_;
Glenn Proctor's avatar
Typos.    
Glenn Proctor committed
938

939
940
  my $ispecies = $class->get_alias($species);

941
  if ( !defined($ispecies) ) {
942
943
944
    throw("Can not find internal name for species '$species'");
  }
  else { $species = $ispecies }
Glenn Proctor's avatar
Typos.    
Glenn Proctor committed
945

946
947
948
949
950
951
952
953
  my %dnadb_adaptors = (
    'sequence'                 => 1,
    'assemblymapper'           => 1,
    'karyotypeband'            => 1,
    'repeatfeature'            => 1,
    'coordsystem'              => 1,
    'assemblyexceptionfeature' => 1
  );
954

955
  # warn "$species, $group, $type";
956
957
958

  $type = lc($type);

959
960
961
962
  # For historical reasons, allow use of group 'regulation' to refer to
  # group 'funcgen'.
  if ( lc($group) eq 'regulation' ) { $group = 'funcgen' }

963
964
  my $dnadb_group =
    $registry_register{_SPECIES}{$species}{ lc($group) }{'_DNA'};
965

966
967
968
  if ( defined($dnadb_group)
    && defined( $dnadb_adaptors{ lc($type) } ) )
  {
969
970
971
    $species =
      $registry_register{_SPECIES}{$species}{ lc($group) }{'_DNA2'};
    $group = $dnadb_group;
Ian Longden's avatar
Ian Longden committed
972
973
  }

974
975
976
  my $ret =
    $registry_register{_SPECIES}{$species}{ lc($group) }{ lc($type) };

977
  if ( !defined($ret) ) { return }
978
  if ( ref($ret) )      { return $ret }
979

980
  # Not instantiated yet
Ian Longden's avatar
Ian Longden committed
981

982
  my $dba = $registry_register{_SPECIES}{$species}{ lc($group) }{'_DB'};
983
984
  my $module = $ret;

985
986
  my $test_eval = eval "require $module";
  if ($@ or (!$test_eval)) {
987
    warning("'$module' cannot be found.\nException $@\n");
988
    return;
Ian Longden's avatar
Ian Longden committed
989
990
  }

991
  if (
992
993
994
    !defined(
      $registry_register{_SPECIES}{$species}{ lc($group) }{'CHECKED'} )
    )
995
  {
996
    $registry_register{_SPECIES}{$species}{ lc($group) }{'CHECKED'} = 1;
997
998
999
1000
1001
    $class->version_check($dba);
  }

  my $adap = "$module"->new($dba);
  Bio::EnsEMBL::Registry->add_adaptor( $species, $group, $type, $adap,
1002
                                       'reset' );
1003
1004
  $ret = $adap;

Ian Longden's avatar
Ian Longden committed
1005
  return $ret;
1006
} ## end sub get_adaptor
Ian Longden's avatar
Ian Longden committed
1007
1008
1009

=head2 get_all_adaptors

1010
1011
1012
1013
1014
1015
  Arg [SPECIES] : (optional) string 
                  species name to get adaptors for
  Arg [GROUP] : (optional) string 
                  group name to get adaptors for
  Arg [TYPE] : (optional) string 
                  type to get adaptors for
Ian Longden's avatar
Ian Longden committed
1016
  Example    : @adaps = @{Bio::EnsEMBL::Registry->get_all_adaptors()};
1017
  Returntype : ref to list of adaptors
Ian Longden's avatar
Ian Longden committed
1018
  Exceptions : none
1019
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
1020
1021
1022
1023

=cut

sub get_all_adaptors{
1024
1025
1026
1027
  my ($class,@args)= @_;
  my ($species, $group, $type);
  my @ret=();
  my (%species_hash, %group_hash, %type_hash);
Ian Longden's avatar
Ian Longden committed
1028

1029

1030
  if(@args == 1){ # Old species only one parameter
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
    warn("-SPECIES argument should now be used to get species adaptors");
    $species = $args[0];
  }
  else{
    # new style -SPECIES, -GROUP, -TYPE
    ($species, $group, $type) =
      rearrange([qw(SPECIES GROUP TYPE)], @args);
  }

  if(defined($species)){
    $species_hash{$species} = 1;
  }
  else{
    # get list of species
    foreach my $dba (@{$registry_register{'_DBA'}}){
      $species_hash{lc($dba->species())} = 1;
    }
  }
  if(defined($group)){
    $group_hash{$group} = 1;
  }
  else{
    foreach my $dba (@{$registry_register{'_DBA'}}){
      $group_hash{lc($dba->group())} = 1;
    }
  }
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066

  if ( defined($type) ) {
    $type_hash{$type} = 1;
  } else {
    foreach my $dba ( @{ $registry_register{'_DBA'} } ) {
      foreach my $ty (
        @{ $registry_register{_SPECIES}{ lc( $dba->species ) }{'list'} }
        )
      {
        $type_hash{ lc($ty) } = 1;
1067
      }
1068
    }
1069
  }
1070

1071
  ### NOW NEED TO INSTANTIATE BY CALLING get_adaptor
1072
1073
1074
1075
1076
1077
1078
  foreach my $sp ( keys %species_hash ) {
    foreach my $gr ( keys %group_hash ) {
      foreach my $ty ( keys %type_hash ) {
        my $temp = $class->get_adaptor( $sp, $gr, $ty );
        if ( defined($temp) ) {
          push @ret, $temp;
        }
1079
1080
1081
      }
    }
  }
1082

1083
  return (\@ret);
Ian Longden's avatar
Ian Longden committed
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
}


=head2 add_alias

  Arg [1]    : name of the species to add alias for
  Arg [2]    : name of the alias
  Example    : Bio::EnsEMBL::Registry->add_alias("Homo Sapiens","Human");
  Description: add alternative name for the species.
  Returntype : none
  Exceptions : none
1095
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
1096
1097
1098
1099
1100
1101

=cut

sub add_alias{
  my ($class, $species,$key) = @_;

1102
  $registry_register{'_ALIAS'}{lc($key)} = lc($species);
1103
  return;
Ian Longden's avatar
Ian Longden committed
1104
1105
}

1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
=head2 remove_alias

  Arg [1]    : name of the species to remove alias for
  Arg [2]    : name of the alias
  Example    : Bio::EnsEMBL::Registry->remove_alias("Homo Sapiens","Human");
  Description: remove alternative name for the species.
  Returntype : none
  Exceptions : none
  Status     : Stable

=cut

sub remove_alias{
  my ($class, $species,$key) = @_;

  delete $registry_register{'_ALIAS'}{lc($key)};
1122
  return;
1123
1124
1125
1126
}



Ian Longden's avatar
Ian Longden committed
1127
1128
1129
1130
1131
1132
=head2 get_alias

  Arg [1]    : name of the possible alias to get species for
  Example    : Bio::EnsEMBL::Registry->get_alias("Human");
  Description: get proper species name.
  Returntype : species name
1133
  Exceptions : none
1134
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
1135
1136
1137

=cut

1138
1139
sub get_alias {
  my ( $class, $key, $no_warn ) = @_;
Ian Longden's avatar
Ian Longden committed
1140

1141
1142
1143
1144
1145
1146
1147
  if ( !defined( $registry_register{'_ALIAS'}{ lc($key) } ) ) {
    if ( ( !defined( $registry_register{_SPECIES}{ lc($key) } ) ) and
         ( !defined( $registry_register{_ALIAS}{ lc($key) } ) ) )
    {
      if ( ( !defined($no_warn) ) or ( !$no_warn ) ) {
        warn "$key is not a valid species name for this instance\n";
      }
1148
      return;
1149
    }
1150
    else { return $key }
Ian Longden's avatar
Ian Longden committed
1151