/ 
Bio-EnsEMBL-113.0.0
River stage zero No dependents
/ Bio::EnsEMBL::DBSQL::BaseAdaptor

LICENSE

Copyright [1999-2015] Wellcome Trust Sanger Institute and the EMBL-European Bioinformatics Institute Copyright [2016-2024] EMBL-European Bioinformatics Institute

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.

CONTACT

Please email comments or questions to the public Ensembl
developers list at <http://lists.ensembl.org/mailman/listinfo/dev>.

Questions may also be sent to the Ensembl help desk at
<http://www.ensembl.org/Help/Contact>.

NAME

Bio::EnsEMBL::DBSQL::BaseAdaptor - Base Adaptor for DBSQL adaptors

SYNOPSIS

# base adaptor provides

# SQL prepare function
$adaptor->prepare("sql statement");

# get of root DBAdaptor object
$adaptor->db();

# constructor, ok for inheritence
$adaptor = Bio::EnsEMBL::DBSQL::SubClassOfBaseAdaptor->new($dbobj);

DESCRIPTION

This is a true base class for Adaptors in the Ensembl DBSQL system.

Adaptors are expected to have the following functions

$obj = $adaptor->fetch_by_dbID($internal_id);

which builds the object from the primary key of the object. This function is crucial because it allows adaptors to collaborate relatively independently of each other - in other words, we can change the schema under one adaptor without too many knock on changes through the other adaptors.

Most adaptors will also have

$dbid = $adaptor->store($obj);

which stores the object. Currently the storing of an object also causes the objects to set

$obj->dbID();

correctly and attach the adaptor.

Other fetch functions go by the convention of

@object_array = @{ $adaptor->fetch_all_by_XXXX($arguments_for_XXXX) };

sometimes it returns an array ref denoted by the 'all' in the name of the method, sometimes an individual object. For example

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

or

@fp = @{ $simple_feature_adaptor->fetch_all_by_Slice($slice) };

Occassionally adaptors need to provide access to lists of ids. In this case the convention is to go list_XXXX, such as

@gene_ids = @{ $gene_adaptor->list_geneIds() };

(note: this method is poorly named)

new

Arg [1]    : Bio::EnsEMBL::DBSQL::DBConnection $dbobj
Example    : $adaptor = new AdaptorInheritedFromBaseAdaptor($dbobj);
Description: Creates a new BaseAdaptor object.  The intent is that this
             constructor would be called by an inherited superclass either
             automatically or through $self->SUPER::new in an overridden 
             new method.
Returntype : Bio::EnsEMBL::DBSQL::BaseAdaptor
Exceptions : none
Caller     : Bio::EnsEMBL::DBSQL::DBConnection
Status     : Stable

prepare

Arg [1]    : string $string
             a SQL query to be prepared by this adaptors database
Example    : $sth = $adaptor->prepare("select yadda from blabla")
Description: provides a DBI statement handle from the adaptor. A convenience
             function so you dont have to write $adaptor->db->prepare all the
             time
Returntype : DBI::StatementHandle
Exceptions : none
Caller     : Adaptors inherited from BaseAdaptor
Status     : Stable

db

Arg [1]    : (optional) Bio::EnsEMBL::DBSQL::DBAdaptor $obj 
             the database this adaptor is using.
Example    : $db = $adaptor->db();
Description: Getter/Setter for the DatabaseConnection that this adaptor is 
             using.
Returntype : Bio::EnsEMBL::DBSQL::DBAdaptor
Exceptions : none
Caller     : Adaptors inherited from BaseAdaptor
Status     : Stable

dbc

Arg [1]    : (optional) Bio::EnsEMBL::DBSQL::DBConnection $obj 
             the database this adaptor is using.
Example    : $db = $adaptor->db();
Description: Getter/Setter for the DatabaseConnection that this adaptor is 
             using.
Returntype : Bio::EnsEMBL::DBSQL::DBConnection
Exceptions : none
Caller     : Adaptors inherited from BaseAdaptor
Status     : Stable

is_multispecies

