/ 
bioperl-db-1.5.2_100
/ Bio::DB::Persistent::PersistentObject

NAME

Bio::DB::Persistent::PersistentObject - makes a given object persistent

SYNOPSIS

# obtain a PersistentObject somehow, e.g.
$pobj = $dbadaptor->create_persistent("Bio::Seq");

# manipulate and query as if it were the wrapped object itself
print $pobj->isa("Bio::PrimarySeqI"), "\n";
$pobj->display_id("O238356");
$pobj->seq("ATCATCGACTGACAGGCAGTATCGACTAGCA");
$fea = Bio::SeqFeature::Generic->new(-start => 3, -end => 15);
$fea->attach_seq($pobj);
# and so on and so forth

# and, finally, or whenever suitable, make it persistent in the datastore
$pobj->create();
# change it
$pobj->desc("not a useful description");
# and update it in the datastore
$pobj->store();

# you may also want it to disappear
$pobj->remove();

DESCRIPTION

This class takes any Bioperl object for which an adaptor exists for a certain datastore and makes it implement Bio::DB::PersistentObjectI.

There is one single caveat though. The wrapped object must not use any of the method names defined in Bio::DB::PersistentObjectI, nor obj() or adaptor(). If it does, calls of these methods will never get routed to the wrapped object.

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 lists

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://bugzilla.open-bio.org/

AUTHOR - Hilmar Lapp

Email hlapp at gmx.net

Describe contact details here

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::Persistent::PersistentObject();
Function: Builds a new Bio::DB::Persistent::PersistentObject object 
Returns : an instance of Bio::DB::Persistent::PersistentObject
Args    : -object => $obj_to_be_wrapped (mandatory)
          -adaptor => $adaptor_for_obj (optional, may be set later)

create

Title   : create
Usage   : $obj->create()
Function: Creates the object as a persistent object in the datastore. This
          is equivalent to an insert.

          Note that you will be able to retrieve the primary key at any time
          by calling primary_key() on the object.
Example :
Returns : The newly assigned primary key.
Args    : 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   : $obj->store()
Function: Updates the persistent object in the datastore to reflect its
          attribute values.
Example :
Returns : TRUE on success and FALSE otherwise
Args    : 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   : $obj->remove()
Function: Removes the persistent object from the datastore.
Example :
Returns : TRUE on success and FALSE otherwise
Args    : none

primary_key

Title   : primary_key
Usage   : $obj->primary_key($newval)
Function: Get the primary key of the persistent object in the datastore.

          Note that this implementation does not permit changing the
          primary key once it has been set. This is for sanity
          reasons, and may or may not be relaxed in the future. The
          only exception is changing it to undef.

Example : 
Returns : value of primary_key (a scalar)
Args    : new value (a scalar, optional)

obj

Title   : obj
Usage   : $obj->obj()
Function: Get/set the object that is made persistent through this adaptor.

          Note that this implementation does not allow to change the
          value once it has been set. This is for sanity reasons, and
          may or may not be relaxed in the future.

Example : 
Returns : The object made persistent through this adaptor
Args    : On set, the new value. Read above for caveat.

adaptor

Title   : adaptor
Usage   : $obj->adaptor($newval)
Function: Get/set of the PersistenceAdaptorI compliant object that actually
          implements persistence for this object
Example : 
Returns : A Bio::DB::PersistenceAdaptorI compliant object
Args    : Optionally, on set a Bio::DB::PersistenceAdaptorI compliant object

is_dirty

Title   : is_dirty
Usage   : $obj->is_dirty($newval)
Function: Get/set whether this persistent object is to be considered
          dirty.

          An object is considered dirty if one or more of it's
          properties has been altered since it was last obtained
          from, stored in, or created in the database, or if the
          create() (insert) or the last store() (update) hasn't been
          committed or rolled back yet.

          There are currently 3 known states of this attribute. A
          value of zero (or false) means the object has not been
          modified since it either came from the database, or since
          the changes have been serialized (via store()) and
          committed (via commit()). A negative value means changes
          have been serialized, but not yet committed. A positive
          value means there have been unserialized changes on the
          object.

Example : 
Returns : value of is_dirty (a scalar)
Args    : on set, new value (a scalar or undef, optional)

Methods for transactional control

Rollback and commit

commit

Title   : commit
Usage   :
Function: Commits the current transaction, if the underlying driver
          supports transactions.
Example :
Returns : TRUE
Args    : none

rollback

Title   : rollback
Usage   :
Function: Triggers a rollback of the current transaction, if the
          underlying driver supports transactions.
Example :
Returns : TRUE
Args    : none

Methods to mimic the wrapped object

isa

Title   : isa
Usage   :
Function: This is a standard perl object method. We override it here in order
          to generically claim we implement everything that the wrapped
          object does.
Example :
Returns : TRUE if this object is an instance of the given class, or inherits
          from the given class, and FALSE otherwise
Args    : the class to query for (a scalar string)

can

Title   : can
Usage   :
Function: This is a standard perl object method. We override it here in order
          to generically claim we 'can' everything that the wrapped
          object does.
Example :
Returns : TRUE if this object is has the named method, and FALSE otherwise
Args    : the method to query for (a scalar string)

Implementation of the decorating methods

See Bio::DB::PersistentObjectI for further documentation of the methods.

rank

Title   : rank
Usage   : $obj->rank($newval)
Function: Get/set the rank of this persistent object in a 1:n or n:n
          relationship.

Example : 
Returns : value of rank (a scalar)
Args    : new value (a scalar or undef, optional)

foreign_key_slot

Title   : foreign_key_slot
Usage   : $obj->foreign_key_slot($newval)
Function: Get/set of the slot name that is referring to this persistent
          object as a foreign key.

Example : 
Returns : value of foreign_key_slot (a scalar)
Args    : new value (a scalar or undef, optional)