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

Magali Ruffier's avatar
Magali Ruffier committed
3
Copyright [1999-2015] Wellcome Trust Sanger Institute and the EMBL-European Bioinformatics Institute
Tiago Grego's avatar
Tiago Grego committed
4
Copyright [2016-2019] EMBL-European Bioinformatics Institute
5

6 7 8 9 10 11 12 13 14 15 16 17 18
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

=cut
19 20


21
=head1 CONTACT
22

23
  Please email comments or questions to the public Ensembl
Magali Ruffier's avatar
Magali Ruffier committed
24
  developers list at <http://lists.ensembl.org/mailman/listinfo/dev>.
25

26
  Questions may also be sent to the Ensembl help desk at
Magali Ruffier's avatar
Magali Ruffier committed
27
  <http://www.ensembl.org/Help/Contact>.
28

29
=cut
30

31
=head1 NAME
32

33
Bio::EnsEMBL::DBSQL::DBAdaptor
34

35
=head1 SYNOPSIS
36

37 38 39 40 41 42
  $db = Bio::EnsEMBL::DBSQL::DBAdaptor->new(
    -user   => 'root',
    -dbname => 'pog',
    -host   => 'caldy',
    -driver => 'mysql'
  );
43

44
  $gene_adaptor = $db->get_GeneAdaptor();
45

46
  $gene = $gene_adaptor->fetch_by_stable_id($stable_id);
47

48 49 50 51 52 53 54 55 56 57 58 59 60 61
  $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
62 63 64

=cut

65
package Bio::EnsEMBL::DBSQL::DBAdaptor;
Ian Longden's avatar
Ian Longden committed
66

67 68
use strict;

69
use Bio::EnsEMBL::DBSQL::DBConnection;
70
use Bio::EnsEMBL::DBSQL::BaseFeatureAdaptor;
71
use Bio::EnsEMBL::Utils::SeqRegionCache;
Magali Ruffier's avatar
Magali Ruffier committed
72
use Bio::EnsEMBL::Utils::Exception qw(throw warning);
73
use Bio::EnsEMBL::Utils::Argument qw(rearrange);
74
use Bio::EnsEMBL::Utils::Scalar qw(check_ref scope_guard);
Ian Longden's avatar
Ian Longden committed
75
use Bio::EnsEMBL::Utils::ConfigRegistry;
76

77 78 79

my $REGISTRY = "Bio::EnsEMBL::Registry";
require Bio::EnsEMBL::Registry;
Graham McVicker's avatar
Graham McVicker committed
80 81 82

=head2 new

Tiago Grego's avatar
Tiago Grego committed
83
  Arg [-DNADB]: (optional) Bio::EnsEMBL::DBSQL::DBAdaptor DNADB 
84 85 86
               All sequence, assembly, contig information etc, will
               be retrieved from this database instead.

87
  Arg [-NO_CACHE]: (optional) int 1
88 89 90 91 92 93 94
               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
95
               not use it or ask in the developer mailing list.
96

97
  Arg [-ADD_ALIASES]: (optional) boolean
Tiago Grego's avatar
Tiago Grego committed
98
                      Used to automatically load aliases for this 
99 100
                      species into the Registry upon loading.

101 102 103 104
  Arg [-ADD_SPECIES_ID]: (optional) boolean
                         Used to automatically load the species id
                         based on the species if none is defined.

Ian Longden's avatar
Ian Longden committed
105 106
  Arg [..]   : Other args are passed to superclass
               Bio::EnsEMBL::DBSQL::DBConnection
107

Ian Longden's avatar
Ian Longden committed
108
  Example    : $db = new Bio::EnsEMBL::DBSQL::DBAdaptor(
109 110 111 112 113 114
                -user   => 'root',
                -dbname => 'pog',
                -host   => 'caldy',
                -driver => 'mysql'
              );

Kieron Taylor's avatar
Kieron Taylor committed
115
              $db = new Bio::EnsEMBL::DBSQL::DBAdaptor(
116
                -species => 'Homo_sapiens',
117 118
                -group   => 'core',
                -user    => 'root',
119 120 121 122
                -dbname  => 'pog',
                -host    => 'caldy',
                -driver  => 'mysql'
              );