Arg [1]    : (optional) boolean $arg
Example    : if ($adaptor->is_multispecies()) { }
Description: Getter/Setter for the is_multispecies boolean of
             to use for this adaptor.
Returntype : boolean
Exceptions : none
Caller     : general
Status     : Stable

species_id

Arg [1]    : (optional) int $species_id
             The internal ID of the species in a multi-species database.
Example    : $db = $adaptor->db();
Description: Getter/Setter for the internal ID of the species in a
             multi-species database.  The default species ID is 1.
Returntype : Integer
Exceptions : none
Caller     : Adaptors inherited from BaseAdaptor
Status     : Stable

bind_param_generic_fetch

Arg [1]   : (optional)  scalar $param
             This is the parameter to bind
Arg [2]   : (optional) int $sql_type
             Type of the parameter (from DBI (:sql_types))
Example   :  $adaptor->bind_param_generic_fetch($stable_id,SQL_VARCHAR);
             $adaptor->generic_fetch();
Description:  When using parameters for the query, will call the bind_param to avoid
              some security issues. If there are no arguments, will return the bind_parameters
ReturnType : listref
Exceptions:  if called with one argument

generate_in_constraint

Arg [1]     : ArrayRef or Scalar $list
              List or a single value of items to be pushed into an IN statement
Arg [2]     : Scalar $column
              Column this IN statement is being applied to. Please fully resolve the
              column.
Arg [3]     : Scalar $param_type
              Data type which should be used when binding. Please use DBI data type symbols
Arg [4]     : Scalar boolean $inline_variables
              Boolean to control if variables are inlined in the constraint. If
              false values are bound via bind_param_generic_fetch() (the default behaviour).

Description : Used internally to generate a SQL constraint to restrict a query by an IN statement.
              The code generates the complete IN statement.
Returntype  : String
Exceptions  : If no list is supplied, the list of values is empty or no data type was given
Caller      : general

generic_fetch

Arg [1]    : (optional) string $constraint
             An SQL query constraint (i.e. part of the WHERE clause)
Arg [2]    : (optional) Bio::EnsEMBL::AssemblyMapper $mapper
             A mapper object used to remap features
             as they are retrieved from the database
Arg [3]    : (optional) Bio::EnsEMBL::Slice $slice
             A slice that features should be remapped to
Example    : $fts = $a->generic_fetch('contig_id in (1234, 1235)');
Description: Performs a database fetch and returns feature objects in
             contig coordinates.
Returntype : listref of Bio::EnsEMBL::SeqFeature in contig coordinates
Exceptions : Thrown if there is an issue with querying the data
Caller     : BaseFeatureAdaptor, ProxyDnaAlignFeatureAdaptor::generic_fetch
Status     : Stable

generic_count

Arg [1]    : (optional) string $constraint
             An SQL query constraint (i.e. part of the WHERE clause)
Example    : $number_feats = $a->generic_count('contig_id in (1234, 1235)');
Description: Performs a database fetch and returns a count of those features
             found. This is analagous to C<generic_fetch()>
Returntype : Integer count of the elements.
Exceptions : Thrown if there is an issue with querying the data

fetch_by_dbID

Arg [1]    : int $id
             The unique database identifier for the feature to be obtained
Example    : $feat = $adaptor->fetch_by_dbID(1234));
             $feat = $feat->transform('contig');
Description: Returns the feature created from the database defined by the
             the id $id.  The feature will be returned in its native
             coordinate system.  That is, the coordinate system in which it
             is stored in the database.  In order to convert it to a
             particular coordinate system use the transfer() or transform()
             method.  If the feature is not found in the database then
             undef is returned instead
Returntype : Bio::EnsEMBL::Feature or undef
Exceptions : thrown if $id arg is not provided
             does not exist
Caller     : general
Status     : Stable

fetch_all_by_dbID_list

Arg [1]    : listref of integers $id_list
             The unique database identifiers for the features to
             be obtained.
