NAME
Bio::DB::BioSQL::BasePersistenceAdaptor - 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 listsReporting 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://bugzilla.open-bio.org/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 = new Bio::DB::BioSQL::BasePersistenceAdaptor();
Function: Builds a new Bio::DB::BioSQL::BasePersistenceAdaptor object
Returns : an instance of Bio::DB::BioSQL::BasePersistenceAdaptor
Args :Methods for managing persistence
This comprises of creating an object in the database (equivalent to an insert), storing an object in the database (equivalent to an update), removing an object from the database (equivalent to a delete), and adding and removing associations between objects when the underlying schema supports such associations.
create
Title : create
Usage : $objectstoreadp->create($obj, @params)
Function: Creates the object as a persistent object in the datastore. This
is equivalent to an insert.
Example :
Returns : A Bio::DB::PersistentObjectI implementing object wrapping the
inserted object.
Args : The object to be inserted, and optionally additional (named)
parameters. A common parameter will
be -fkobjs, with a reference to an array of foreign key objects
that are not retrievable from the persistent object itself.store
Title : store
Usage : $objectstoreadp->store($persistent_obj,@params)
Function: Updates the given persistent object in the datastore.
Example :
Returns : TRUE on success and FALSE otherwise
Args : The object to be updated, and optionally additional (named)
parameters. A common parameter will
be -fkobjs, with a reference to an array of foreign key objects
that are not retrievable from the persistent object itself.remove
Title : remove
Usage : $objectstoreadp->remove($persistent_obj, @params)
Function: Removes the persistent object from the datastore.
Example :
Returns : TRUE on success and FALSE otherwise
Args : The object to be removed, and optionally additional (named)
parameters.add_association
Title : add_assocation
Usage :
Function: Stores the association between given objects in the datastore.
Example :
Returns : TRUE on success and FALSE otherwise
Args : Named parameters. At least the following must be recognized:
-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
abstract column names and the values are values
of those columns. These columns are generally
those 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 slot-to-column 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.remove_association
Title : remove_assocation
Usage :
Function: Removes the association between the given objects in
the datastore.
Example :
Returns : TRUE on success and FALSE otherwise
Args : Named parameters. At least the following must be recognized:
-objs a reference to an array of objects the association
between which is to be removed
-values a reference to a hash the keys of which are
abstract column names and the values are values
of those columns. These columns are generally
those other than the ones for foreign keys to
the entities to be associated. Supplying this
is only necessary if those columns participate
in a unique key by which to find those
associations to be removed.
-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 slot-to-column 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.Making persistent objects
The DBAdaptorI factory mandates this operation, but it will in most cases conduct the operation by first finding the appropriate persistence adaptor and then asking the adaptor to do the operation. Hence, here is where the real stuff happens.
create_persistent
Title : create_persistent
Usage :
Function: Takes the given object and turns it onto a
PersistentObjectI implementing object. Returns the
result. Does not actually create the object in a database.
Calling this method is expected to have a recursive effect
such that all children of the object, i.e., all slots that
are objects themselves, are made persistent objects, too.
Example :
Returns : A Bio::DB::PersistentObjectI implementing object wrapping the
passed object.
Args : An object to be made into a PersistentObjectI object (the class
will be suitable for this adaptor).
Optionally, the class which actually implements wrapping the object
to become a PersistentObjectI._create_persistent
Title : _create_persistent
Usage :
Function: Calling this method recursively replaces all eligible
children of the object, i.e., all slots that are objects
themselves and for which an adaptor exists, with instances
of Bio::DB::PersistentObjectI.
This is an internal method. Do not call from outside.
Example :
Returns : The first argument.
Args : - A Bio::DB::PersistentObjectI implementing object, the
class of which is suitable for this adaptor (unless on a
recursive call).
- Optionally, the class which actually implements wrapping
the object to become a PersistentObjectI.Finding objects by some property
This comprises of finding by primary key, finding by unique key (alternative key), finding by association, and finding by query.
find_by_primary_key
Title : find_by_primary_key
Usage : $objectstoreadp->find_by_primary_key($pk)
Function: Locates the entry associated with the given primary key and
initializes a persistent object with that entry.
By default this implementation caches all objects by primary key
if caching is enabled. Note that by default caching is disabled.
Provide -cache_objects => 1 to the constructor in order to enable
it.
Example :
Returns : An instance of the class this adaptor adapts, represented by an
object implementing Bio::DB::PersistentObjectI, or undef if no
matching entry was found.
Args : The primary key.
Optionally, the Bio::Factory::ObjectFactoryI compliant object
factory to be used for instantiating the proper class. If the object
does not implement Bio::Factory::ObjectFactoryI, it is assumed to
be the object to be populated with the query results.find_by_unique_key
Title : find_by_unique_key
Usage :
Function: Locates the entry matching the unique key attributes as set
in the passed object, and populates a persistent object
with this entry.
This method will ask get_unique_key_query() for the actual
alternative key(s) by which to search. It can handle
multiple alternative keys returned by
get_unique_key_query(). So the knowledge about which
properties of an object constitute an alternative key, and
how to retrieve the values for those properties, is with
get_unique_key_query() which therefore must be overridden
by every adaptor.
Multiple keys will be semantically ORed with short-cut
evaluation, meaning the method will loop over all
alternative keys and terminate the loop as soon as a match
is found. Thus, the order of multiple keys returned by
get_unique_key_query() does matter.
Example :
Returns : A Bio::DB::PersistentObjectI implementing object, with the
attributes populated with values provided by the entry in the
datastore, or undef if no matching entry was found. If one was
found, the object returned will be the first argument if that
implemented Bio::DB::PersistentObjectI already, and a new
persistent object otherwise.
Args : The object with those attributes set that constitute the chosen
unique key (note that the class of the object must be suitable for
the adaptor).
Additional attributes and values if required, passed as named
parameters. Specifically noteworthy are
-fkobjs a reference to an array holding foreign key
objects if those can't be retrieved from the
object itself (e.g., a Comment object will need
the Seq object passed with this argument)
-obj_factory the object factory to use to create new
objects when a matching row is found. If not
specified, the passed object will be populated
rather than creating a new object.
-flat_only do not retrieve and attach children (objects
having a foreign key to the entity handled by
this adaptor) if value evaluates to true
(default: false)_find_by_unique_key
Title : _find_by_unique_key
Usage :
Function: Locates the entry matching the unique key attributes as
set in the passed object, and populates a persistent
object with this entry.
This is the protected version of find_by_unique_key. Since
it requires more upfront work to pass the right parameters
in the right order, you should not call it from outside,
but there may be situations where you want to call this
method from a derived class.
Example :
Returns : A Bio::DB::PersistentObjectI implementing object, with the
attributes populated with values provided by the entry in the
datastore, or undef if no matching entry was found. If one was
found, the object returned will be the first argument if that
implemented Bio::DB::PersistentObjectI already, and a new
persistent object otherwise.
Args :
- The object with those attributes set that constitute the
chosen unique key (note that the class of the object must
be suitable for the adaptor).
- The query as an anonymous hash with keys being properties
in the unique key. See get_unique_key_query() for a more
detailed description on what the expected structure is.
- A reference to an array of foreign key objects if
applicable (undef if the entity doesn't have any foreign
keys).
- The object factory to use to create a new object if a
matching row is found. Optional; if not specified the
passed object will be populated with the found values
rather than a new object created.
- A flag indicating whether not to retrieve and attach
children (objects having a foreign key to the object to
build). Defaults to false if omitted, meaning children
will be attached.find_by_association
Title : find_by_association
Usage :
Function: Locates those records associated between a number of objects. The
focus object (the type to be instantiated) depends on the adaptor
class that inherited from this class.
Example :
Returns : A Bio::DB::Query::QueryResultI implementing object
Args : Named parameters. At least the following must be recognized:
-objs a reference to an array of objects to be associated with
each other
-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 slot-to-column 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.
-obj_factory the factory to use for instantiating object from
the found rows
-constraints a reference to an array of additional
L<Bio::DB::Query::QueryConstraint> objects
-values the values to bind to the constraint clauses,
as a hash reference keyed by the constraints
Caveats: Make sure you *always* give the objects to be associated in the
same order.find_by_query
Title : find_by_query
Usage :
Function: Locates entries that match a particular query and returns
the result as an array of peristent objects.
The query is represented by an instance of
Bio::DB::Query::AbstractQuery or a derived class. Note that
SELECT fields will be ignored and auto-determined. Give
tables in the query as objects, class names, or adaptor
names, and columns as slot names or foreign key class names
in order to be maximally independent of the exact
underlying schema. The driver of this adaptor will
translate the query into tables and column names.
Example :
Returns : A Bio::DB::Query::QueryResultI implementing object
Args : The query as a Bio::DB::Query::AbstractQuery or derived
instance. Note that the SELECT fields of that query object
will inadvertantly be overwritten.
Optionally additional (named) parameters. Recognized
parameters at this time are
-fkobjs a reference to an array of foreign key
objects that are not retrievable from the
persistent object itself
-obj_factory the object factory to use for creating
objects for resulting rows
-name a unique name for the query, which will make
the the statement be a cached prepared
statement, which in subsequent invocations
will only be re-bound with parameters values,
but not recreated
-values a reference to an array holding the values
to be bound, if the query is a named query
-flat_only do not retrieve and attach children (objects
having a foreign key to the entity handled by
this adaptor) if value evaluates to true
(default: false)_build_object
Title : _build_object
Usage :
Function: Build and populate an object or populate a prepuilt object from
a row from the database.
This is a private method primarily to centralize the code
for this task from the various find_by_XXXX methods. Don't
call from outside unless you know what you're doing.
Example :
Returns : A persistent object (implements Bio::DB::PersistentObjectI)
Args : Named parameters. Currently supported are:
-obj A prebuilt object to be populated only (optional)
-row a reference to an array of column values (mandatory)
-pk the primary key to be associated with the new object
(optional)
-num_fks the number of foreign key instances which need
to be associated with the object to be built
(optional, defaults to 0)
-obj_factory an object factory to be used for instantiating
the object if it needs to be created
-flat_only do not retrieve and attach children (objects
having a foreign key to the object to build)
if value evaluates to true (default: false)Transaction control methods
This comprises of rollback and commit. The point to have those here even though they merely delegate to the driver is that the caller doesn't need to distinguish whether the RDBMS driver supports transactions or not. If the DBI driver doesn't then simply the adaptor driver won't do anything.
commit
Title : commit
Usage :
Function: Commits the current transaction, if the underlying driver
supports transactions.
Example :
Returns : TRUE
Args : nonerollback
Title : rollback
Usage :
Function: Triggers a rollback of the current transaction, if the
underlying driver supports transactions.
Example :
Returns : TRUE
Args : noneDatabase Context and Adaptor Driver
These are published attributes for convenient perusal by derived adaptors.
dbcontext
Title : dbcontext
Usage : $obj->dbcontext($newval)
Function: Get/set the DBContextI object representing the physical database.
Example :
Returns : A Bio::DB::DBContextI implementing object
Args : on set, the new Bio::DB::DBContextI implementing objectdbh
Title : dbh
Usage : $obj->dbh($newval)
Function: Get/set the DBI connection handle.
If you set this from outside, you should know exactly what
you are doing.
Example :
Returns : value of dbh (a database handle)
Args : on set, the new value (a database handle, optional)dbd
Title : dbd
Usage : $obj->dbd($newval)
Function: Get/set the driver for this adaptor.
The driver will usually be an instance of a class derived
from L<Bio::DB::BioSQL::BaseDriver>. It will usually also
have to implement L<Bio::DB::Persistent::ObjectRelMapperI>.
If you set this from outside, you should know exactly what
you are doing. If the value is requested in get-mode but no
value has been set yet, the driver will be auto-loaded. Most
if not all of the adaptors will in fact use this
auto-loading feature.
Example :
Returns : value of dbd (a scalar)
Args : new value (a scalar, optional)db
Title : db
Usage : $dbadaptor = $obj->db()
Function: This is just shorthand for $obj->dbcontext()->dbadaptor().
Example :
Returns : value of db (a Bio::DB::DBAdaptorI implementing object)
Args : nonesth
Title : sth
Usage : $obj->sth($key, $prepared_sth)
Function: caches prepared statements
Example :
Returns : a DBI statement handle cached under the key, or all statement
handles in the cache if no key is supplied
Args : the key for the cached prepared statement handle, and optionally
on set the new statement handle to be cached, or undef to
remove the handle from the cachesql_generator
Title : sql_generator
Usage : $obj->sql_generator($newval)
Function: Get/set the SQL generator object to use for turning query objects
into SQL statements.
Example :
Returns : value of sql_generator (an instance of Bio::DB::Query::SqlGenerator
or a derived object)
Args : new value (an instance of Bio::DB::Query::SqlGenerator
or a derived object, optional)caching_mode
Title : caching_mode
Usage : $obj->caching_mode($newval)
Function: Get/set whether objects are cached for find_by_primary_key()
and find_by_unique_key().
See obj_cache() for documentation on how to use the object cache.
If you disable caching through this method, the entire
cache will be flushed as a side effect.
Example :
Returns : TRUE if caching of objects is enabled and FALSE otherwise
Args : new value (a scalar, optional)obj_cache
Title : obj_cache
Usage :
Function: Implements a simple cache of objects by key. Often, this will be
used by derived classes to cache singletons, if there is only a
limited number of certain base objects, like Species, or
Ontology_Term.
A derived adaptor may want to override this method to cache only
selectively. The constructor of this class turns off caching by
default; supply -cache_objects => 1 in order to turn it on, or
call $adp->caching_mode(1).
Example :
Returns : The object cached under the key, or undef if there is no such key
Args : The key under which to cache the object.
Optionally, on set the object to be cached. Pass undef to
un-cache an object stored under the key.crc64
Title : crc64
Usage :
Function: Computes and returns the CRC64 checksum for a given string.
This method may be called as a static method too as it
doesn't not make any references to instance
properties. However, it isn't really meant for outside
consumption, but rather for derived classes as a utility
method. At present, in fact this module itself doesn't use
it.
This is basically ripped out of the bioperl swissprot
parser. Credits go to whoever contributed it there.
Example :
Returns : the CRC64 checksum as a string
Args : the string as a scalar for which to obtain the CRC64Object Lifespan-related methods
finish
Title : finish
Usage : $objectadp->finish()
Function: Finishes the resources used by this object. Note that this will
not disconnect the database handle, but it will remove the reference
to it.
This behaviour is needed because the connection handle may be shared
between multiple objects.
Note that given the implementation here you may continue to use the
adaptor after calling this method, since a new db handle will be
obtained automatically if needed, and objects removed from the cache
will be rebuilt.
Basically, this method will reset the object cache if any and finish
all cached statement handles and reset the statement handle cache.
Note that this method will not throw an exception even if finishing
the resources causes an error. It will issue a warning though, and
if verbose() >= 1 warnings become exceptions.
Example :
Returns : none
Args : noneDESTROY
Title : DESTROY
Usage :
Function: We override this here to call finish().
Example :
Returns :
Args :Abstract Methods
Almost all of the following methods MUST be overridden by a
derived class. For some methods there is an implementation here
that assumes "no action" is the right thing, but for many adaptors
this won't be right. There is no way this base implementation can
make any meaningful guesses at the correct values for those.get_persistent_slots
Title : get_persistent_slots
Usage :
Function: Get the slots of the object that map to attributes in its
respective entity in the datastore.
Slot name generally refers to a method name, but is not
required to do so, since determining the values is under
the control of get_persistent_slot_values().
This is a strictly abstract method. A derived class MUST
override it to return something meaningful.
Example :
Returns : an array of method names constituting the serializable slots
Args : the object about to be inserted or updatedget_persistent_slot_values
Title : get_persistent_slot_values
Usage :
Function: Obtain the values for the slots returned by get_persistent_slots(),
in exactly that order.
The reason this method is here is that sometimes the actual
slot values need to be post-processed to yield the value
that gets actually stored in the database. E.g., slots
holding arrays will need some kind of join function
applied. Another example is if the method call needs
additional arguments. Supposedly the adaptor for a specific
interface knows exactly what to do here.
Since there is also populate_from_row() the adaptor has
full control over mapping values to a version that is
actually stored.
This is a strictly abstract method and it MUST be
overridden by a derived class.
Example :
Returns : A reference to an array of values for the persistent slots of this
object. Individual values may be undef.
Args : The object about to be serialized.
A reference to an array of foreign key objects if not retrievable
from the object itself.get_foreign_key_objects
Title : get_foreign_key_objects
Usage :
Function: Gets the objects referenced by this object, and which therefore need
to be referenced as foreign keys in the datastore.
Note that the objects are expected to implement
Bio::DB::PersistentObjectI.
An implementation may obtain the values either through the object
to be serialized, or through the additional arguments. An
implementation should also make sure that the order of foreign key
objects returned is always the same.
Note also that in order to indicate a NULL value for a nullable
foreign key, either put an object returning undef from
primary_key(), or put the name of the class instead. DO NOT SIMPLY
LEAVE IT OUT.
This implementation assumes a default of no foreign keys and returns
an empty array.
Example :
Returns : an array of Bio::DB::PersistentObjectI implementing objects
Args : The object about to be inserted or updated, or undef if the call
is for a SELECT query. In the latter case return class or interface
names that are mapped to the foreign key tables.
Optionally, additional named parameters. A common parameter will
be -fkobjs, with a reference to an array of foreign key objects
that are not retrievable from the persistent object itself.attach_foreign_key_objects
Title : attach_foreign_key_objects
Usage :
Function: Attaches foreign key objects to the given object as far as
necessary.
This method is called after find_by_XXX() queries, not for INSERTs
or UPDATEs.
This implementation assumes there are no foreign keys that need to
be retrieved and instantiated. You MUST override this method
in order to have foreign key objects taken care of upon SELECTs.
Example :
Returns : TRUE on success, and FALSE otherwise.
Args : The object to which to attach foreign key objects.
A reference to an array of foreign key values, in the order of
foreign keys returned by get_foreign_key_objects().store_children
Title : store_children
Usage :
Function: Inserts or updates the child entities of the given object in the
datastore.
Usually, those child objects will reference the given object as
a foreign key.
The implementation can assume that all of the child objects
are already Bio::DB::PersistentObjectI.
While obtaining and looping over all child objects could have been
implemented as a generic business logic method, supplying the right
foreign key objects is hard to accomplish in a generic fashion.
The implementation here assumes there are no children and hence
just returns TRUE. You MUST override it in order to have any
children taken care of.
Example :
Returns : TRUE on success, and FALSE otherwise
Args : The Bio::DB::PersistentObjectI implementing object for which the
child objects shall be made persistent.
A reference to an array of foreign key values, in the order of
foreign keys returned by get_foreign_key_objects().attach_children
Title : attach_children
Usage :
Function: Possibly retrieve and attach child objects of the given object.
This is needed when whole object trees are supposed to be built
when a base object is queried for and returned. An example would
be Bio::SeqI objects and all the annotation objects that hang off
of it.
This is called by the find_by_XXXX() methods once the base object
has been built.
This implementation will do nothing unless it is overridden. Whether
to override it or not will depend on which of the children shall be
loaded instantly instead of lazily.
Example :
Returns : TRUE on success, and FALSE otherwise.
Args : The object for which to find and to which to attach the child
objects.remove_children
Title : remove_children
Usage :
Function: This method is to cascade deletes in maintained objects.
Child records in the database will usually be cascaded by
the RDBMS. In order to cascade removals to persistent child
objects, you must override this method. Usually you will
need to undefine the primary key of child objects, and
possibly remove them from caches if they are cached.
Because failure to do so may result in serious and often
non-obvious bugs, there is no default provided here. You
*must* override this method in a derived adaptor as
evidence that you know what you are doing, even if all you
do is just return TRUE.
Example :
Returns : TRUE on success and FALSE otherwise
Args : The persistent object that was just removed from the database.
Additional (named) parameter, as passed to remove().instantiate_from_row
Title : instantiate_from_row
Usage :
Function: Instantiates the class this object is an adaptor for, and populates
it with values from columns of the row.
Usually a derived class will instantiate the proper class and pass
it on to populate_from_row().
This implementation assumes that the object factory is provided,
uses it to instantiate a new object, and then passes on to
populate_from_row(). If this is not appropriate the method must be
overridden by a derived object.
Example :
Returns : An object, or undef, if the row contains no values
Args : A reference to an array of column values. The first column is the
primary key, the other columns are expected to be in the order
returned by get_persistent_slots().
Optionally, the object factory to be used for instantiating the
proper class. The adaptor must be able to instantiate a default
class if this value is undef.populate_from_row
Title : populate_from_row
Usage :
Function: Populates the given object with values from columns of the row.
This method is strictly abstract and MUST be overridden by a
derived object.
Example :
Returns : The object populated, or undef, if the row contains no values
Args : The object to be populated.
A reference to an array of column values. The first column is the
primary key, the other columns are expected to be in the order
returned by get_persistent_slots().get_unique_key_query
Title : get_unique_key_query
Usage :
Function: Obtain the suitable unique key slots and values as
determined by the attribute values of the given object and
the additional foreign key objects, in case foreign keys
participate in a UK.
This method embodies the knowledge about which properties
constitute the alternative keys for an object (entity) and
how to obtain the values of those properties from the
object. Therefore, unless there is no alternative key for
an entity, the respective (derived) adaptor must override
this method.
If there are multiple alternative keys for an entity, the
overriding implementation may choose to determine at
runtime the best alternative key given the object and then
return only a single alternative key, or it may choose to
return an array of (supposedly equally suitable)
alternative keys. Note that if every alternative key
returned will be searched for until a match is found
(short-cut evaluation), so returning partially populated
alternative keys is usually not wise.
This implementation assumes there are no unique keys
defined for the entity adapted by this class and hence
returns an empty hash ref. Instead of overriding this
method a derived class may choose to override
find_by_unique_key() instead, as that one calls this
method.
See the documentation of find_by_unique_key() for further
information on what the return value is used for and what
the implications are.
Example :
Returns : One or more references to hash(es) where each hash
represents one unique key, and the keys of each hash
represent the names of the object's slots that are part of
the particular unique key and their values are the values
of those slots as suitable for the key.
Args : The object with those attributes set that constitute the chosen
unique key (note that the class of the object will be suitable for
the adaptor).
A reference to an array of foreign key objects if not retrievable
from the object itself.