123

Kieron Taylor's avatar
Kieron Taylor committed
124
              $db = new Bio::EnsEMBL::DBSQL::DBAdaptor(
125
                -species         => 'staphylococcus_aureus',
126 127
                -group           => 'core',
                -user            => 'root',
128 129 130 131 132
                -dbname          => 'staphylococcus_collection_1_52_1a',
                -multispecies_db => 1,
                -host            => 'caldy',
                -driver          => 'mysql'
              );
133

Ian Longden's avatar
Ian Longden committed
134 135
  Description: Constructor for DBAdaptor.
  Returntype : Bio::EnsEMBL::DBSQL::DBAdaptor
Graham McVicker's avatar
Graham McVicker committed
136 137
  Exceptions : none
  Caller     : general
138
  Status     : Stable
139 140 141

=cut

142
sub new {
143
  my ( $class, @args ) = @_;
144

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

Andreas Kusalananda Kähäri's avatar
Andreas Kusalananda Kähäri committed
147
  my ( $is_multispecies, $species, $species_id, $group, $con, $dnadb,
148
    $no_cache, $dbname, $add_aliases, $add_species_id )
149 150
    = rearrange( [
      'MULTISPECIES_DB', 'SPECIES', 'SPECIES_ID', 'GROUP',
151
      'DBCONN',          'DNADB',   'NO_CACHE',   'DBNAME',
152
      'ADD_ALIASES', 'ADD_SPECIES_ID'
153 154 155
    ],
    @args
    );
156

157 158
  if ( defined($con) ) { $self->dbc($con) }
  else {
159 160 161
    if(! defined $dbname) {
      throw "-DBNAME is a required parameter when creating a DBAdaptor";
    }
162
    $self->dbc( new Bio::EnsEMBL::DBSQL::DBConnection(@args) );
Ian Longden's avatar
Ian Longden committed
163
  }
Ian Longden's avatar
Ian Longden committed
164

Tiago Grego's avatar
Tiago Grego committed
165
  if ( defined($species) ) { $self->species($species); } 
166 167
  if ( defined($group) )   { $self->group($group) }

168 169
  $self = Bio::EnsEMBL::Utils::ConfigRegistry::gen_load($self);

170 171
  if (defined $species_id) {
    $self->species_id($species_id);
172
  } elsif ($add_species_id and defined $species) {
173 174 175 176
    $self->find_and_add_species_id();
  } else {
    $self->species_id(1);
  }
177

178 179 180
  $self->is_multispecies( defined($is_multispecies)
                          && $is_multispecies == 1 );

Andreas Kusalananda Kähäri's avatar
Andreas Kusalananda Kähäri committed
181
  if ( defined($dnadb) )    { $self->dnadb($dnadb) }
182 183
  if ( $no_cache ) { $self->no_cache($no_cache) }
  if ( $add_aliases ) { $self->find_and_add_aliases($add_aliases) }
184

Ian Longden's avatar
Ian Longden committed
185
  return $self;
Andreas Kusalananda Kähäri's avatar
Andreas Kusalananda Kähäri committed
186
} ## end sub new
187

188
=head2 clear_caches
Ian Longden's avatar
Ian Longden committed
189

190
  Example			: $dba->clear_caches();
Tiago Grego's avatar
Tiago Grego committed
191
  Description	: Loops through all linked adaptors and clears their 
192 193
                caches if C<clear_cache()> is implemented. Not all caches
                are cleared & the DBAdaptor instance should be removed from
Tiago Grego's avatar
Tiago Grego committed
194
                the registry to clear these remaining essential caches. 
195 196 197 198 199 200 201
  Returntype 	: None
  Exceptions 	: None

=cut

sub clear_caches {
  my ($self) = @_;
202
  my $adaptors = $REGISTRY->get_all_adaptors(
203
    $self->species(), $self->group());
204
  foreach my $adaptor (@{$adaptors}) {
205 206 207 208 209 210
    if($adaptor->can('clear_cache')) {
      $adaptor->clear_cache();
    }
  }
  return;
}
211

212 213 214 215
=head2 find_and_add_aliases

  Example     : $dba->find_and_add_aliases();
  Description : When executed we delegate to the find_and_add_aliases
