NAME
Bio::DB::BioSQL::BaseDriver - DESCRIPTION of Object
SYNOPSIS
Give standard usage here
DESCRIPTION
Describe the object here
FEEDBACK
Mailing Lists
User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to the Bioperl mailing list. Your participation is much appreciated.
bioperl-l@bioperl.org - General discussion
http://bioperl.org/wiki/Mailing_lists - About the mailing listsSupport
Please direct usage questions or support issues to the mailing list:
bioperl-l@bioperl.org
rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible.
Reporting Bugs
Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their resolution. Bug reports can be submitted via the web:
http://redmine.open-bio.org/projects/bioperl/AUTHOR - Hilmar Lapp
Email hlapp at gmx.net
CONTRIBUTORS
Additional contributors names and emails here
APPENDIX
The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
new
Title : new
Usage : my $obj = Bio::DB::BioSQL::BaseDriver->new();
Function: Builds a new Bio::DB::BioSQL::BaseDriver object
Returns : an instance of Bio::DB::BioSQL::BaseDriver
Args :prepare_delete_sth
Title : prepare_delete_sth
Usage :
Function: Creates a prepared statement with one placeholder variable
suitable to delete one row from the respective table the
given class maps to.
The method may throw an exception, or the database handle
methods involved may throw an exception.
Example :
Returns : A DBI statement handle for a prepared statement with one placeholder
Args : The calling adaptor (basically, it needs to implement dbh()).
Optionally, additional arguments.prepare_findbypk_sth
Title : prepare_findbypk_sth
Usage :
Function: Prepares and returns a DBI statement handle with one placeholder for
the primary key. The statement is expected to return the primary key
as the first and then as many columns as
$adp->get_persistent_slots() returns, and in that order.
Example :
Returns : A DBI prepared statement handle with one placeholder
Args : The Bio::DB::BioSQL::BasePersistenceAdaptor derived object
(basically, it needs to implement dbh() and get_persistent_slots()).
A reference to an array of foreign key slots (class names).prepare_findbyuk_sth
Title : prepare_findbyuk_sth
Usage :
Function: Prepares and returns a DBI SELECT statement handle with as many
placeholders as necessary for the given unique key.
The statement is expected to return the primary key as the first and
then as many columns as $adp->get_persistent_slots() returns, and in
that order.
Example :
Returns : A DBI prepared statement handle with as many placeholders as
necessary for the given unique key
Args : The calling Bio::DB::BioSQL::BasePersistenceAdaptor derived object
(basically, it needs to implement dbh() and get_persistent_slots()).
A reference to a hash with the names of the object''s slots in the
unique key as keys and their values as values.
A reference to an array of foreign key objects or slots
(class names if slot).prepare_insert_association_sth
Title : prepare_insert_association_sth
Usage :
Function: Prepares a DBI statement handle suitable for inserting the
association between the two entities that correspond to the
given objects.
Example :
Returns : the DBI statement handle
Args : The calling adaptor.
Named parameters. Currently recognized are:
-objs a reference to an array of objects to be
associated with each other
-values a reference to a hash the keys of which are
column names and the values are values of
columns other than the ones for foreign keys to
the entities to be associated
-contexts optional; if given it denotes a reference
to an array of context keys (strings), which
allow the foreign key name to be determined
through the association map rather than through
foreign_key_name(). This may be necessary if
more than one object of the same type takes
part in the association. The array must be in
the same order as -objs, and have the same
number of elements. Put undef for objects
for which there are no multiple contexts.
Caveats: Make sure you *always* give the objects to be associated in the
same order.prepare_delete_association_sth
Title : prepare_delete_association_sth
Usage :
Function: Prepares a DBI statement handle suitable for deleting the
association between the two entities that correspond to the
given objects.
Example :
Returns : the DBI statement handle
Args : The calling adaptor.
Named parameters. Currently recognized are:
-objs a reference to an array of objects the association
between which is to be deleted
-values a reference to a hash the keys of which are
column names and the values are values of
columns other than the ones for foreign keys to
the entities to be associated
-contexts optional; if given it denotes a reference
to an array of context keys (strings), which
allow the foreign key name to be determined
through the association map rather than through
foreign_key_name(). This may be necessary if
more than one object of the same type takes
part in the association. The array must be in
the same order as -objs, and have the same
number of elements. Put undef for objects
for which there are no multiple contexts.
Caveats: Make sure you *always* give the objects to be associated in the
same order.prepare_delete_query_sth
Title : prepare_delete_query_sth
Usage :
Function: Prepares a DBI statement handle suitable for deleting rows
from a table that match a number of attributes.
Example :
Returns : the DBI statement handle
Args : The calling adaptor.
Named parameters. Currently recognized are:
-fkobjs optional; a reference to an array of foreign
key objects by which to constrain; this is
complementary to -values
-contexts optional; if given it denotes a reference
to an array of context keys (strings), which
allow the foreign key name to be determined
through the association map rather than through
foreign_key_name(). This may be necessary if
an entity has more than one foreign key to the
same entity. The array must be in the same
order as -fkobjs, and have the same number of
elements. Put undef for objects for which there
are no multiple contexts.
-values optional; a reference to a hash the keys of
which are attribute names by which to constrain
the queryprepare_insert_sth
Title : prepare_insert_sth
Usage :
Function: Prepares a DBI statement handles suitable for inserting
a row (as values of the slots of an object) into a table.
Example :
Returns : the DBI statement handle
Args : the calling adaptor (a Bio::DB::PersistenceAdaptorI object)
a reference to an array of object slot names
a reference to an array of foreign key objects (optional)prepare_update_sth
Title : prepare_update_sth
Usage :
Function: Prepares a DBI statement handle suitable for updating
a row in a table where the row is identified by its
primary key.
Example :
Returns : the DBI statement handle
Args : the calling adaptor (a Bio::DB::PersistenceAdaptorI object)
a reference to an array of object slot names
a reference to an array of foreign key objects (optional)cascade_delete
Title : cascade_delete
Usage :
Function: Removes all persistent objects dependent from the given persistent
object from the database (foreign key integrity).
This implementation assumes that the underlying schema and RDBMS
support cascading deletes, and hence does nothing other than
returning TRUE.
Example :
Returns : TRUE on success, and FALSE otherwise
Args : The DBContextI implementing object for the database.
The object for which the dependent rows shall be deleted.
Optionally, additional (named) arguments.insert_object
Title : insert_object
Usage :
Function:
Example :
Returns : The primary key of the newly inserted record.
Args : A Bio::DB::BioSQL::BasePersistenceAdaptor derived object
(basically, it needs to implement dbh(), sth($key, $sth),
dbcontext(), and get_persistent_slots()).
The object to be inserted.
A reference to an array of foreign key objects; if any of those
foreign key values is NULL (some foreign keys may be nullable),
then give the class name.update_object
Title : update_object
Usage :
Function:
Example :
Returns : The number of updated rows
Args : A Bio::DB::BioSQL::BasePersistenceAdaptor derived object
(basically, it needs to implement dbh(), sth($key, $sth),
dbcontext(), and get_persistent_slots()).
The object to be updated.
A reference to an array of foreign key objects; if any of those
foreign key values is NULL (some foreign keys may be nullable),
then give the class name.get_sth
Title : get_sth
Usage :
Function: Retrieves the (prepared) statement handle to bind
parameters for and to execute for the given operation.
By default this will use the supplied key to retrieve the
statement from the cache.
This method is here to provide an opportunity for
inheriting drivers to intercept the cached statement
retrieval in order to on-the-fly redirect the statement
execution to use a different statement than it would have
used by default.
This method may return undef if for instance there is no
appropriate statement handle in the cache. Returning undef
will trigger the calling method to construct a statement
from scratch.
Example :
Returns : a prepared statement handle if one is exists for the query,
and undef otherwise
Args : - the calling adaptor (a Bio::DB::BioSQL::BasePersistenceAdaptor
derived object
- the object for the persistence operation
- a reference to an array of foreign key objects; if any of
those foreign key values is NULL then the class name
- the key to the cache of the adaptor
- the operation requesting a cache key (a scalar basically
representing the name of the method)translate_query
Title : translate_query
Usage :
Function: Translates the given query as represented by the query object
from objects and class names and slot names to tables and column
names.
Example :
Returns : An object of the same class as the input query, but representing
the translated query, and also with the SELECT fields properly set
to facilitate object construction.
Args : The calling adaptor.
The query as a Bio::DB::Query::BioQuery or derived object.
A reference to an array of foreign key objects._build_select_list
Title : _build_select_list
Usage :
Function: Builds and returns the select list for an object query. The list
contains those columns, in the right order, that are necessary to
populate the object.
Example :
Returns : An array of strings (column names, not prefixed)
Args : The calling persistence adaptor.
A reference to an array of foreign key entities (objects, class
names, or adaptors) the object must attach.
A reference to a hash table mapping entity names to aliases (if
omitted, aliases will not be used, and SELECT columns can only be
from one table)table_name
Title : table_name
Usage :
Function: Obtain the name of the table in the relational schema
corresponding to the given class name, object, or
persistence adaptor.
This implementation uses a object-relational hash map keyed
by class to obtain the table name.
Example :
Returns : the name of the table (a string), or undef if the table cannot be
determined
Args : The referenced object, class name, or the persistence
adaptor for it.association_table_name
Title : association_table_name
Usage :
Function: Obtain the name of the table in the relational schema
corresponding to the association of entities as represented
by their corresponding class names, objects, or persistence
adaptors.
This implementation will use table_name() and the map
returned by association_entity_map().
This method will throw an exception if the association is
not mapped (not to be confused with the association being
unsupported).
Example :
Returns : the name of the table (a string, or undef if the association is not
supported by the schema)
Args : A reference to an array of objects, class names, or persistence
adaptors. The array may freely mix types.primary_key_name
Title : primary_key_name
Usage :
Function: Obtain the name of the primary key attribute for the given table in
the relational schema.
This implementation just appends _id to the table name,
which yields correct results for at least the MySQL version
of the BioSQL schema. Override it for your own schema if
necessary.
Example :
Returns : The name of the primary key (a string)
Args : The name of the table (a string)foreign_key_name
Title : foreign_key_name
Usage :
Function: Obtain the foreign key name for referencing an object, as
represented by object, class name, or the persistence adaptor.
Example :
Returns : the name of the foreign key (a string)
Args : The referenced object, class name, or the persistence adaptor for
it. _build_foreign_key_name
Title : _build_foreign_key_name
Usage :
Function: Build the column name for a foreign key to the given table.
The default implementation here retrieves the primary key
for the given table.
This is called by foreign_key_name() once it has determined
the table name. If a particular driver wants to build the
foreign key name in a specific or generally different way
than the default implementation here, this is the method to
override (unless you also want to change the way the table
is determined; in that case you would override
foreign_key_name()).
Example :
Returns : The name of the foreign key column as a string
Args : The table name as a stringsequence_name
Title : sequence_name
Usage :
Function: Returns the name of the primary key generator (SQL sequence)
for the given table.
The value returned is passed as the second argument to the
L<Bio::DB:DBI>::last_id_value as implemented by the
driver. Because the parameter is not required irregardless
of driver, it is perfectly legal for this method to return
undef. If the L<Bio::DB::DBI> driver does need this
parameter, this method should be overridden by the matching
adaptor driver.
The default we assume here is we dont need this value.
Example :
Returns : the name of the sequence (a string)
Args : The name of the table.objrel_map
Title : objrel_map
Usage :
Function: Get/set the object-relational map from classes to entities.
Example :
Returns : A reference to a hash map where object interfaces are the keys
Args : Optional, on set a reference to the respective hash mapslot_attribute_map
Title : slot_attribute_map
Usage :
Function: Get/set the mapping for each entity from object slot names
to column names.
Example :
Returns : A reference to a hash map with entity names being the keys,
if no key (entity name, object, or adaptor) was
provided. Otherwise, a hash reference with the slot names
being keys to their corresponding column names.
Args : Optionally, the object, adaptor, or entity for which to
obtain the map.
Optionally, on set a reference to a hash map satisfying the
features of the returned value.not_select_attrs
Title : not_select_attrs
Usage : $obj->not_select_attrs($newval)
Function: Get/set a map of all columns that should not be included in
SELECT lists.
Example :
Returns : value of not_select_attrs (a reference to a hash map)
Args : new value (a reference to a hash map, optional)association_entity_map
Title : association_entity_map
Usage : $obj->association_entity_map($newval)
Function: Get/set the association entity map. The map is an anonymous
hash with entities that participate in associations being
keys. The values are hash refs themselves, with the other
participating entity being the key, and the value being
either the name of the respective association entity, or
another hash ref with the same structure if more entities
participate in the association.
The hash map must be commutative. I.e., the association
entity must be locatable irregardless with which of the
participating entities one starts.
Example :
Returns : value of association_entity_map (a hash ref of hash refs)
Args : new value (a hash ref of hash refs, optional)DBI calls for possible interception
These will usually delegate straightforward DBI calls on the supplied handle, but can also be used by an inheriting adaptor driver to intercept the call and add additional parameters, for example a hash reference with named parameters.
commit
Title : commit
Usage :
Function: Commits the current transaction, if the underlying driver
supports transactions.
Example :
Returns : TRUE
Args : The database connection handle for which to commit.rollback
Title : rollback
Usage :
Function: Triggers a rollback of the current transaction, if the
underlying driver supports transactions.
Example :
Returns : TRUE
Args : The database connection for which to rollback.bind_param
Title : bind_param
Usage :
Function: Binds a parameter value to a prepared statement.
The reason this method is here is to give RDBMS-specific
drivers a chance to intercept the parameter binding and
perform additional actions, or add additional parameters to
the call, like data type. Certain drivers need to be helped
for certain types, for example DBD::Oracle for LOB
parameters.
Example :
Returns : the return value of the DBI::bind_param() call
Args : the DBI statement handle to bind to
the index of the column
the value to bind
additional arguments to be passed to the sth->bind_param callprepare
Title : prepare
Usage :
Function: Prepares a SQL statement and returns a statement handle.
The reason this method is here is the same as for
bind_param.
Example :
Returns : the return value of the DBI::prepare() call
Args : the DBI database handle for preparing the statement
the SQL statement to prepare (a scalar)
additional arguments to be passed to the dbh->prepare callUtility methods
report_execute_failure
Title : report_execute_failure
Usage :
Function: Report the failure to execute a SQL statement.
The reporting by default uses warn() but may be requested
to throw().
Example :
Returns :
Args : Named paramaters. Currently recognized are
-sth the statement handle whose execution failed
-adaptor the calling adaptor
(a Bio::DB::PersistenceAdaptorI object)
-op the type of operation that failed ('insert',
'update',...)
-vals a reference to an array of values that were bound
-fkobjs a reference to an array of foreign key objects
that were bound (optional)
-report_func the name of the method to call for reporting
the message (optional, default is 'warn')