Bio::Root::Storable(3pm)

NAME
Bio::Root::Storable - Safely store/retrieve objects from disk

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 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.

AUTHOR Will Spooner

  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 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();

  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 separately 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   :