Tiago Grego's avatar
Tiago Grego committed
216 217
                method in Bio::EnsEMBL::Registry which scans the 
                database's MetaContainer for species.alias entries 
218 219 220 221 222 223 224 225 226
                indicating alternative names for this species. This
                is best executed on a core DBAdaptor instance.
  Returntype  : None
  Exceptions  : None

=cut

sub find_and_add_aliases {
  my ($self) = @_;
227
  $REGISTRY->find_and_add_aliases(-ADAPTOR => $self);
228 229 230
  return;
}

231 232
=head2 find_and_add_species_id

Tiago Grego's avatar
Tiago Grego committed
233
  Description : 
234 235 236 237 238 239 240 241 242 243 244 245
  Returntype  : None
  Exceptions  : None

=cut

sub find_and_add_species_id {
  my ($self) = @_;
  my $species = $self->species;
  defined $species or throw "Undefined species";

  my $dbc = $self->dbc;
  my $sth = $dbc->prepare(sprintf "SELECT DISTINCT species_id FROM %s.meta " .
Tiago Grego's avatar
Tiago Grego committed
246
			  "WHERE meta_key='species.alias' AND meta_value LIKE '%%s%'", 
247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262
			  $dbc->db_handle->quote_identifier($dbc->dbname), $species);
  $sth->execute() or
    throw "Error querying for species_id: perhaps the DB doesn't have a meta table?\n" .
      "$DBI::err .... $DBI::errstr\n";

  my $species_id;
  $sth->bind_columns(\$species_id);
  $sth->fetch;

  throw "Undefined species_id" unless defined $species_id;
  throw "Something wrong retrieving the species_id"
    unless $species_id >= 1;

  $self->species_id($species_id);
  return;
}
263

264
=head2 dbc
265

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

268
  Example    : $dbc = $dba->dbc();
Ian Longden's avatar
Ian Longden committed
269 270
  Description: Getter/Setter for DBConnection.
  Returntype : Bio::EnsEMBL::DBSQL::DBConnection
271
  Exceptions : throws if argument not a Bio::EnsEMBL::DBSQL::DBConnection
272
  Caller     : general
273
  Status     : Stable
274

275 276
=cut

277
sub dbc{
Ian Longden's avatar
Ian Longden committed
278
  my $self  = shift;
Tiago Grego's avatar
Tiago Grego committed
279
  
Ian Longden's avatar
Ian Longden committed
280 281 282 283 284 285 286 287 288 289
  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};
290 291
}

Ian Longden's avatar
Ian Longden committed
292
=head2 add_db_adaptor
Ian Longden's avatar
Ian Longden committed
293

Ian Longden's avatar
Ian Longden committed
294 295 296 297 298
  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);
Tiago Grego's avatar
Tiago Grego committed
299
  Description: Attaches another database instance to this database so 
Ian Longden's avatar
Ian Longden committed
300 301
               that it can be used in instances where it is required.
  Returntype : none
302
  Exceptions : none
Ian Longden's avatar
Ian Longden committed
303
  Caller     : EnsWeb
304
  Status     : At Risk
305 306 307

=cut

Ian Longden's avatar
Ian Longden committed
308 309
sub add_db_adaptor {
  my ($self, $name, $adaptor) = @_;
Ian Longden's avatar
Ian Longden committed
310

Ian Longden's avatar
Ian Longden committed
311 312 313 314
  unless($name && $adaptor && ref $adaptor) {
    throw('adaptor and name arguments are required');
  }

315
  $REGISTRY->add_db($self, $name, $adaptor);
316

Ian Longden's avatar
Ian Longden committed
317
}
318

319

Ian Longden's avatar
Ian Longden committed
320
=head2 remove_db_adaptor
Graham McVicker's avatar
Graham McVicker committed
321

Ian Longden's avatar
Ian Longden committed
322 323 324 325 326 327
  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
328
  Exceptions : none
Ian Longden's avatar
Ian Longden committed
329
  Caller     : ?
330
  Status     : At Risk
Graham McVicker's avatar
Graham McVicker committed
331 332 333

=cut

Ian Longden's avatar
Ian Longden committed
334 335
sub remove_db_adaptor {
  my ($self, $name) = @_;
336
  return $REGISTRY->remove_db($self, $name);
337 338 339
}


