DBAdaptor.pm 29.7 KB
Newer Older
1
=head1 LICENSE
2

3
  Copyright (c) 1999-2013 The European Bioinformatics Institute and
4
  Genome Research Limited.  All rights reserved.
5

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

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

11
=head1 CONTACT
12

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

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

19
=cut
20

21
=head1 NAME
22

23
Bio::EnsEMBL::DBSQL::DBAdaptor
24

25
=head1 SYNOPSIS
26

27 28 29 30 31 32
  $db = Bio::EnsEMBL::DBSQL::DBAdaptor->new(
    -user   => 'root',
    -dbname => 'pog',
    -host   => 'caldy',
    -driver => 'mysql'
  );
33

34
  $gene_adaptor = $db->get_GeneAdaptor();
35

36
  $gene = $gene_adaptor->fetch_by_stable_id($stable_id);
37

38 39 40 41 42 43 44 45 46 47 48 49 50 51
  $slice =
    $db->get_SliceAdaptor()->fetch_by_chr_start_end( 'X', 1, 10000 );

=head1 DESCRIPTION

Formerly this class provided database connectivity and a means
to retrieve object adaptors.  This class is now provided for
convenience and backwards compatibility, and delegates its connection
responsibilities to the DBConnection class (no longer inherited from)
and its object adaptor retrieval to the static Bio::EnsEMBL::Registry.

Please use Bio::EnsEMBL::Registry to retrieve object adaptors.

=head1 METHODS
52 53 54

=cut

55
package Bio::EnsEMBL::DBSQL::DBAdaptor;
Ian Longden's avatar
Ian Longden committed
56

57 58
use strict;

59
use Bio::EnsEMBL::DBSQL::DBConnection;
60
use Bio::EnsEMBL::DBSQL::BaseFeatureAdaptor;
61
use Bio::EnsEMBL::Utils::SeqRegionCache;
62 63
use Bio::EnsEMBL::Utils::Exception qw(throw warning deprecate);
use Bio::EnsEMBL::Utils::Argument qw(rearrange);
Ian Longden's avatar
Ian Longden committed
64 65
use Bio::EnsEMBL::Registry;
use Bio::EnsEMBL::Utils::ConfigRegistry;
66

67
my $registry = "Bio::EnsEMBL::Registry";
Graham McVicker's avatar
Graham McVicker committed
68 69 70

=head2 new

Ian Longden's avatar
Ian Longden committed
71
  Arg [-DNADB]: (optional) Bio::EnsEMBL::DBSQL::DBAdaptor DNADB 
72 73 74
               All sequence, assembly, contig information etc, will
               be retrieved from this database instead.

75
  Arg [-NO_CACHE]: (optional) int 1
76 77 78 79 80 81 82
               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
83
               not use it or ask in the developer mailing list.
84

Ian Longden's avatar
Ian Longden committed
85 86
  Arg [..]   : Other args are passed to superclass
               Bio::EnsEMBL::DBSQL::DBConnection
87

Ian Longden's avatar
Ian Longden committed
88
  Example    : $db = new Bio::EnsEMBL::DBSQL::DBAdaptor(
89 90 91 92 93 94
                -user   => 'root',
                -dbname => 'pog',
                -host   => 'caldy',
                -driver => 'mysql'
              );

Kieron Taylor's avatar
Kieron Taylor committed
95
              $db = new Bio::EnsEMBL::DBSQL::DBAdaptor(
96
                -species => 'Homo_sapiens',
97 98
                -group   => 'core',
                -user    => 'root',
99 100 101 102
                -dbname  => 'pog',
                -host    => 'caldy',
                -driver  => 'mysql'
              );
103

Kieron Taylor's avatar
Kieron Taylor committed
104
              $db = new Bio::EnsEMBL::DBSQL::DBAdaptor(
105
                -species         => 'staphylococcus_aureus',
106 107
                -group           => 'core',
                -user            => 'root',
108 109 110 111 112
                -dbname          => 'staphylococcus_collection_1_52_1a',
                -multispecies_db => 1,
                -host            => 'caldy',
                -driver          => 'mysql'
              );
113

Ian Longden's avatar
Ian Longden committed
114 115
  Description: Constructor for DBAdaptor.
  Returntype : Bio::EnsEMBL::DBSQL::DBAdaptor
Graham McVicker's avatar
Graham McVicker committed
116 117
  Exceptions : none
  Caller     : general
118
  Status     : Stable
119 120 121

=cut

