Bio::Root::Storable - Safely store/retrieve objects from disk
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 separately, and replaced by a skeleton object in
the parent hierarchy. 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.
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()
Arg [1] : See 'new' method
Function : Initialises storable-specific attributes
Returntype: boolean
Exceptions:
Caller :
Example :
Arg [1] : string (optional)
Function : Accessor for the file to write state into.
Should not normally use as a setter - let Root::IO
do this for you.
Returntype: string
Exceptions:
Caller : Bio::Root::Storable->store
Example : my $statefile = $obj->statefile();
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');
Arg [1] : string (optional)
Function : Accessor for the statefile template. Defaults to XXXXXXXX
Returntype: string
Exceptions:
Caller :
Example : $obj->workdir('RES_XXXXXXXX');
Arg [1] : string (optional)
Function : Accessor for the statefile template.
Returntype: string
Exceptions:
Caller :
Example : $obj->suffix('.state');
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
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 }
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();
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();
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 separately using 'new_retrievable'
Returntype: string
Exceptions:
Caller :
Example : my $serialised = $obj->serialise();
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 );
Arg [1] : none
Function : Returns a clone of the calling object
Returntype: Bio::Root::Storable inhereting object
Exceptions:
Caller :
Example : my $clone = $obj->clone();
Arg [1] : none
Function : Clears the stored object from disk
Returntype: boolean
Exceptions:
Caller :
Example : $obj->remove();
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 :
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 :