Ian Longden's avatar
Ian Longden committed
340
=head2 get_all_db_adaptors
341

Ian Longden's avatar
Ian Longden committed
342 343
  Arg [1]    : none
  Example    : @attached_dbs = values %{$db->get_all_db_adaptors()};
Tiago Grego's avatar
Tiago Grego committed
344
  Description: returns all of the attached databases as 
Ian Longden's avatar
Ian Longden committed
345
               a hash reference of key/value pairs where the keys are
Tiago Grego's avatar
Tiago Grego committed
346
               database names and the values are the attached databases  
Ian Longden's avatar
Ian Longden committed
347 348 349
  Returntype : hash reference with Bio::EnsEMBL::DBSQL::DBConnection values
  Exceptions : none
  Caller     : Bio::EnsEMBL::DBSQL::ProxyAdaptor
350 351
  Status     : At Risk
             : please use  Bio::EnsEMBL::Registry->get_all_db_adaptors
352 353 354

=cut

Ian Longden's avatar
Ian Longden committed
355 356
sub get_all_db_adaptors {
  my ($self) = @_;
357
  return $REGISTRY->get_all_db_adaptors($self);
Graham McVicker's avatar
Graham McVicker committed
358 359
}

Ensembl Pipeline's avatar
Ensembl Pipeline committed
360

361

Ian Longden's avatar
Ian Longden committed
362
=head2 get_db_adaptor
363

Ian Longden's avatar
Ian Longden committed
364 365 366 367 368 369
  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
370
  Exceptions : none
Ian Longden's avatar
Ian Longden committed
371
  Caller     : ?
372 373
  Status     : At Risk
             : please use  Bio::EnsEMBL::Registry->get_db_adaptors
374 375 376

=cut

Ian Longden's avatar
Ian Longden committed
377 378
sub get_db_adaptor {
  my ($self, $name) = @_;
379

380
  return $REGISTRY->get_db($self, $name);
Ian Longden's avatar
Ian Longden committed
381
}
382

383 384 385 386 387 388 389 390 391
=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

Tiago Grego's avatar
Tiago Grego committed
392
=cut 
393

