MAN page from Mandrake Other perl-Class-Eroot-19960603-1.i386.rpm

Eroot

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

Eroot - an eternal root to handle persistent objects

ABSTRACT

The Eternal Root (eroot) is given references to the root objects of anyobject hierarchies which must persist between separate invocations of theapplication. When the eroot's destructor is called, the eroot will find allobjects referenced in the object hierarchies and will store them. Allobjects will be restored (if possible) when and if the Continue messageis sent to the eroot.

SYNOPSIS

        require Class::Eroot;        my $some_obj;        my $eroot = new EROOT ( 'Name' => "persist.file",                                  'Key'  => "myAppObjects" );

        if( $eroot->Continue ){                # No existing objects.  Start from scratch.                $some_obj = new SomeObj;                $eroot->Keep( "Some_obj" => $some_obj );        }        else{                $some_obj = $eroot->Root("some_obj");        }

        $eroot->List;        $eroot->Keep( "MyObj" => $myobj );        $eroot->Lose( "Old_Obj" );        $eroot->Lose( $this_obj );

DESCRIPTION

When the eroot saves a group of object hierarchies, it stores its keywith them. The key of any objects being restored must match the key of theeroot which is trying to restore them. The Continue method will calldie if the keys do not match. Continue will return 0 if the objects wereloaded and non-zero if they were not.

The eroot will attempt to send a suspend message to the object prior tostoring the object's state. The object's class is not required to have asuspend method defined.

When the eroot restores an object it will bless the object reference in theobject's class (package) and will attempt to send a resume message to theobject. The object's class is not required to have a resume method defined.

An object should not propagate suspend and resume messages. The erootwill send suspend messages to the objects in the order in which they werestored in the eroot (breadth-first, root-to-leaves). The eroot will sendresume messages by starting with the classes of the objects at the leaves ofthe object hierarchy and moving toward the root of the object hierarchy.

Note that Perl will call the destructors of the persistent objects. Theprogrammer should be prepared to deal with this.

It is necessary to Keep an object only once. The object will remainpersistent until the eroot is told to Lose it.

INSTANCE VARIABLES

References will be properly hooked up if they are type SCALAR, ARRAY, REF,or HASH. The eroot assumes that keys and values (if the value is not areference) for the objects' instance variables can be represented as textwithin single quotes. If this is not true for your objects then the object'ssuspend method can be used to ``wrap'' the object for storage, and theresume method can be used to ``unwrap'' the object.

Embedded single quotes in the value will be preserved. This iscurrently the only place where single quotes are handled.

THINGS TO AVOID

        o Storing the eroot.        o Storing references to tie()'d variables and objects.        o Storing references to CODE objects.        o Storing the same object in two different eroots.          Unless you think you know what you're doing, of course.        o Using two eroots to store each other :)        o Storing named arrays and hashes.  These will be restored as          anonymous arrays and hashes.        o Storing an object while it has an open stream.        o Storing an object which has an %OVERLOAD somewhere in          it's class hierarchy.

Know your object hierarchy. Be sure that everything in the hierarchycan handle persistence.

NOTES

This is not an OODBMS.

FILES

        Class::Eroot.pm - Eternal Root class.        persist.file    - User-defined file where objects are stored.        Class::Template.pm      - Struct/member template builder.

This document was created byman2html,using the manual pages.