NAME

Eroot - an eternal root to handle persistent objects

ABSTRACT

The Eternal Root (eroot) is given references to the root objects of any object hierarchies which must persist between separate invocations of the application. When the eroot's destructor is called, the eroot will find all objects referenced in the object hierarchies and will store them. All objects will be restored (if possible) when and if the Continue message is 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 key with them. The key of any objects being restored must match the key of the eroot which is trying to restore them. The Continue method will call die if the keys do not match. Continue will return 0 if the objects were loaded and non-zero if they were not.

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

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

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

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

It is necessary to Keep an object only once. The object will remain persistent 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 a reference) for the objects' instance variables can be represented as text within single quotes. If this is not true for your objects then the object's suspend method can be used to "wrap" the object for storage, and the resume method can be used to "unwrap" the object.

Embedded single quotes in the value will be preserved. This is currently 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 hierarchy can 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.