394
sub get_available_adaptors {
395
  my $adaptors = {
396 397
    # Firstly those that just have an adaptor named after there object
    # in the main DBSQL directory.
398 399 400 401 402 403 404
    AltAlleleGroup                      => 'Bio::EnsEMBL::DBSQL::AltAlleleGroupAdaptor',
    Analysis                            => 'Bio::EnsEMBL::DBSQL::AnalysisAdaptor',
    ArchiveStableId                     => 'Bio::EnsEMBL::DBSQL::ArchiveStableIdAdaptor',
    AssemblyExceptionFeature            => 'Bio::EnsEMBL::DBSQL::AssemblyExceptionFeatureAdaptor',
    AssemblyMapper                      => 'Bio::EnsEMBL::DBSQL::AssemblyMapperAdaptor',
    AssemblySlice                       => 'Bio::EnsEMBL::DBSQL::AssemblySliceAdaptor',
    Attribute                           => 'Bio::EnsEMBL::DBSQL::AttributeAdaptor',
405
    Biotype                             => 'Bio::EnsEMBL::DBSQL::BiotypeAdaptor',
406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423
    CoordSystem                         => 'Bio::EnsEMBL::DBSQL::CoordSystemAdaptor',
    DataFile                            => 'Bio::EnsEMBL::DBSQL::DataFileAdaptor',
    DBEntry                             => 'Bio::EnsEMBL::DBSQL::DBEntryAdaptor',
    DensityFeature                      => 'Bio::EnsEMBL::DBSQL::DensityFeatureAdaptor',
    DensityType                         => 'Bio::EnsEMBL::DBSQL::DensityTypeAdaptor',
    DnaAlignFeature                     => 'Bio::EnsEMBL::DBSQL::DnaAlignFeatureAdaptor',
    Exon                                => 'Bio::EnsEMBL::DBSQL::ExonAdaptor',
    Gene                                => 'Bio::EnsEMBL::DBSQL::GeneAdaptor',
    IntronSupportingEvidence            => 'Bio::EnsEMBL::DBSQL::IntronSupportingEvidenceAdaptor',
    KaryotypeBand                       => 'Bio::EnsEMBL::DBSQL::KaryotypeBandAdaptor',
    MiscFeature                         => 'Bio::EnsEMBL::DBSQL::MiscFeatureAdaptor',
    MiscSet                             => 'Bio::EnsEMBL::DBSQL::MiscSetAdaptor',
    Operon                              => 'Bio::EnsEMBL::DBSQL::OperonAdaptor',
    OperonTranscript                    => 'Bio::EnsEMBL::DBSQL::OperonTranscriptAdaptor',
    PredictionExon                      => 'Bio::EnsEMBL::DBSQL::PredictionExonAdaptor',
    PredictionTranscript                => 'Bio::EnsEMBL::DBSQL::PredictionTranscriptAdaptor',
    ProteinAlignFeature                 => 'Bio::EnsEMBL::DBSQL::ProteinAlignFeatureAdaptor',
    ProteinFeature                      => 'Bio::EnsEMBL::DBSQL::ProteinFeatureAdaptor',
424
    RNAProduct                          => 'Bio::EnsEMBL::DBSQL::RNAProductAdaptor',
425 426 427 428 429 430 431 432 433 434 435 436
    RepeatConsensus                     => 'Bio::EnsEMBL::DBSQL::RepeatConsensusAdaptor',
    RepeatFeature                       => 'Bio::EnsEMBL::DBSQL::RepeatFeatureAdaptor',
    SeqRegionSynonym                    => 'Bio::EnsEMBL::DBSQL::SeqRegionSynonymAdaptor',
    Sequence                            => 'Bio::EnsEMBL::DBSQL::SequenceAdaptor',
    SimpleFeature                       => 'Bio::EnsEMBL::DBSQL::SimpleFeatureAdaptor',
    Slice                               => 'Bio::EnsEMBL::DBSQL::SliceAdaptor',
    SupportingFeature                   => 'Bio::EnsEMBL::DBSQL::SupportingFeatureAdaptor',
    Transcript                          => 'Bio::EnsEMBL::DBSQL::TranscriptAdaptor',
    TranscriptSupportingFeature         => 'Bio::EnsEMBL::DBSQL::TranscriptSupportingFeatureAdaptor',
    Translation                         => 'Bio::EnsEMBL::DBSQL::TranslationAdaptor',
    UnmappedObject                      => 'Bio::EnsEMBL::DBSQL::UnmappedObjectAdaptor',

437
    # Those whose adaptors are in Map::DBSQL
438 439 440 441 442
    Ditag                               => 'Bio::EnsEMBL::Map::DBSQL::DitagAdaptor',
    DitagFeature                        => 'Bio::EnsEMBL::Map::DBSQL::DitagFeatureAdaptor',
    Marker                              => 'Bio::EnsEMBL::Map::DBSQL::MarkerAdaptor',
    MarkerFeature                       => 'Bio::EnsEMBL::Map::DBSQL::MarkerFeatureAdaptor',

443 444
    # Finally the exceptions... those that have non-standard mapping
    # between object / adaptor ....
445
    GenomeContainer                     => 'Bio::EnsEMBL::DBSQL::GenomeContainer',
446 447 448 449
    MetaContainer                       => 'Bio::EnsEMBL::DBSQL::MetaContainer',
    MetaCoordContainer                  => 'Bio::EnsEMBL::DBSQL::MetaCoordContainer',
  };
  return $adaptors;
450
} ## end sub get_available_adaptors
451

452 453 454 455 456 457
###########################################################
#
# Support for DAS
#
###########################################################

Graham McVicker's avatar
Graham McVicker committed
458 459
=head2 add_DASFeatureFactory

Tiago Grego's avatar
Tiago Grego committed
460
  Arg [1]    : Bio::EnsEMBL::ExternalFeatureFactory $value 
Graham McVicker's avatar
Graham McVicker committed
461
  Example    : none
Tiago Grego's avatar
Tiago Grego committed
462
  Description: Attaches a DAS Feature Factory to this method.  
Graham McVicker's avatar
Graham McVicker committed
463 464 465 466 467 468
               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