122
sub new {
123
  my ( $class, @args ) = @_;
124

125
  my $self = bless {}, $class;
Graham McVicker's avatar
Graham McVicker committed
126

Andreas Kusalananda Kähäri's avatar
Andreas Kusalananda Kähäri committed
127
  my ( $is_multispecies, $species, $species_id, $group, $con, $dnadb,
128
    $no_cache, $dbname )
129 130
    = rearrange( [
      'MULTISPECIES_DB', 'SPECIES', 'SPECIES_ID', 'GROUP',
131
      'DBCONN',          'DNADB',   'NO_CACHE',   'DBNAME'
132 133 134
    ],
    @args
    );
135

136 137
  if ( defined($con) ) { $self->dbc($con) }
  else {
138 139 140
    if(! defined $dbname) {
      throw "-DBNAME is a required parameter when creating a DBAdaptor";
    }
141
    $self->dbc( new Bio::EnsEMBL::DBSQL::DBConnection(@args) );
Ian Longden's avatar
Ian Longden committed
142
  }
Ian Longden's avatar
Ian Longden committed
143

144 145 146
  if ( defined($species) ) { $self->species($species) }
  if ( defined($group) )   { $self->group($group) }

147
 
148 149
  $self = Bio::EnsEMBL::Utils::ConfigRegistry::gen_load($self);

Andreas Kusalananda Kähäri's avatar
Andreas Kusalananda Kähäri committed
150
  $self->species_id( $species_id || 1 );
151

152 153 154
  $self->is_multispecies( defined($is_multispecies)
                          && $is_multispecies == 1 );

Andreas Kusalananda Kähäri's avatar
Andreas Kusalananda Kähäri committed
155 156
  if ( defined($dnadb) )    { $self->dnadb($dnadb) }
  if ( defined($no_cache) ) { $self->no_cache($no_cache) }
157

Ian Longden's avatar
Ian Longden committed
158
  return $self;
Andreas Kusalananda Kähäri's avatar
Andreas Kusalananda Kähäri committed
159
} ## end sub new
160

161
=head2 clear_caches
Ian Longden's avatar
Ian Longden committed
162

163 164 165 166 167 168 169 170 171 172 173 174 175 176
  Example			: $dba->clear_caches();
  Description	: Loops through all linked adaptors and clears their 
                caches if C<clear_cache()> is implemented. Not all caches
                are cleared & the DBAdaptor instance should be removed from
                the registry to clear these remaining essential caches. 
  Returntype 	: None
  Exceptions 	: None

=cut

sub clear_caches {
  my ($self) = @_;
  my $adaptors = Bio::EnsEMBL::Registry->get_all_adaptors(
    $self->species(), $self->group());
177
  foreach my $adaptor (@{$adaptors}) {
178 179 180 181 182 183
    if($adaptor->can('clear_cache')) {
      $adaptor->clear_cache();
    }
  }
  return;
}
184

185
=head2 dbc
186

Ian Longden's avatar
Ian Longden committed
187 188
  Arg[1]    : (optional) Bio::EnsEMBL::DBSQL::DBConnection

189
  Example    : $dbc = $dba->dbc();
Ian Longden's avatar
Ian Longden committed
190 191
  Description: Getter/Setter for DBConnection.
  Returntype : Bio::EnsEMBL::DBSQL::DBConnection
192
  Exceptions : throws if argument not a Bio::EnsEMBL::DBSQL::DBConnection
193
  Caller     : general
194
  Status     : Stable
195

196 197
=cut

198
sub dbc{
Ian Longden's avatar
Ian Longden committed
199 200 201 202 203 204 205 206 207 208 209 210
  my $self  = shift;
  
  if(@_){
    my $arg = shift;
    if(defined($arg)){
      if(!$arg->isa('Bio::EnsEMBL::DBSQL::DBConnection')){
	throw("$arg is no a DBConnection\n");
      }
    }
    $self->{_dbc} = $arg;
  }
  return $self->{_dbc};
211 212
}

213

214

Ian Longden's avatar
Ian Longden committed
215
=head2 add_db_adaptor
Ian Longden's avatar
Ian Longden committed
216

Ian Longden's avatar
Ian Longden committed
217 218 219 220 221 222 223 224
  Arg [1]    : string $name
               the name of the database to attach to this database
  Arg [2]    : Bio::EnsEMBL::DBSQL::DBConnection
               the db adaptor to attach to this database
  Example    : $db->add_db_adaptor('lite', $lite_db_adaptor);
  Description: Attaches another database instance to this database so 
               that it can be used in instances where it is required.
  Returntype : none
225
  Exceptions : none
Ian Longden's avatar
Ian Longden committed
226
  Caller     : EnsWeb
227 228
  Status     : At Risk
             : may get deprecated, please use add_db from the registry instead
229 230 231

=cut

