NAME

Persistence::Object::Simple - Object Persistence with Data::Dumper.

SYNOPSIS

  use Persistence::Object::Simple;
  my $perobj = new Persistence::Object::Simple ( __Fn   => $path );
  my $perobj = new Persistence::Object::Simple ( __Dope => $directory );
  my $perobj = new Persistence::Object;
  my $perobj->commit ();

DESCRIPTION

P::O::S provides persistence functionality to its objects. Object definitions are stored as stringified perl data structures, generated with Data::Dumper, that are amenable to manual editing and external processing from outside the class interface.

Persistence is achieved with a blessed hash container that holds the object data. The container can store objects that employ non-hash structures as well. See Inheriting Persistence::Object::Simple, Class Methods and the persistent list class example (examples/Plist.pm).

CONSTRUCTOR

new()

Creates a new Persistent Object or retrieves an existing object definition. Takes a hash argument with following possible keys:

__Fn: Pathname of the file that contains the persistent object definition. __Fn is treated as the object identifier and required at object retrieval.
__Dope: The Directory of Persistent Entities. P::O::S generates a unique filename to store object data in the specified directory. The object identifier is the complete pathname of the object's persistent image and is placed in the __Fn instance variable. This argument is ignored when __Fn is provided.
__Create: A boolean attribute that can either take a ``Yes'' or a ``No'' value. It informs the method whether to create an object image if one doesn't already exist. __Create is ``yes'' by default.
__Random: Random string used as input for computing the unique object name. This should be used when unpredictable object names are required for security reasons. The random string can be generated with Crypt::Random, a module which provides cryptographically secure random numbers.

When new() is called without any arguments it uses a unique file in the default DOPE, ``/tmp'', to store the object definition. The default DOPE can be altered with the dope() method.

 $po = new Persistence::Object::Simple
       ( __Fn => "/tmp/codd/suse5.2.codd" );

 # -- generates a unique filename  in /tmp/codd
 $po  = new Persistence::Object::Simple
       ( __Dope => "/tmp/codd" );
 print $po->{ __Fn };

 # -- generates a unique filename in defalt dope (/tmp)
 $po  = new Persistence::Object::Simple;
 print $po->{ __Fn };

METHODS

commit()

Commits the object to disk. Like new() it takes __Fn and __Dope arguments, but __Dope takes precedence. When a __Dope is provided, the directory portion of the object filename is ignored and the object is stored in the specified directory.

    $perobj->commit ();
    $perobj->commit (  __Fn   => $foo );
    $perobj->commit (  __Dope => $bar );

Commit() can also store non-object data refs. See Class Methods.

expire()

Irrevocably destructs the object. Removes the persistent entry from the DOPE.

    $perobj->expire ();

If you want to keep a backup of the object before destroying it, use commit() to store in a different location. Undefing $obj->{ __Fn } before writing to the disk will force commit() to store the object in a unique file in the specified DOPE.

    $perobj->{ __Fn } = undef;
    $perobj->commit ( __Dope => "/tmp/dead" );
    $perobj->expire ();

move()

Moves the object to a different DOPE.

    $perobj->move ( __Dope => "/some/place/else" );

Specifying __Fnalter attribute will force move() to drop the existing file name and generate a new one in specified directory. This can be useful when backing up objects that may have the same filename.

    $perobj-> ( __Dope => 'queues/backup',
                __Fnalter => 1 );

lock()

Gets an exclusive lock. The owner of the lock can commit() without unlocking.

    $perobj->lock ();

unlock()

Releases the lock.

    $perobj->unlock ();

dumper()

Returns the Data::Dumper instance bound to the object. Should be called before commit() to change Data::Dumper behavior.

    my $dd = $perobj->dumper ();
    $dd->purity (1);
    $dd->terse  (1);  # -- smaller dumps.
    $perobj->commit ();

See the Data::Dumper manpage.

load()

Class method that retrieves and builds the object. Takes a filename argument. Don't call this directly, use new () for object retrieval.

    Persistence::Object::Simple->load (
        __Fn => '/tmp/dope/myobject'
    );

Inheriting Persistence::Object::Simple

In most cases you would want to inherit this module. It does not provide instance data methods so the object data functionality must be entirely provided by the inheriting module. Moreover, if you use your objects to store refs to class data, you'd need to bind and detach these refs at load() and commit(). Otherwise, you'll end up with a separate copy of class data with every object which will eventually break your code. See the perlobj manpage, the perlbot manpage, and the perltoot manpage, on why you should use objects to access class data.

Persistence::Database inherits this module to provide a transparently persistent database class. It overrides new(), load() and commit() methods. There is no class data to bind/detach, but load() and commit() are overridden to serve as examples/templates for derived classes. Data instance methods, AUTOLOADed at runtime, automatically commit() when data is stored in Instance Variables. For more details, Read The Fine Sources.

Class Methods

load() and commit() can be used for storing non-object references. commit() and load() can be invoked as class methods with a ``Data'' argument. Some examples:

 # generates a unique filename in /tmp
 my $fn = Persistence::Object::Simple->commit (
     __Dope => "/tmp", Data => $x );

 @list = 0..100;
 Persistence::Object::Simple->commit
  ( __Fn => '/tmp/datarefs/numbers',
    Data => \@list;
  );

 $list = Persistence::Object::Simple->load
  ( __Fn => '/tmp/datarefs/numbers' );

 $" = "\n"; print "@$list";

AUTHOR

Vipul Ved Prakash, <mail@vipul.net>

COPYRIGHT

CONTRIBUTORS

Mike Blazer <blazer@mail.nevalink.ru> helped with the Win32 Port.
Holger Heimann <hh@it-sec.de> helped with debugging.
Kirrily 'Skud' Robert, <skud@infotrope.net> patched P::O::S to be taint-friendly.

Persistence::Object::Simple - Object Persistence with Data::Dumper.