469 470
  Status     : At Risk
             : with the new web code this may not be needed/supported
Graham McVicker's avatar
Graham McVicker committed
471 472 473 474

=cut

sub add_DASFeatureFactory{
Tiago Grego's avatar
Tiago Grego committed
475
 
Tanya Gray's avatar
Tanya Gray committed
476
 my ($self,$value) = @_;
Tiago Grego's avatar
Tiago Grego committed
477
  
Graham McVicker's avatar
Graham McVicker committed
478 479 480 481
  push(@{$self->{'_das_ff'}},$value);
}


Web Admin's avatar
Web Admin committed
482 483 484
sub remove_all_DASFeatureFactories {
  $_[0]->{'_das_ff'} = [];
}
Graham McVicker's avatar
Graham McVicker committed
485 486 487 488
=head2 _each_DASFeatureFactory

  Args       : none
  Example    : none
Tiago Grego's avatar
Tiago Grego committed
489
  Description: Not sure if this is used, or if it should be removed.  It 
Graham McVicker's avatar
Graham McVicker committed
490
               does not seem to be used at the moment
491
  Returntype : Bio::EnsEMBL::ExternalFeatureFactory
Graham McVicker's avatar
Graham McVicker committed
492 493
  Exceptions : none
  Caller     : ??
494 495
  Status     : At Risk
             : with the new web code this may not be needed/supported
Graham McVicker's avatar
Graham McVicker committed
496 497 498 499 500 501

=cut

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

Web Admin's avatar
Web Admin committed
502
   return @{$self->{'_das_ff'}||[]}
Graham McVicker's avatar
Graham McVicker committed
503 504 505
}


Tiago Grego's avatar
Tiago Grego committed
506 507 508 509
################################################################## 
# 
# SUPPORT FOR EXTERNAL FEATURE FACTORIES 
# 
510
##################################################################
511

512

513

514 515 516 517 518 519 520 521 522
=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
Tiago Grego's avatar
Tiago Grego committed
523 524
               will have its db attribute set to this DBAdaptor object via 
               the db accessor method. 
525

Tiago Grego's avatar
Tiago Grego committed
526 527
               ExternalFeatureAdaptors passed to this method are stored 
               internally in a hash keyed on the string returned by the 
528
               ExternalFeatureAdaptors track_name method.
Tiago Grego's avatar
Tiago Grego committed
529 530
               
               If the track name method is not implemented then the 
531 532 533
               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
Tiago Grego's avatar
Tiago Grego committed
534
               same track name.  For example, if no track_names are specified 
535
               then the the external feature adaptors will be stored under the
Tiago Grego's avatar
Tiago Grego committed
536
               keys 'External features', 'External features2' 
537
               'External features3' etc.
538 539
  Returntype : none
  Exceptions : none
540
  Caller     : general
Tiago Grego's avatar
Tiago Grego committed
541
  
542
=cut
543

544 545 546
sub add_ExternalFeatureAdaptor {
  my ($self, $adaptor) = @_;

Tiago Grego's avatar
Tiago Grego committed
547
  unless($adaptor && ref $adaptor && 
548
	 $adaptor->isa('Bio::EnsEMBL::External::ExternalFeatureAdaptor')) {
549 550
     throw("[$adaptor] is not a " .
           "Bio::EnsEMBL::External::ExternalFeatureAdaptor");
551
  }
552

553 554 555 556
  unless(exists $self->{'_xf_adaptors'}) {
    $self->{'_xf_adaptors'} = {};
  }

557
  my $track_name = $adaptor->{'_track_name'};
558 559 560
  if(!$track_name) {
    $track_name = $adaptor->track_name();
  }
561 562 563 564 565 566 567

  #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
568
  if(exists $self->{'_xf_adaptors'}->{"$track_name"}) {
569
    my $num = 2;
570
    $num++ while(exists $self->{'_xf_adaptors'}->{"$track_name$num"});
571 572 573 574 575
    $self->{'_xf_adaptors'}->{"$track_name$num"} = $adaptor;
  } else {
    $self->{'_xf_adaptors'}->{"$track_name"} = $adaptor;
  }

576
  $adaptor->ensembl_db($self);
577
}
578

579

580 581