Ian Longden's avatar
Ian Longden committed
232 233
sub add_db_adaptor {
  my ($self, $name, $adaptor) = @_;
Ian Longden's avatar
Ian Longden committed
234

Ian Longden's avatar
Ian Longden committed
235 236 237 238 239
  unless($name && $adaptor && ref $adaptor) {
    throw('adaptor and name arguments are required');
  }

  Bio::EnsEMBL::Registry->add_db($self, $name, $adaptor);
240

Ian Longden's avatar
Ian Longden committed
241
}
242

243

Ian Longden's avatar
Ian Longden committed
244
=head2 remove_db_adaptor
Graham McVicker's avatar
Graham McVicker committed
245

Ian Longden's avatar
Ian Longden committed
246 247 248 249 250 251
  Arg [1]    : string $name
               the name of the database to detach from this database.
  Example    : $lite_db = $db->remove_db_adaptor('lite');
  Description: Detaches a database instance from this database and returns
               it.
  Returntype : none
Ian Longden's avatar
Ian Longden committed
252
  Exceptions : none
Ian Longden's avatar
Ian Longden committed
253
  Caller     : ?
254 255
  Status     : At Risk
             : mey get deprecated, use remove_db instead from the Registry
Graham McVicker's avatar
Graham McVicker committed
256 257 258

=cut

Ian Longden's avatar
Ian Longden committed
259 260 261 262
sub remove_db_adaptor {
  my ($self, $name) = @_;

  return Bio::EnsEMBL::Registry->remove_db($self, $name);
263 264 265
}


Ian Longden's avatar
Ian Longden committed
266
=head2 get_all_db_adaptors
267

Ian Longden's avatar
Ian Longden committed
268 269 270 271 272 273 274 275
  Arg [1]    : none
  Example    : @attached_dbs = values %{$db->get_all_db_adaptors()};
  Description: returns all of the attached databases as 
               a hash reference of key/value pairs where the keys are
               database names and the values are the attached databases  
  Returntype : hash reference with Bio::EnsEMBL::DBSQL::DBConnection values
  Exceptions : none
  Caller     : Bio::EnsEMBL::DBSQL::ProxyAdaptor
276 277 278
  Status     : At Risk
             : may get deprecated soon
             : please use  Bio::EnsEMBL::Registry->get_all_db_adaptors
279 280 281

=cut

Ian Longden's avatar
Ian Longden committed
282 283
sub get_all_db_adaptors {
  my ($self) = @_;
284
  return Bio::EnsEMBL::Registry->get_all_db_adaptors($self);
Graham McVicker's avatar
Graham McVicker committed
285 286
}

Ensembl Pipeline's avatar
Ensembl Pipeline committed
287

288

Ian Longden's avatar
Ian Longden committed
289
=head2 get_db_adaptor
290

Ian Longden's avatar
Ian Longden committed
291 292 293 294 295 296
  Arg [1]    : string $name
               the name of the attached database to retrieve
  Example    : $lite_db = $db->get_db_adaptor('lite');
  Description: returns an attached db adaptor of name $name or undef if
               no such attached database exists
  Returntype : Bio::EnsEMBL::DBSQL::DBConnection
297
  Exceptions : none
Ian Longden's avatar
Ian Longden committed
298
  Caller     : ?
299 300 301
  Status     : At Risk
             : may get deprecated soon
             : please use  Bio::EnsEMBL::Registry->get_db_adaptors
302 303 304

=cut

Ian Longden's avatar
Ian Longden committed
305 306
sub get_db_adaptor {
  my ($self, $name) = @_;
307

Ian Longden's avatar
Ian Longden committed
308 309
  return Bio::EnsEMBL::Registry->get_db($self, $name);
}
310

311 312 313 314 315 316 317 318 319 320
=head2 get_available_adaptors

  Example    : my %pairs = %{$dba->get_available_adaptors()};
  Description: gets a hash of the available adaptors
  ReturnType : reference to a hash
  Exceptions : none
  Caller     : Bio::EnsEMBL::Utils::ConfigRegistry
  Status     : Stable

=cut 
321

