Persistence::Object::Simple - Object Persistence with Data::Dumper.
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 ();
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, Non-OO Usage and the persistent list class example (examples/Plist.pm).
- 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.
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 };
- 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 Non-OO Usage.
- 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" );
- 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 Data::Dumper.
- 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' );
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 perlobj,
perlbot, and perltoot, 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.
load() and commit() can be used for storing
non-object references. Here's a section from examples/pdataref:
@list = 0..100;
Persistence::Object::Simple::commit
( undef, __Fn => '/tmp/datarefs/numbers',
Data => \@list;
);
$list = Persistence::Object::Simple::load
( undef, __Fn => '/tmp/datarefs/numbers' );
$" = "\n"; print "@$list";
Data::Dumper(3), Persistence::User(3), perl(1).
Vipul Ved Prakash, mail@vipul.net
Copyright (c) 1998, Vipul Ved Prakash. All rights reserved. This code is
free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
|