Arg [2]    : optional - Bio::EnsEMBL::Slice to map features onto.
Example    : @feats = @{$adaptor->fetch_all_by_dbID_list([1234, 2131, 982]))};
Description: Returns the features created from the database
             defined by the the IDs in contained in the provided
             ID list $id_list.  The features will be returned
             in their native coordinate system.  That is, the
             coordinate system in which they are stored in the
             database.  In order to convert the features to a
             particular coordinate system use the transfer() or
             transform() method.  If none of the features are
             found in the database a reference to an empty list is
             returned.
Returntype : listref of Bio::EnsEMBL::Features
Exceptions : thrown if $id arg is not provided
             does not exist
Caller     : general
Status     : Stable

_uncached_fetch_all_by_id_list

Arg [1]    : listref of IDs
Arg [2]    : (optional) Bio::EnsEMBL::Slice $slice
             A slice that features should be remapped to
Arg [3]    : String describing the ID type.
             Valid values include dbID and stable_id. dbID is an alias for
             the primary key, while other names map directly to table columns
             of the Feature this adaptor manages.
Arg [4]    : Boolean $numeric
             Indicates if the incoming data is to be processed as a numeric
             or as a String. If arg [3] was set to dbID then we default this to
             be true. If arg [3] was set to stable_id then we default this to
             be false.
             When not using a standard arg[3] the IDs are assumed to be Strings.
Arg [5]    : Integer $max_size
             Control the maximum number of IDs sent to a database in a single 
             query. Defaults to 2K for Strings and 16K for integers. Only
             provide if you know *exactly* why you need to edit it.
Example    : $list_of_features = $adaptor->_uncached_fetch_all_by_id_list(
                 [qw(ENSG00000101321 ENSG00000101346 ENSG00000101367)],
                 undef,
                 "stable_id", 0); #using strings
             
             # Numeric set to true because we are using numerics
             $list_of_features = $adaptor->_uncached_fetch_all_by_id_list(
                 [1,2,3,4],
                 undef,
                 "dbID", 1);

             # Numeric defaults to true because we are querying using dbID
             $list_of_features = $adaptor->_uncached_fetch_all_by_id_list(
                 [1,2,3,4],
                 undef,
                 "dbID");
Description: This is a generic method used to fetch lists of features by IDs.
             It avoids caches, meaning it is best suited for block fetching.
             See fetch_all_by_dbID_list() for more info.
Returntype : ArrayRef of Bio::EnsEMBL::Feature
Exceptions : Thrown if a list of IDs is not supplied.
Caller     : BaseFeatureAdaptor, BaseAdaptor and derived classes.

last_insert_id

Arg [1]     : (optional) $field the name of the field the inserted ID was pushed 
              into
Arg [2]     : (optional) HashRef used to pass extra attributes through to the 
              DBD driver
Arg [3]     : (optional) $table the name of the table to use if the adaptor
              does not implement C<_tables()>
Description : Delegating method which uses DBI to extract the last inserted 
              identifier. If using MySQL we just call the DBI method 
              L<DBI::last_insert_id()> since MySQL ignores any extra
              arguments. See L<DBI> for more information about this 
              delegated method. 
Example     : my $id = $self->last_insert_id('my_id'); my $other_id = $self->last_insert_id();
Returntype  : Scalar or undef

insert_ignore_clause

_id_cache

Description : Used to return an instance of a support BaseCache module
              which can be used to speed up object access. The method
              also respects the DBAdaptor's no_cache() flag and will
              return undef in those situations
Example     : my $cache = $self->_id_cache();
Returntype  : Bio::EnsEMBL::DBSQL::Support::BaseCache

_no_id_cache

Description : Flags if the ID based caching is active or not. This could be
              due to the adaptor not wanting to cache or because of
              a global no_cache() flag on the DBAdaptor instance
Returntype  : Boolean

ignore_cache_override

Description : Method to interfere with no_cache directive from Registry on
              a per adaptor basis. This method should be called after new()
              in order to trigger the _build_id_cache at first query.                  
Example     : $adaptor->ignore_cache_override(1);              
Returntype  : Boolean

schema_version

Description : Returns the schema version of the currently connected
              DBAdaptor. The subroutine also caches this value so
              repeated calls continue to be speedy.                  
Example     : $adaptor->schema_version();            
Returntype  : Integer