Christopher Fields
and 1 contributors

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

Support

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

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 = Bio::DB::Persistent::PersistentObject->new();
 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)