Bio::Root::Storable - object serialisation methods 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(); 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.

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

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 email or the web: bioperl-bugs@bio.perl.org http://bugzilla.bioperl.org/ Email whs@sanger.ac.uk 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 $Bio::Root::IO::TEMPDIR 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 :