322 323 324 325 326
sub get_available_adaptors {
  my %pairs = (
    # Firstly those that just have an adaptor named after there object
    # in the main DBSQL directory.
    map( { $_ => "Bio::EnsEMBL::DBSQL::${_}Adaptor" } qw(
327
        Analysis                 ArchiveStableId      Attribute
328 329 330 331
        AssemblyExceptionFeature AssemblyMapper       CoordSystem
        CompressedSequence       DBEntry              DnaAlignFeature
        DensityFeature           DensityType          Exon
        Gene                     KaryotypeBand        MiscSet
332
        MiscFeature              PredictionTranscript PredictionExon
333
        ProteinFeature           ProteinAlignFeature  RepeatConsensus
334
        RepeatFeature            Sequence             SeqRegionSynonym  SimpleFeature
335 336
        Slice                    SupportingFeature    Transcript
        TranscriptSupportingFeature Translation       UnmappedObject
Ian Longden's avatar
Ian Longden committed
337 338
        UnconventionalTranscriptAssociation           AssemblySlice
        SplicingEvent            SplicingEventFeature SplicingTranscriptPair
339
        Operon 			 OperonTranscript
340
        DataFile                 Assembly
341
        IntronSupportingEvidence AltAlleleGroup
342 343
        ) ),
    # Those whose adaptors are in Map::DBSQL
344
    map( { $_ => "Bio::EnsEMBL::Map::DBSQL::${_}Adaptor" } qw(
345 346 347 348 349 350 351 352
        Marker MarkerFeature QtlFeature Qtl Ditag DitagFeature
        ) ),
    # Finally the exceptions... those that have non-standard mapping
    # between object / adaptor ....
    # 'Blast'                => 'Bio::EnsEMBL::External::BlastAdaptor',
    'MetaCoordContainer' => 'Bio::EnsEMBL::DBSQL::MetaCoordContainer',
    'MetaContainer'      => 'Bio::EnsEMBL::DBSQL::MetaContainer',
    'SNP'                => 'Bio::EnsEMBL::DBSQL::ProxySNPAdaptor',
353
  );
354 355 356

  return ( \%pairs );
} ## end sub get_available_adaptors
357

358 359 360 361 362 363
###########################################################
#
# Support for DAS
#
###########################################################

Graham McVicker's avatar
Graham McVicker committed
364 365
=head2 add_DASFeatureFactory

366
  Arg [1]    : Bio::EnsEMBL::ExternalFeatureFactory $value 
Graham McVicker's avatar
Graham McVicker committed
367 368 369 370 371 372 373 374
  Example    : none
  Description: Attaches a DAS Feature Factory to this method.  
               ExternalFeatureFactory objects are not really used right now.
               They may be reintroduced or taken out completely.  The fate
               of this function is unknown (although it is presently needed).
  Returntype : none
  Exceptions : none
  Caller     : EnsWeb
375 376
  Status     : At Risk
             : with the new web code this may not be needed/supported
Graham McVicker's avatar
Graham McVicker committed
377 378 379 380

=cut

sub add_DASFeatureFactory{
Tanya Gray's avatar
Tanya Gray committed
381 382
 
 my ($self,$value) = @_;
Graham McVicker's avatar
Graham McVicker committed
383 384 385 386 387
  
  push(@{$self->{'_das_ff'}},$value);
}


Web Admin's avatar
Web Admin committed
388 389 390
sub remove_all_DASFeatureFactories {
  $_[0]->{'_das_ff'} = [];
}
Graham McVicker's avatar
Graham McVicker committed
391 392 393 394 395 396
=head2 _each_DASFeatureFactory

  Args       : none
  Example    : none
  Description: Not sure if this is used, or if it should be removed.  It 
               does not seem to be used at the moment
397
  Returntype : Bio::EnsEMBL::ExternalFeatureFactory
Graham McVicker's avatar
Graham McVicker committed
398 399
  Exceptions : none
  Caller     : ??
400 401
  Status     : At Risk
             : with the new web code this may not be needed/supported
Graham McVicker's avatar
Graham McVicker committed
402 403 404 405 406 407

=cut

sub _each_DASFeatureFactory{
   my ($self) = @_;

Web Admin's avatar
Web Admin committed
408
   return @{$self->{'_das_ff'}||[]}
Graham McVicker's avatar
Graham McVicker committed
409 410 411
}


412 413
################################################################## 
# 
414
# SUPPORT FOR EXTERNAL FEATURE FACTORIES 
415 416
# 
##################################################################
417

418

419

420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443
=head2 add_ExternalFeatureAdaptor

  Arg [1]    : Bio::EnsEMBL::External::ExternalFeatureAdaptor
  Example    : $db_adaptor->add_ExternalFeatureAdaptor($xfa);
  Description: Adds an external feature adaptor to this database adaptor.
               Adding the external adaptor in this way allows external
               features to be obtained from Slices and from RawContigs.

               The external feature adaptor which is passed to this method
               will have its db attribuite set to this DBAdaptor object via 
               the db accessor method. 

               ExternalFeatureAdaptors passed to this method are stored 
               internally in a hash keyed on the string returned by the 
               ExternalFeatureAdaptors track_name method.
               
               If the track name method is not implemented then the 
               a default key named 'External features' is assigned.  In the
               event of duplicate key names, a number is appended to the
               key name, and incremented for each subsequent adaptor with the
               same track name.  For example, if no track_names are specified 
               then the the external feature adaptors will be stored under the
               keys 'External features', 'External features2' 
               'External features3' etc.