=head2 get_ExternalFeatureAdaptors
582

Graham McVicker's avatar
Graham McVicker committed
583
  Arg [1]    : none
Tiago Grego's avatar
Tiago Grego committed
584
  Example    : @xfas = values %{$db_adaptor->get_ExternalFeatureAdaptors}; 
585
  Description: Retrieves all of the ExternalFeatureAdaptors which have been
Tiago Grego's avatar
Tiago Grego committed
586
               added to this DBAdaptor.  The ExternalFeatureAdaptors are 
587 588
               returned in a reference to a hash keyed on the track names
               of the external adaptors
Tiago Grego's avatar
Tiago Grego committed
589
  Returntype : Reference to a hash of ExternalFeatureAdaptors keyed on 
590
               their track names.
591
  Exceptions : none
592
  Caller     : general
593 594 595

=cut

596 597 598 599 600 601 602 603 604 605 606
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
Tiago Grego's avatar
Tiago Grego committed
607 608
  Description: It is recommended that add_ExternalFeatureAdaptor be used 
               instead.  See documentation for 
609 610 611
               Bio::EnsEMBL::External::ExternalFeatureAdaptor

               Adds an external feature factory to the core database
Tiago Grego's avatar
Tiago Grego committed
612
               so that features from external sources can be displayed in 
613 614 615 616 617 618 619 620 621 622
               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) = @_;
623

624
   $self->add_ExternalFeatureAdaptor($value);
625 626
}

627 628 629 630 631 632 633 634 635
#
# 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
636 637
  Returntype : Adaptor Object of arbitrary type or undef
  Exceptions : none
638
  Caller     : external
639 640
  Status     : Medium Risk
             : please use the Registry method, as at some time this
Tiago Grego's avatar
Tiago Grego committed
641 642
             : may no longer be supported.
 
643 644
=cut

645
sub get_adaptor {
Ian Longden's avatar
Ian Longden committed
646
  my ($self, $canonical_name, @other_args) = @_;
647
  return $REGISTRY->get_adaptor($self->species(),$self->group(),$canonical_name);
Ian Longden's avatar
Ian Longden committed
648
}
649

Ian Longden's avatar
Ian Longden committed
650 651


652 653 654
=head2 set_adaptor

  Arg [1]    : Canonical data type for new adaptor.
Kieron Taylor's avatar
Kieron Taylor committed
655
  Arg [2]    : Object defining the adaptor for arg1.
656 657
  Example    : $aa = Bio::EnsEMBL::DBSQL::GeneAdaptor->new($db_adaptor);
             : $db_adaptor->set_adaptor("Gene", $ga)
658 659
  Description: Stores the object which represents the adaptor for the
               arg1 data type.
660
  Returntype : none
Ian Longden's avatar
Ian Longden committed
661
  Exceptions : none
662
  Caller     : external
663 664
  Status     : Medium Risk
             : please use the Registry method, as at some time this
665
             : may no longer be supported.
Tiago Grego's avatar
Tiago Grego committed
666
 
667 668
=cut

669
sub set_adaptor {
Ian Longden's avatar
Ian Longden committed
670
  my ($self, $canonical_name, $module) = @_;
671
  $REGISTRY->add_adaptor($self->species(),$self->group(),$canonical_name,$module);
672
  return $module;
673 674
}

Ian Longden's avatar
Ian Longden committed
675

676 677 678 679 680 681
#
# GENERIC FEATURE ADAPTORS
#

=head2 get_GenericFeatureAdaptors

682 683
  Arg [1]    : List of names of feature adaptors to get. If no
               adaptor names are given, all the defined adaptors are returned.
684
  Example    : $db->get_GenericFeature("SomeFeature", "SomeOtherFeature")
685 686 687
  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
688
               feature adaptors (or all feature adaptors).
689 690 691 692 693
  Exceptions : If any of the the named generic feature adaptors do not exist.
  Caller     : external

=cut

