Archive Ensembl HomeArchive Ensembl Home
DBEntry.pm
Go to the documentation of this file.
00001 =head1 LICENSE
00002 
00003   Copyright (c) 1999-2012 The European Bioinformatics Institute and
00004   Genome Research Limited.  All rights reserved.
00005 
00006   This software is distributed under a modified Apache license.
00007   For license details, please see
00008 
00009     http://www.ensembl.org/info/about/code_licence.html
00010 
00011 =head1 CONTACT
00012 
00013   Please email comments or questions to the public Ensembl
00014   developers list at <dev@ensembl.org>.
00015 
00016   Questions may also be sent to the Ensembl help desk at
00017   <helpdesk@ensembl.org>.
00018 
00019 =cut
00020 
00021 =head1 NAME
00022 
00023 Bio::EnsEMBL::DBEntry -
00024 Object representing an external reference (xref)
00025 
00026 =head1 SYNOPSIS
00027 
00028 =head1 DESCRIPTION
00029 
00030 This object holds information about external references (xrefs) to
00031 Ensembl objects.
00032 
00033 =head1 METHODS
00034 
00035 =cut
00036 
00037 package Bio::EnsEMBL::DBEntry;
00038 
00039 use strict;
00040 use warnings;
00041 no warnings qw(uninitialized);
00042 
00043 use Bio::EnsEMBL::Storable;
00044 use Bio::Annotation::DBLink;
00045 
00046 use Bio::EnsEMBL::Utils::Argument qw(rearrange);
00047 use Bio::EnsEMBL::Utils::Exception qw(deprecate);
00048 use Scalar::Util qw(weaken isweak);
00049 
00050 our @ISA = qw(Bio::EnsEMBL::Storable Bio::Annotation::DBLink);
00051 
00052 
00053 =head2 new_fast
00054 
00055   Arg [1]    : Hashref $hashref - hash reference to bless as new DBEntry object
00056   Description: A very quick constructor that requires internal knowledge of
00057                the class. This is used in speed critical sections of the code
00058                where many objects need to be created quickly.
00059   Returntype : Bio::EnsEMBL::DBEntry
00060   Exceptions : none
00061   Caller     : general
00062   Status     : Stable
00063 
00064 =cut
00065 
00066 sub new_fast {
00067   my $class = shift;
00068   my $hashref = shift;
00069   my $self = bless $hashref, $class;
00070   weaken($self->{adaptor})  if ( ! isweak($self->{adaptor}) );
00071   return $self;
00072 }
00073 
00074 
00075 =head2 new
00076 
00077   Args [...] : list of named parameters 
00078   Example    : my $dbentry = new Bio::EnsEMBL::DBEntry(
00079                     -adaptor => $adaptor,
00080                     -primary_id => $pid,
00081                     -version => $version,
00082                     -dbname  => $dbname,
00083                     -release => $release,
00084                     -display_id => $did,
00085                     -description => $description,
00086                     -priority => $priority,
00087                     -db_display_name => $db_display_name,
00088                     -info_type => $info_type,
00089                     -info_text => $info_text,
00090                     -type => $type,
00091                     -secondary_db_name => $secondary_db_name,
00092                     -secondary_db_table => $secondary_db_table
00093             -linkage_annotation => $object_xref_text);
00094   Description: Creates a new DBEntry object
00095   Returntype : Bio::EnsEMBL::DBEntry
00096   Exceptions : none
00097   Caller     : Bio::EnsEMBL::DBEntryAdaptor
00098   Status     : At Risk
00099                Due to 'PRIORITY',
00100               'INFO_TYPE', 'INFO_TEXT', ''DB_DISPLAY_NAME', 'TYPE',
00101               'SECONDARY_DB_NAME', 'SECONDARY_DB_TABLE'
00102                being under development - if you don't use any of these the
00103                method can be considered Stable
00104 
00105 =cut
00106 
00107 sub new {
00108   my ($class, @args) = @_;
00109   
00110   my $self = bless {},$class;
00111 
00112   my ( $adaptor, $dbID, $primary_id, $version,
00113        $dbname, $release, $display_id, $description,
00114        $priority,
00115        $db_display_name, $info_type, $info_text, $type,
00116        $secondary_db_name, $secondary_db_table, $link_annotation, $analysis) =
00117     rearrange ( ['ADAPTOR','DBID','PRIMARY_ID','VERSION',
00118                  'DBNAME','RELEASE','DISPLAY_ID','DESCRIPTION',
00119          'PRIORITY',
00120          'DB_DISPLAY_NAME', 'INFO_TYPE', 'INFO_TEXT', 'TYPE',
00121                  'SECONDARY_DB_NAME', 'SECONDARY_DB_TABLE', 'LINKAGE_ANNOTATION', 'ANALYSIS'], @args );
00122 
00123   $self->adaptor($adaptor);
00124   $self->{'dbID'}    = $dbID;
00125 
00126   if( defined $primary_id ) { $self->primary_id( $primary_id ) }
00127   if( defined $version ) { $self->version( $version ) } else
00128     { $self->version( "" ); }
00129   if( defined $dbname ) { $self->dbname( $dbname ) }
00130   if( defined $release) { $self->release( $release ) }
00131   if( defined $display_id) { $self->display_id( $display_id ) }
00132   if( defined $description) { $self->description($description) }
00133   if( defined $priority) { $self->priority($priority) }
00134   if( defined $db_display_name) { $self->db_display_name($db_display_name) }
00135   if( defined $info_type) { $self->info_type($info_type) }
00136   if( defined $info_text) { $self->info_text($info_text) }
00137   if( defined $type) { $self->type($type) }
00138   if( defined $secondary_db_name) { $self->secondary_db_name($secondary_db_name) }
00139   if( defined $secondary_db_table) { $self->secondary_db_table($secondary_db_table) }
00140 
00141   $self->linkage_annotation($link_annotation) if defined $link_annotation;
00142   $self->analysis($analysis) if defined $analysis;
00143 
00144 
00145   return $self;
00146 }
00147 
00148 
00149 =head2 primary_id
00150 
00151   Arg [1]    : (optional) String $arg - value to set
00152   Example    : none
00153   Description: Getter/setter for attribute 'primary_id'.
00154                This is the object's primary id in the external database.
00155   Returntype : String
00156   Exceptions : none
00157   Caller     : general
00158   Status     : Stable
00159 
00160 =cut
00161 
00162 sub primary_id {
00163   my ( $self, $arg ) = @_;
00164   if( defined $arg ) {
00165     $self->{primary_id} = $arg;
00166   } 
00167   return $self->{primary_id};
00168 }
00169 
00170 
00171 =head2 display_id
00172 
00173   Arg [1]    : (optional) String $arg - value to set
00174   Example    : none
00175   Description: Getter/setter for attribute 'display_id'.
00176                The object's preferred display name. This can be the same
00177                as primary_id or ensembl-specific.
00178   Returntype : String
00179   Exceptions : none
00180   Caller     : general
00181   Status     : Stable
00182 
00183 =cut
00184 
00185 sub display_id{
00186    my ( $self, $arg ) = @_;
00187    if( defined $arg ) {
00188        $self->{display_id} = $arg;
00189    } 
00190    return $self->{display_id};
00191 }
00192 
00193 
00194 =head2 optional_id
00195 
00196   Args       : none
00197   Example    : none
00198   Description: Additional getter for attribute 'display_id'.
00199                The object's preferred display name.
00200                Only include for BioPerl interface compliance, please use
00201                $self->display_id().
00202   Returntype : String
00203   Exceptions : none
00204   Caller     : general
00205   Status     : Stable
00206 
00207 =cut
00208 
00209 sub optional_id {
00210   my $self = shift;
00211   return $self->display_id;
00212 }
00213 
00214 
00215 =head2 dbname
00216 
00217   Arg [1]    : (optional) String $arg - value to set
00218   Example    : none
00219   Description: Getter/setter for attribute 'dbname'.
00220                The name of the external database.
00221   Returntype : String
00222   Exceptions : none
00223   Caller     : general
00224   Status     : Stable
00225 
00226 =cut
00227 
00228 sub dbname {
00229   my ( $self, $arg ) = @_;
00230   if( defined $arg ) {
00231     $self->{dbname} = $arg;
00232   } 
00233   return $self->{dbname};
00234 }
00235 
00236 
00237 =head2 database
00238 
00239   Args       : none
00240   Example    : none
00241   Description: Additional getter for attribute 'dbname'.
00242                The name of the external database.
00243                Only include for BioPerl interface compliance, please use
00244                $self->dbname().
00245   Returntype : String
00246   Exceptions : none
00247   Caller     : general
00248   Status     : Stable
00249 
00250 =cut
00251 
00252 sub database {
00253   my $self = shift;
00254   return $self->dbname();
00255 }
00256 
00257 
00258 =head2 release
00259 
00260   Arg [1]    : (optional) String $arg - value to set
00261   Example    : none
00262   Description: Getter/setter for attribute 'release'.
00263                The external database release name.
00264   Returntype : String
00265   Exceptions : none
00266   Caller     : general
00267   Status     : Stable
00268 
00269 =cut
00270 
00271 sub release {
00272   my ( $self, $arg ) = @_;
00273   if( defined $arg ) {
00274     $self->{release} = $arg;
00275   } 
00276   return $self->{release};
00277 }
00278 
00279 
00280 =head2 version
00281 
00282   Arg [1]    : (optional) String $arg - value to set
00283   Example    : none
00284   Description: Getter/setter for attribute 'version'.
00285                The object's version in the external database.
00286   Returntype : String
00287   Exceptions : none
00288   Caller     : general
00289   Status     : Stable
00290 
00291 =cut
00292 
00293 sub version {
00294   my ( $self, $arg ) = @_;
00295   if( defined $arg ) {
00296     $self->{version} = $arg;
00297   } 
00298   return $self->{version};
00299 }
00300 
00301 
00302 =head2 description
00303 
00304   Arg [1]    : (optional) String $arg - value to set
00305   Example    : none
00306   Description: Getter/setter for attribute 'description'.
00307                The object's description, from the xref table
00308   Returntype : String
00309   Exceptions : none
00310   Caller     : general
00311   Status     : Stable
00312 
00313 =cut
00314 
00315 sub description {
00316   my ( $self, $arg ) = @_;
00317 
00318   if ( defined($arg) ) { $self->{'description'} = $arg }
00319 
00320   return $self->{description};
00321 }
00322 
00323 =head2 analysis
00324 
00325   Arg [1]    : Bio::EnsEMBL::Analysis $analysis
00326   Example    : none
00327   Description: get/set for attribute analysis
00328   Returntype : Bio::EnsEMBL::Analysis
00329   Exceptions : none
00330   Caller     : general
00331   Status     : Stable
00332 
00333 =cut
00334 
00335 sub analysis {
00336    my $self = shift;
00337   $self->{analysis} = shift if( @_ );
00338   return $self->{analysis};
00339 }
00340 
00341 =head2 comment
00342 
00343   Args       : none
00344   Example    : none
00345   Description: Additional getter for attribute 'description'.
00346                The object's description.
00347                Only include for BioPerl interface compliance, please use
00348                $self->description().
00349   Returntype : String
00350   Exceptions : none
00351   Caller     : general
00352   Status     : Stable
00353 
00354 =cut
00355 
00356 sub comment {
00357   my $self = shift;
00358   return $self->description();
00359 }
00360 
00361 
00362 =head2 priority
00363 
00364   Arg [1]    : int $priority
00365   Example    : none
00366   Priority   : Getter/setter for attribute 'priority'. Note this
00367                is the priority from the external_db table.
00368   Returntype : String
00369   Exceptions : none
00370   Caller     : general
00371   Status     : At Risk
00372              : due to it being under development
00373 
00374 =cut
00375 
00376 sub priority {
00377   my ( $self, $arg ) = @_;
00378   if( defined $arg ) {
00379     $self->{priority} = $arg;
00380   } 
00381   return $self->{priority};
00382 }
00383 
00384 
00385 =head2 db_display_name
00386 
00387   Arg [1]    : String $db_display_name
00388   Example    : none
00389   Description: Getter/setter for attribute 'db_display_name'.
00390                The preferred display name for the external database. Has
00391                "Projected " prepended if info_type='PROJECTION'.
00392   Returntype : String
00393   Exceptions : none
00394   Caller     : general
00395 
00396 =cut
00397 
00398 sub db_display_name {
00399   my ( $self, $arg ) = @_;
00400   if( defined $arg ) {
00401     $self->{db_display_name} = $arg;
00402   }
00403 
00404   my $name;
00405   if ($self->{info_type} && $self->{info_type} eq "PROJECTION") {
00406     $name = "Projected " . $self->{db_display_name};
00407   } else {
00408     $name =  $self->{db_display_name};
00409   }
00410 
00411   return $name;
00412 }
00413 
00414 
00415 =head2 info_type
00416 
00417   Arg [1]    : String $info_type
00418   Example    : none
00419   Description: Getter/setter for attribute 'info_type'.
00420   Returntype : String
00421   Exceptions : none
00422   Caller     : general
00423 
00424 =cut
00425 
00426 sub info_type {
00427   my ( $self, $arg ) = @_;
00428   if( defined $arg ) {
00429     $self->{info_type} = $arg;
00430   }
00431   return $self->{info_type};
00432  }
00433 
00434 
00435 =head2 info_text
00436 
00437   Arg [1]    : String $info_text
00438   Example    : none
00439   Description: Getter/setter for attribute 'info_text'.
00440   Returntype : String
00441   Exceptions : none
00442   Caller     : general
00443 
00444 =cut
00445 
00446 sub info_text {
00447   my ( $self, $arg ) = @_;
00448   if( defined $arg ) {
00449     $self->{info_text} = $arg;
00450   } 
00451   return $self->{info_text};
00452 }
00453 
00454 =head2 linkage_annotation
00455 
00456   Arg [1]    : String $object_xref_text
00457   Example    : none
00458   Description: Getter/setter for attribute 'linkage_annotation'.
00459   Returntype : String
00460   Exceptions : none
00461   Caller     : general
00462 
00463 =cut
00464 
00465 sub linkage_annotation {
00466   my ( $self, $arg ) = @_;
00467 
00468   $self->{linkage_annotation} = $arg if defined $arg;
00469   
00470   return $self->{linkage_annotation};
00471 }
00472 
00473 
00474 =head2 type
00475 
00476   Arg [1]    : String $type
00477   Example    : none
00478   Description: Getter/setter for attribute 'type'.
00479   Returntype : String
00480   Exceptions : none
00481   Caller     : general
00482 
00483 =cut
00484 
00485 sub type {
00486   my ( $self, $arg ) = @_;
00487   if( defined $arg ) {
00488     $self->{type} = $arg;
00489   }
00490   return $self->{type};
00491 }
00492 
00493 =head2 secondary_db_name
00494 
00495   Arg [1]    : String $secondary_db_name
00496   Example    : none
00497   Description: Getter/setter for attribute 'secondary_db_name'.
00498   Returnsecondary_db_name : String
00499   Exceptions : none
00500   Caller     : general
00501 
00502 =cut
00503 
00504 sub secondary_db_name {
00505   my ( $self, $arg ) = @_;
00506   if( defined $arg ) {
00507     $self->{secondary_db_name} = $arg;
00508   }
00509   return $self->{secondary_db_name};
00510 }
00511 
00512 
00513 =head2 secondary_db_table
00514 
00515   Arg [1]    : String $secondary_db_table
00516   Example    : none
00517   Description: Getter/setter for attribute 'secondary_db_table'.
00518   Returnsecondary_db_table : String
00519   Exceptions : none
00520   Caller     : general
00521 
00522 =cut
00523 
00524 sub secondary_db_table {
00525   my ( $self, $arg ) = @_;
00526   if( defined $arg ) {
00527     $self->{secondary_db_table} = $arg;
00528   }
00529   return $self->{secondary_db_table};
00530 }
00531 
00532 
00533 =head2 add_synonym
00534 
00535   Arg [1]    : String $arg - synonym to add
00536   Example    : none
00537   Description: Add a synonym for the external object.
00538   Returntype : none
00539   Exceptions : none
00540   Caller     : general
00541   Status     : Stable
00542 
00543 =cut
00544 
00545 
00546 sub add_synonym {
00547   my ( $self, $arg ) = @_;
00548   if( defined $arg ) {
00549     push( @{$self->{synonyms}}, $arg );
00550   }
00551 }
00552 
00553 
00554 =head2 get_all_synonyms
00555 
00556   Args      : none
00557   Example    : my @synonyms = @{ $db_entry->get_all_synonyms };
00558   Description: Get a list of synonyms known for this object.
00559                Synonyms are lazy-loaded if required.
00560   Returntype : listref of strings. May be empty.
00561   Exceptions : none
00562   Caller     : general
00563   Status     : Stable
00564 
00565 =cut
00566 
00567 sub get_all_synonyms {
00568 
00569   my $self = shift;
00570 
00571   # lazy-load synonyms if required
00572   if (!$self->{synonyms} && $self->adaptor()) {
00573     $self->{synonyms} = $self->adaptor()->fetch_all_synonyms($self->dbID());
00574   }
00575 
00576   return $self->{synonyms};
00577 }
00578 
00579 
00580 =head2 get_all_dependents
00581 
00582   Args[1]    : (optional) Bio::EnsEMBL::Gene, Transcript or Translation object
00583   Example    : my @dependents = @{ $db_entry->get_all_dependents };
00584   Description: Get a list of DBEntrys that are depenednet on the DBEntry.
00585                if an ensembl gene transcript or translation is given then only
00586                the ones on that object will be given
00587   Returntype : listref of DBEntrys. May be empty.
00588   Exceptions : none
00589   Caller     : general
00590   Status     : UnStable
00591 
00592 =cut
00593 
00594 sub get_all_dependents {
00595   my $self = shift;
00596   my $ensembl_object = shift;
00597 
00598   return  $self->adaptor()->get_all_dependents($self->dbID(), $ensembl_object);
00599 }
00600 
00601 =head2 get_all_masters
00602 
00603   Args[1]    : (optional) Bio::EnsEMBL::Gene, Transcript or Translation object
00604   Example    : my @masters = @{ $db_entry->get_all_masters };
00605   Description: Get a list of DBEntrys that are the masters of the DBEntry.
00606                if an ensembl gene transcript or translation is given then only
00607                the ones on that object will be given.
00608   Returntype : listref of DBEntrys. May be empty.
00609   Exceptions : none
00610   Caller     : general
00611   Status     : UnStable
00612 
00613 =cut
00614 
00615 sub get_all_masters {
00616   my $self = shift;
00617   my $ensembl_object = shift;
00618 
00619   return  $self->adaptor()->get_all_masters($self->dbID(), $ensembl_object);
00620 }
00621 
00622 
00623 =head2 flush_synonyms
00624 
00625   Args       : none
00626   Example    : none
00627   Description: Remove all synonyms from this object.
00628   Returntype : none
00629   Exceptions : none
00630   Caller     : general
00631   Status     : Stable
00632 
00633 =cut
00634 
00635 sub flush_synonyms {
00636   my $self = shift;
00637   $self->{synonyms} = [];
00638 }
00639 
00640 
00641 =head2 status
00642 
00643   Arg [1]    : (optional) String $arg - value to set
00644   Example    : none
00645   Description: Getter/setter for attribute 'status'.
00646   Returntype : String
00647   Exceptions : none
00648   Caller     : general
00649   Status     : Stable
00650 
00651 =cut
00652 
00653 
00654 sub status{
00655   my ( $self, $arg ) = @_;
00656   if( defined $arg ) {
00657      $self->{status} = $arg;
00658   } 
00659   return $self->{status};
00660 }
00661 
00662 =head2 ensembl_object_type
00663 
00664   Arg [1]    : (optional) String $arg - value to set
00665   Example    : none
00666   Description: Getter/setter for attribute ensembl_object_type.
00667   Returntype : String
00668   Exceptions : none
00669   Caller     : general
00670   Status     : Stable
00671 
00672 =cut
00673 
00674 
00675 sub ensembl_object_type{
00676   my ( $self, $arg ) = @_;
00677   if( defined $arg ) {
00678      $self->{ensembl_object_type} = $arg;
00679   } 
00680   return $self->{ensembl_object_type};
00681 }
00682 
00683 =head2 ensembl_id
00684 
00685   Arg [1]    : (optional) String $arg - value to set
00686   Example    : none
00687   Description: Getter/setter for attribute ensembl_id.
00688   Returntype : String
00689   Exceptions : none
00690   Caller     : general
00691   Status     : Stable
00692 
00693 =cut
00694 
00695 
00696 sub ensembl_id{
00697   my ( $self, $arg ) = @_;
00698   if( defined $arg ) {
00699      $self->{ensembl_id} = $arg;
00700   } 
00701   return $self->{ensembl_id};
00702 }
00703 
00704 
00705 
00706 =head1 DEPRECATED METHODS
00707 
00708 =cut
00709 
00710 =head2 get_synonyms
00711 
00712   Description: DEPRECATED use get_all_synonyms instead
00713 
00714 =cut
00715 
00716 sub get_synonyms {
00717   my $self = shift;
00718 
00719   deprecate("get_synonyms has been renamed get_all_synonyms.");
00720   return $self->get_all_synonyms;
00721 }
00722 
00723 1;
00724