444 445
  Returntype : none
  Exceptions : none
446
  Caller     : general
447
  
448
=cut
449

450 451 452 453 454
sub add_ExternalFeatureAdaptor {
  my ($self, $adaptor) = @_;

  unless($adaptor && ref $adaptor && 
	 $adaptor->isa('Bio::EnsEMBL::External::ExternalFeatureAdaptor')) {
455 456
     throw("[$adaptor] is not a " .
           "Bio::EnsEMBL::External::ExternalFeatureAdaptor");
457
  }
458

459 460 461 462
  unless(exists $self->{'_xf_adaptors'}) {
    $self->{'_xf_adaptors'} = {};
  }

463
  my $track_name = $adaptor->{'_track_name'};
464 465 466
  if(!$track_name) {
    $track_name = $adaptor->track_name();
  }
467 468 469 470 471 472 473

  #use a generic track name if one hasn't been defined
  unless(defined $track_name) {
    $track_name = "External features";
  }

  #if the track name exists add numbers to the end until a free name is found
474
  if(exists $self->{'_xf_adaptors'}->{"$track_name"}) {
475
    my $num = 2;
476
    $num++ while(exists $self->{'_xf_adaptors'}->{"$track_name$num"});
477 478 479 480 481
    $self->{'_xf_adaptors'}->{"$track_name$num"} = $adaptor;
  } else {
    $self->{'_xf_adaptors'}->{"$track_name"} = $adaptor;
  }

482
  $adaptor->ensembl_db($self);
483
}
484

485

486 487

=head2 get_ExternalFeatureAdaptors
488

Graham McVicker's avatar
Graham McVicker committed
489
  Arg [1]    : none
490 491 492 493 494 495 496
  Example    : @xfas = values %{$db_adaptor->get_ExternalFeatureAdaptors}; 
  Description: Retrieves all of the ExternalFeatureAdaptors which have been
               added to this DBAdaptor.  The ExternalFeatureAdaptors are 
               returned in a reference to a hash keyed on the track names
               of the external adaptors
  Returntype : Reference to a hash of ExternalFeatureAdaptors keyed on 
               their track names.
497
  Exceptions : none
498
  Caller     : general
499 500 501

=cut

502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528
sub get_ExternalFeatureAdaptors {
  my $self = shift;

  return $self->{'_xf_adaptors'};
}


=head2 add_ExternalFeatureFactory

  Arg [1]    : Bio::EnsEMBL::DB::ExternalFeatureFactoryI $value
  Example    : $db_adaptor->add_ExternalFeatureFactory
  Description: It is recommended that add_ExternalFeatureAdaptor be used 
               instead.  See documentation for 
               Bio::EnsEMBL::External::ExternalFeatureAdaptor

               Adds an external feature factory to the core database
               so that features from external sources can be displayed in 
               ensembl. This method is still available mainly for legacy
               support for external EnsEMBL installations.
  Returntype : none
  Exceptions : none
  Caller     : external

=cut

sub add_ExternalFeatureFactory{
   my ($self,$value) = @_;
529

530
   $self->add_ExternalFeatureAdaptor($value);
531 532
}

533 534 535 536 537 538 539 540 541
#
# OVERWRITABLE STANDARD ADAPTORS
#

=head2 get_adaptor

  Arg [1]    : Canonical data type for which an adaptor is required.
  Example    : $db_adaptor->get_adaptor("Protein")
  Description: Gets an adaptor object for a standard data type.
Ian Longden's avatar
Ian Longden committed
542 543
  Returntype : Adaptor Object of arbitrary type or undef
  Exceptions : none
544
  Caller     : external
545 546 547 548
  Status     : Medium Risk
             : please use the Registry method, as at some time this
             : may no longer be supprted.
 
549 550
=cut

551
sub get_adaptor {
Ian Longden's avatar
Ian Longden committed
552
  my ($self, $canonical_name, @other_args) = @_;
553

554
  return $registry->get_adaptor($self->species(),$self->group(),$canonical_name);
Ian Longden's avatar
Ian Longden committed
555
}
556

Ian Longden's avatar
Ian Longden committed
557 558


559 560 561
=head2 set_adaptor

  Arg [1]    : Canonical data type for new adaptor.
Kieron Taylor's avatar
Kieron Taylor committed
562
  Arg [2]    : Object defining the adaptor for arg1.
