Bio::Root::Storable.3pm

Langue: en

Version: 2010-05-19 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

NAME

Bio::Root::Storable - object serialisation methods

SYNOPSIS

   my $storable = Bio::Root::Storable->new();
 
   # Store/retrieve using class retriever
   my $token     = $storable->store();
   my $storable2 = Bio::Root::Storable->retrieve( $token );
 
   # Store/retrieve using object retriever
   my $storable2 = $storable->new_retrievable();
   $storable2->retrieve();
 
 

DESCRIPTION

Generic module that allows objects to be safely stored/retrieved from disk. Can be inhereted by any BioPerl object. As it will not usually be the first class in the inheretence list, _initialise_storable() should be called during object instantiation.

Object storage is recursive; If the object being stored contains other storable objects, these will be stored seperately, and replaced by a skeleton object in the parent heirarchy. When the parent is later retrieved, its children remain in the skeleton state until explicitly retrieved by the parent. This lazy-retrieve approach has obvious memory efficiency benefits for certain applications.

By default, objects are stored in binary format (using the Perl Storable module). Earlier versions of Perl5 do not include Storable as a core module. If this is the case, ASCII object storage (using the Perl Data::Dumper module) is used instead.

ASCII storage can be enabled by default by setting the value of $Bio::Root::Storable::BINARY to false.

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 one of the Bioperl mailing lists. Your participation is much appreciated.
   bioperl-l@bio.perl.org
 
 

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 the bugs and their resolution. Bug reports can be submitted via the web:
   http://bugzilla.open-bio.org/
 
 

AUTHOR - Will Spooner

Email whs@sanger.ac.uk

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

new

   Arg [1]   : -workdir  => filesystem path,
               -template => tmpfile template,
               -suffix   => tmpfile suffix,
   Function  : Builds a new Bio::Root::Storable inhereting object
   Returntype: Bio::Root::Storable inhereting object
   Exceptions: 
   Caller    : 
   Example   : $storable = Bio::Root::Storable->new()
 
 

_initialise_storable

   Arg [1]   : See 'new' method
   Function  : Initialises storable-specific attributes
   Returntype: boolean
   Exceptions: 
   Caller    : 
   Example   :
 
 

statefile

   Arg [1]   : string (optional)
   Function  : Accessor for the file to write state into.
               Should not normaly use as a setter - let Root::IO
               do this for you.
   Returntype: string
   Exceptions: 
   Caller    : Bio::Root::Storable->store
   Example   : my $statefile = $obj->statefile();
 
 

workdir

   Arg [1]   : string (optional) (TODO - convert to array for x-platform)
   Function  : Accessor for the statefile directory. Defaults to File::Spec->tmpdir
   Returntype: string
   Exceptions: 
   Caller    : 
   Example   : $obj->workdir('/tmp/foo');
 
 

template

   Arg [1]   : string (optional)
   Function  : Accessor for the statefile template. Defaults to XXXXXXXX
   Returntype: string
   Exceptions: 
   Caller    : 
   Example   : $obj->workdir('RES_XXXXXXXX');
 
 

suffix

   Arg [1]   : string (optional)
   Function  : Accessor for the statefile template.
   Returntype: string
   Exceptions: 
   Caller    : 
   Example   : $obj->suffix('.state');
 
 

new_retrievable

   Arg [1]   : Same as for 'new'
   Function  : Similar to store, except returns a 'skeleton' of the calling
               object, rather than the statefile.
               The skeleton can be repopulated by calling 'retrieve'. This
               will be a clone of the original object.
   Returntype: Bio::Root::Storable inhereting object
   Exceptions: 
   Caller    : 
   Example   : my $skel = $obj->new_retrievable(); # skeleton 
               $skel->retrieve();                  # clone
 
 

retrievable

   Arg [1]   : none
   Function  : Reports whether the object is in 'skeleton' state, and the
               'retrieve' method can be called.
   Returntype: boolean
   Exceptions: 
   Caller    : 
   Example   : if( $obj->retrievable ){ $obj->retrieve }
 
 

token

   Arg [1]   : None
   Function  : Accessor for token attribute
   Returntype: string. Whatever retrieve needs to retrieve.
               This base implementation returns the statefile
   Exceptions: 
   Caller    : 
   Example   : my $token = $obj->token();
 
 

store

   Arg [1]   : none
   Function  : Saves a serialised representation of the object structure
               to disk. Returns the name of the file that the object was
               saved to.
   Returntype: string
 
   Exceptions: 
   Caller    : 
   Example   : my $token = $obj->store();
 
 

serialise

   Arg [1]   : none
   Function  : Prepares the the serialised representation of the object.
               Object attribute names starting with '__' are skipped.
               This is useful for those that do not serialise too well
               (e.g. filehandles).
               Attributes are examined for other storable objects. If these
               are found they are serialised seperately using 'new_retrievable'
   Returntype: string
   Exceptions: 
   Caller    : 
   Example   : my $serialised = $obj->serialise();
 
 

retrieve

   Arg [1]   : string; filesystem location of the state file to be retrieved
   Function  : Retrieves a stored object from disk.
               Note that the retrieved object will be blessed into its original
               class, and not the
   Returntype: Bio::Root::Storable inhereting object
   Exceptions: 
   Caller    : 
   Example   : my $obj = Bio::Root::Storable->retrieve( $token );
 
 

clone

   Arg [1]   : none
   Function  : Returns a clone of the calling object
   Returntype: Bio::Root::Storable inhereting object
   Exceptions: 
   Caller    : 
   Example   : my $clone = $obj->clone();
 
 

remove

   Arg [1]   : none
   Function  : Clears the stored object from disk
   Returntype: boolean
   Exceptions: 
   Caller    : 
   Example   : $obj->remove();
 
 

_freeze

   Arg [1]   : variable
   Function  : Converts whatever is in the the arg into a string.
               Uses either Storable::freeze or Data::Dumper::Dump
               depending on the value of $Bio::Root::BINARY
   Returntype: 
   Exceptions: 
   Caller    : 
   Example   :
 
 

_thaw

   Arg [1]   : string
   Function  : Converts the string into a perl 'whatever'.
               Uses either Storable::thaw or eval depending on the
               value of $Bio::Root::BINARY.
               Note; the string arg should have been created with 
               the _freeze method, or strange things may occur!
   Returntype: variable
   Exceptions: 
   Caller    : 
   Example   :