PersistentObject(3) User Contributed Perl Documentation PersistentObject(3)NAMENOCpulse::PersistentObject - an abstract PERL class that provides a
primitive persistence mechanism for named objects.
SYNOPSIS
package MyClass;
use NOCpulse::PersistentObject;
@ISA qw(NOCpulse::PersistentObject);
...
my $thing = NOCpulse::PersistentObject->newInitializedNamed('hello');
$thing->persist;
$sameThing = NOCpulse::PersistentObject->loadFromDatabase('hello');
DESCRIPTIONNOCpulse::PersistentObject is a layer above Object that adds primitive
object persistence via the FreezeThaw based serialization mechanism
defined in Object.
To set up this mechanism, you must:
* Set up an Object::SystemIni() file for the class hierarchy
And for each class you must:
* Add a section to the SystemIni file whose name is the name of your
class
* Add an item to that section called "databaseDirectory" whose value is
a path to the directory where the instance database is to live
* Add an item to that section called "databaseType" whose value is the
name of a properly fleshed out subclass of AbstractObjectRepository
(for instance
NOCpulse::DBMObjectRepository).
Classes derived from NOCpulse::PersistentObject will have an instance
variable called "name" defined for them. The name variable is the
means by which the persistence mechanism keeps track of stored objects.
You must come up with a scheme that ensures that each instance of a
given class has a name value that is unique among all instances.
Insofar as the name attribute is crucial to the inner workings of the
persistence mechanisms, a number of new constructors are defined:
newNamed(<name>) newInitializedName(<name>[,@opts])
loadFromDatabase(<name>)
You should use these instead of the Object constructors to ensure that
the persistence mechanism has everything set up properly.
REQUIRES
Object
EXPORTS
nothing
MODULE VARIABLES
$config - holds an Config::IniFiles instance if one was created with
SystemIni()CLASS VARIABLES
%classvars - holds hashes of "class instance" variables
MODULE METHODS
none
CLASS METHODSdatabaseType()
Returns the name of the database type used to store objects of this
class (as currently configured)
databaseDirectory()
Returns the path of the directory in which the databaseType will
store objects of this class (as currently configured). Looks first
for a class variable called databaseDirectory, then at the class
ini section for an entry called databaseDirectory.
databaseFilename()
Returns the full path name of the file that databaseType will store
objects in.
database()
Returns the database instance for this class
instances()
Returns a hash of all the instances of the class currently in
memory
named(<name>)
Returns the instance named <name> if it is currently in memory
saveToDatabase()
Saves all objects currently in memory to the repository. Also see
persist() (below)
loadFromDatabase([<name> [, <use-cache]])
If called with no parameters, loads all objects from the repository
into memory and returns a pointer to the instances() hash
If called with the <name> parameter, loads the named object from
the repository into memory (adding it to the instances list) and
returns the instance.
If called with <name> and <use-cache>, first checks for a cached
instances and returns it if present, otherwise loads as above.
newNamed(<name>)
Creates an instance of the class whose name is <name> in memory and
returns it.
newNamed(<name>[,@params])
Creates an instance of the class whos name is <name> in memory,
calls its initialize() method with [@params], and returns the
instance.
INSTANCE METHODSinstVarDefinitions()
Same as that for Object, but Subclasses MUST call
$self-SUPER::instVarDefinitions> if they override this.
persist()
Writes the instance in question to the object repository
immediately.
doesNotUnderstand(...)
Overrides AUTOLOADed get_xxx in Object behavior such that instances
can retrieve values from its class .ini file on a per instance
basis.
Explanation: If you set up a per-class .ini file according to
Object::ConfigValue(), you this extension to the get_xxx protocol
allows you to exploit the fact that all instances of
NOCpulse::PersistentObject have a unique name. Specifically, once
you have an instantiated NOCpulse::PersistentObject, a call to
get_xxx (where xxx is any name) that would otherwise fail for the
lack of an instance variable will now first check to see if your
class per-class .ini file has a section whose name is the name of
the current instance. If such a section is found, its namespace
will be "added" to that of the instance virtually via the get_xxx
call.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 304:
You forgot a '=back' before '=head1'
Around line 392:
You forgot a '=back' before '=head1'
perl v5.14.1 2010-08-26 PersistentObject(3)