563 564
  Example    : $aa = Bio::EnsEMBL::DBSQL::GeneAdaptor->new($db_adaptor);
             : $db_adaptor->set_adaptor("Gene", $ga)
565 566
  Description: Stores the object which represents the adaptor for the
               arg1 data type.
567
  Returntype : none
Ian Longden's avatar
Ian Longden committed
568
  Exceptions : none
569
  Caller     : external
570 571 572 573
  Status     : Medium Risk
             : please use the Registry method, as at some time this
             : may no longer be supprted.
 
574 575
=cut

576
sub set_adaptor {
Ian Longden's avatar
Ian Longden committed
577
  my ($self, $canonical_name, $module) = @_;
578

579
  $registry->add_adaptor($self->species(),$self->group(),$canonical_name,$module);
580

581
  return $module;
582 583
}

Ian Longden's avatar
Ian Longden committed
584

585 586 587 588 589 590
#
# GENERIC FEATURE ADAPTORS
#

=head2 get_GenericFeatureAdaptors

591 592
  Arg [1]    : List of names of feature adaptors to get. If no
               adaptor names are given, all the defined adaptors are returned.
593
  Example    : $db->get_GenericFeature("SomeFeature", "SomeOtherFeature")
594 595 596
  Description: Returns a hash containing the named feature adaptors (or
               all feature adaptors).
  Returntype : reference to a Hash containing the named
Arne Stabenau's avatar
Arne Stabenau committed
597
               feature adaptors (or all feature adaptors).
598 599 600 601 602
  Exceptions : If any of the the named generic feature adaptors do not exist.
  Caller     : external

=cut

603
sub get_GenericFeatureAdaptors {
604

Arne Stabenau's avatar
Arne Stabenau committed
605
  my ($self, @names) = @_;
606

Arne Stabenau's avatar
Arne Stabenau committed
607
  my %adaptors = ();
608

Arne Stabenau's avatar
Arne Stabenau committed
609 610 611 612 613
  if (!@names) {
    %adaptors = %{$self->{'generic_feature_adaptors'}};
  } else {
    foreach my $name (@names) {
      if (!exists($self->{'generic_feature_adaptors'}->{$name})) {
614
        throw("No generic feature adaptor has been defined for $name" );
Arne Stabenau's avatar
Arne Stabenau committed
615
      }
Ian Longden's avatar
Ian Longden committed
616 617


Arne Stabenau's avatar
Arne Stabenau committed
618 619 620
      $adaptors{$name} = $self->{'generic_feature_adaptors'}->{$name};
    }
  }
621

Arne Stabenau's avatar
Arne Stabenau committed
622
  return \%adaptors;
623 624
}

625

626 627 628 629
=head2 add_GenericFeatureAdaptor

  Arg [1]    : The name of the feature.
  Arg [2]    : Adaptor object for a generic feature.
630 631 632 633
  Example    : $db->add_GenericFeatureAdaptor("SomeFeature",
                              "Bio::EnsEMBL::DBSQL::SomeFeatureAdaptor")
  Description: Stores the object which represents the adaptor for the
               named feature type.
634 635 636 637 638 639
  Returntype : none
  Exceptions :
  Caller     : external

=cut

640
sub add_GenericFeatureAdaptor {
641
  my ($self, $name, $adaptor_obj) = @_;
642
	
643 644 645 646 647
  # check that $adaptor is an object that subclasses BaseFeatureAdaptor	
  if (!$adaptor_obj->isa("Bio::EnsEMBL::DBSQL::BaseFeatureAdaptor")) {
    throw("$name is a " . ref($adaptor_obj) . "which is not a " .
          "subclass of Bio::EnsEMBL::DBSQL::BaseFeatureAdaptor" );
  }
648

649
  $self->{'generic_feature_adaptors'}->{$name} = $adaptor_obj;
650
}
651

652 653
=head2 species

Ian Longden's avatar
Ian Longden committed
654 655 656 657 658 659 660 661 662 663
  Arg [1]    : (optional) string $arg
               The new value of the species used by this DBAdaptor. 
  Example    : $species = $dba->species()
  Description: Getter/Setter for the species of to use for 
               this connection.  There is currently no point in setting 
               this value after the connection has already been established 
               by the constructor.
  Returntype : string
  Exceptions : none
  Caller     : new
664
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
665 666 667 668

=cut

sub species {
669 670 671 672 673 674
  my ( $self, $arg ) = @_;

  if ( defined($arg) ) {
    $self->{_species} = $arg;
  }

Ian Longden's avatar
Ian Longden committed
675 676 677
  $self->{_species};
}