694
sub get_GenericFeatureAdaptors {
695

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

Arne Stabenau's avatar
Arne Stabenau committed
698
  my %adaptors = ();
699

Arne Stabenau's avatar
Arne Stabenau committed
700 701 702 703 704
  if (!@names) {
    %adaptors = %{$self->{'generic_feature_adaptors'}};
  } else {
    foreach my $name (@names) {
      if (!exists($self->{'generic_feature_adaptors'}->{$name})) {
705
        throw("No generic feature adaptor has been defined for $name" );
Arne Stabenau's avatar
Arne Stabenau committed
706
      }
Ian Longden's avatar
Ian Longden committed
707 708


Arne Stabenau's avatar
Arne Stabenau committed
709 710 711
      $adaptors{$name} = $self->{'generic_feature_adaptors'}->{$name};
    }
  }
712

Arne Stabenau's avatar
Arne Stabenau committed
713
  return \%adaptors;
714 715
}

716

717 718 719 720
=head2 add_GenericFeatureAdaptor

  Arg [1]    : The name of the feature.
  Arg [2]    : Adaptor object for a generic feature.
721 722 723 724
  Example    : $db->add_GenericFeatureAdaptor("SomeFeature",
                              "Bio::EnsEMBL::DBSQL::SomeFeatureAdaptor")
  Description: Stores the object which represents the adaptor for the
               named feature type.
725 726 727 728 729 730
  Returntype : none
  Exceptions :
  Caller     : external

=cut

731
sub add_GenericFeatureAdaptor {
732
  my ($self, $name, $adaptor_obj) = @_;
Tiago Grego's avatar
Tiago Grego committed
733 734
	
  # check that $adaptor is an object that subclasses BaseFeatureAdaptor	
735 736 737 738
  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" );
  }
739

740
  $self->{'generic_feature_adaptors'}->{$name} = $adaptor_obj;
741
}
742

743 744
=head2 species

Ian Longden's avatar
Ian Longden committed
745
  Arg [1]    : (optional) string $arg
Tiago Grego's avatar
Tiago Grego committed
746
               The new value of the species used by this DBAdaptor. 
Ian Longden's avatar
Ian Longden committed
747
  Example    : $species = $dba->species()
Tiago Grego's avatar
Tiago Grego committed
748 749 750
  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 
Ian Longden's avatar
Ian Longden committed
751 752 753 754
               by the constructor.
  Returntype : string
  Exceptions : none
  Caller     : new
755
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
756 757 758 759

=cut

sub species {
760 761 762 763 764 765
  my ( $self, $arg ) = @_;

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

Ian Longden's avatar
Ian Longden committed
766 767 768
  $self->{_species};
}

769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784
=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() ] }
785 786 787
  return $self->{'_all_species'} if exists $self->{_all_species};
  my $sql = "SELECT meta_value FROM meta WHERE meta_key = 'species.db_name'";
  $self->{_all_species} = $self->dbc->sql_helper()->execute_simple(-SQL => $sql);
788 789 790 791
  return $self->{'_all_species'};
} ## end sub all_species


792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817
=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};
}


818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841
=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;
  }

842
  return $self->{_species_id};
843 844
}

Ian Longden's avatar
Ian Longden committed
845

846 847 848
=head2 no_cache

  Arg [1]    : (optional) int $arg
Tiago Grego's avatar
Tiago Grego committed
849
               The new value of the no cache attribute used by this DBAdaptor. 
850
  Example    : $no_cache = $dba->no_cache();
Tiago Grego's avatar
Tiago Grego committed
851 852 853
  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 
854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874
               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
875 876 877
=head2 group

  Arg [1]    : (optional) string $arg
Tiago Grego's avatar
Tiago Grego committed
878
               The new value of the group used by this DBAdaptor. 
Ian Longden's avatar
Ian Longden committed
879
  Example    : $group = $dba->group()
Tiago Grego's avatar
Tiago Grego committed
880 881 882
  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 
Ian Longden's avatar
Ian Longden committed
883 884 885 886
               by the constructor.
  Returntype : string
  Exceptions : none
  Caller     : new
887
  Status     : Stable
Ian Longden's avatar
Ian Longden committed
888 889

=cut
890

Ian Longden's avatar
Ian Longden committed
891 892 893 894 895 896
sub group {
  my ($self, $arg ) = @_;
  ( defined $arg ) &&
    ( $self->{_group} = $arg );
  $self->{_group};
}
897

898 899 900 901 902 903 904 905 </