678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704
=head2 all_species

  Args       : NONE
  Example    : @all_species = @{$dba->all_species()};
  Description: Returns the names of all species contained in the
               database to which this DBAdaptor is connected.
  Returntype : array reference
  Exceptions : none
  Caller     : general
  Status     : Stable

=cut

sub all_species {
  my ($self) = @_;

  if ( !$self->is_multispecies() ) { return [ $self->species() ] }

  if ( exists( $self->{'_all_species'} ) ) {
    return $self->{'_all_species'};
  }

  my $statement =
      "SELECT meta_value "
    . "FROM meta "
    . "WHERE meta_key = 'species.db_name'";

705
  my $sth = $self->dbc()->db_handle()->prepare($statement);
706 707 708 709

  $sth->execute();

  my $species;
710
  $sth->bind_columns( \$species );
711 712 713 714 715 716 717 718 719 720

  my @all_species;
  while ( $sth->fetch() ) { push( @all_species, $species ) }

  $self->{'_all_species'} = \@all_species;

  return $self->{'_all_species'};
} ## end sub all_species


721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746
=head2 is_multispecies

  Arg [1]    : (optional) boolean $arg
  Example    : if ($dba->is_multispecies()) { }
  Description: Getter/Setter for the is_multispecies boolean of
               to use for this connection.  There is currently no
               point in setting this value after the connection has
               already been established by the constructor.
  Returntype : boolean
  Exceptions : none
  Caller     : new
  Status     : Stable

=cut

sub is_multispecies {
  my ( $self, $arg ) = @_;

  if ( defined($arg) ) {
    $self->{_is_multispecies} = $arg;
  }

  return $self->{_is_multispecies};
}


747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770
=head2 species_id

  Arg [1]    : (optional) string $arg
               The new value of the species_id used by this DBAdaptor
               when dealing with multi-species databases.
  Example    : $species_id = $dba->species_id()
  Description: Getter/Setter for the species_id of to use for this
               connection.  There is currently no point in setting
               this value after the connection has already been
               established by the constructor.
  Returntype : string
  Exceptions : none
  Caller     : new
  Status     : Stable

=cut

sub species_id {
  my ( $self, $arg ) = @_;

  if ( defined($arg) ) {
    $self->{_species_id} = $arg;
  }

771
  return $self->{_species_id};
772 773
}

Ian Longden's avatar
Ian Longden committed
774

775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803
=head2 no_cache

  Arg [1]    : (optional) int $arg
               The new value of the no cache attribute used by this DBAdaptor. 
  Example    : $no_cache = $dba->no_cache();
  Description: Getter/Setter for the no_cache to use for 
               this connection.  There is currently no point in setting 
               this value after the connection has already been established 
               by the constructor.
  Returntype : int
  Exceptions : none
  Caller     : new
  Status     : Stable

=cut

sub no_cache {
  my ($self, $arg ) = @_;

  if ( defined $arg ){
      if ($arg != 1 && $arg != 0){
	  throw("$arg is not allowed for this attribute. Only value 1|0 is allowed");
      }
      $self->{_no_cache} = $arg;
  }
  $self->{_no_cache};
}


Ian Longden's avatar
Ian Longden committed
804 805 806 807 808 809 810 811 812 813 814 815
=head2 group

  Arg [1]    : (optional) string $arg
               The new value of the group used by this DBAdaptor. 
  Example    : $group = $dba->group()
  Description: Getter/Setter for the group of to use for 
               this connection.  There is currently no point in setting 
               this value after the connection has already been established 
               by the constructor.
  Returntype : string
  Exceptions : none
  Caller     : new
816
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
817 818

=cut
819

Ian Longden's avatar
Ian Longden committed
820 821 822 823 824 825
sub group {
  my ($self, $arg ) = @_;
  ( defined $arg ) &&
    ( $self->{_group} = $arg );
  $self->{_group};
}
826

827 828 829 830 831 832 833 834
=head2 get_SeqRegionCache

  Arg [1]    : none
  Example    : my $srcache = $dba->get_SeqRegionCache();
  Description: Retrieves a seq_region cache for this database
  Returntype : Bio::EnsEMBL::Utils::SeqRegionCache
  Exceptions : none
  Caller     : SliceAdaptor, AssemblyMapperAdaptor
835
  Status     : Stable
836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854

=cut

sub get_SeqRegionCache {
  my $self = shift;

  # use the cache from the database where seq_regions are stored
  if($self != $self->dnadb()) {
    return $self->dnadb()->get_SeqRegionCache();
  }

  if(!$self->{'seq_region_cache'}) {
    $self->{'seq_region_cache'} = Bio::EnsEMBL::Utils::SeqRegionCache->new();
  }

  return $self->{'seq_region_cache'};
}


855

856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874
#convenient method to retrieve the schema_build version for the database being used

sub _get_schema_build{
  my ($self) = @_;

  #avoided using dnadb by default to avoid obfuscation of behaviour
  
  my @dbname = split/_/, $self->dbc->dbname();

  #warn "dbname is $schema_build";

  my $schema_build = pop @dbname;
  $schema_build = pop(@dbname).'_'.$schema_build;


  return $schema_build;
}


Ian Longden's avatar
Ian Longden committed
875 876 877 878 879 880 881 882 883
=head2 dnadb

 Title   : dnadb
 Usage   : my $dnadb = $db->dnadb();
 Function: returns the database adaptor where the dna lives
           Useful if you only want to keep one copy of the dna
           on disk but have other databases with genes and features in
 Returns : dna database adaptor
 Args    : Bio::EnsEMBL::DBSQL::BaseAdaptor
884 885
 Status  : Medium Risk.
         : Use the Registry method add_DNAAdaptor/get_DNAAdaptor instead
Ian Longden's avatar
Ian Longden committed
886 887 888 889 890 891 892 893

=cut

sub dnadb {
  my $self = shift;

  if(@_) {
    my $arg = shift;
894
    $registry->add_DNAAdaptor($self->species(),$self->group(),$arg->species(),$arg->group());
Ian Longden's avatar
Ian Longden committed
895 896 897
  }

#  return $self->{'dnadb'} || $self;
898
  return $registry->get_DNAAdaptor($self->species(),$self->group()) || $self;
Ian Longden's avatar
Ian Longden committed
899 900 901 902 903 904
}


use vars '$AUTOLOAD';

sub AUTOLOAD {
905
  my ( $self, @args ) = @_;
Ian Longden's avatar
Ian Longden committed
906 907

  my $type;
908
  if ( $AUTOLOAD =~ /^.*::get_(\w+)Adaptor$/ ) {
Ian Longden's avatar
Ian Longden committed
909
    $type = $1;
910
  } elsif ( $AUTOLOAD =~ /^.*::get_(\w+)$/ ) {
Ian Longden's avatar
Ian Longden committed
911
    $type = $1;
912 913
  } else {
    throw( sprintf( "Could not work out type for %s\n", $AUTOLOAD ) );
Ian Longden's avatar
Ian Longden committed
914
  }
915
  
916
  my $ret = $registry->get_adaptor( $self->species(), $self->group(), $type );
917

918 919 920 921 922
  return $ret if $ret;
  
  warning( sprintf(
    "Could not find %s adaptor in the registry for %s %s\n",
    $type, $self->species(), $self->group() ) );
Ian Longden's avatar
Ian Longden committed
923

924 925 926
  throw( sprintf( 
    "Could not get adaptor %s for %s %s\n",
    $type, $self->species(), $self->group() ) );
927 928

} ## end sub AUTOLOAD
929

930
sub DESTROY { }    # required due to AUTOLOAD
931

932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955
=head2 to_hash

  Example    : my $hash = $dba->to_hash();
               my $new_dba = $dba->new(%{$hash});
  Description: Provides a hash which is compatible with the 
               parameters for DBAdaptor's new() method. This can be
               useful during serialisation but be aware that Registry
  Returntype : Hash
  Exceptions : none
  Caller     : general
  Status     : New  

=cut

sub to_hash {
  my ($self) = @_;
  my $hash = $self->dbc()->to_hash();
  $hash->{-SPECIES} = $self->species();
  $hash->{-GROUP} = $self->group();
  $hash->{-SPECIES_ID} = $self->species_id();
  $hash->{-MULTISPECIES_DB} = $self->is_multispecies();
  return $hash;
}

956

957
#########################
958
# sub DEPRECATED METHODS
959
#########################
960 961 962 963 964 965 966 967 968 969 970 971
=head2 db
  
  Description: DEPRECATED 
  
=cut

sub db{
  my ($self, $arg ) = @_;
 deprecate("db Should no longer be called from the DBAdaptor. DBConnection should now be used OR preferably the object adaptor itself\n");
 return $self->dbc($arg);
}

972

973
sub source { deprecate('Do not use - this method does nothing'); }
974 975


976
=head2 assembly_type
977

978 979
  Description: DEPRECATED - Use CoordSystemAdaptor to obtain default coordinate
               system instead.
980

981
=cut
982

983 984
sub assembly_type{
  my $self = shift;
985

986
  deprecate('Use CoordSystemAdaptor $csa->fetch_all->[0]->version() instead');
987