Persistent - persistent object package for Graphic

#include <InterViews/Graphic/persistent.h>

Persistent is a class that implements a general persistent object. Persistent objects can exist in memory, on disk, or both; the implementation supports a transparent interface to objects regardless of their location. Thus persistent objects can exist beyond the lifetime of the programs that create and use them. Though Persistent was designed to support the persistent structured graphics provided by Graphic , programmers can build their own persistent classes by deriving from Persistent. The file need not be included if Graphic header files are already included; it should be included only when deriving new Persistent objects.

The following operations are defined on Persistent objects:
virtual ~Persistent()

Deleting a persistent object will flush it from the object manager cache.

virtual ClassId GetClassId()

Every class derived from Persistent must have a globally unique identifier associated with it. This member function must be redefined in derived classes to return the identifier reserved for that class.

virtual bool IsA(ClassId)

Returns true if the persistent object is an instance of the class (or subclass of the class) specified by the given ClassId. This member function must be redefined in derived classes to return the appropriate value.

virtual Persistent* GetCluster()

If a persistent object (the parent object) contains other persistent objects as part of its internal state, then the parent and the objects it contains can be clustered on disk, or written and read consecutively. This can improve performance when the parent object is read since the objects within it are not scattered throughout the disk. GetCluster is called internally to determine whether the object is clustered within a parent or not. GetCluster returns this by default, meaning that the object is not to be clustered within another. If GetCluster is redefined to return nil, then the object is assumed to be clustered within a parent and will be written and read automatically whenever the parent is written or read.

virtual bool write(File* f)
virtual bool read(File* f)

These functions define what information is written and read when the persistent object is transferred to and from disk. The argument is a class (defined in <InterViews/Graphic/file.h>) that encapsulates stdio file operations. ParentClass::read(f) must be called in the read function before anything else is read. Similarly, ParentClass::write(f) must be called in the write function before anything else is written. Write and read operations typically write and read ASCII and/or binary data and/or references to other persistent objects (provided by the Ref class, described below). Write and read return false if the operation was unsuccessful for any reason; otherwise they return true. These functions should not perform any operation (such as File::SeekTo and the like, or dereferencing a Ref) that changes the position of the next input or output operation on the File.

virtual bool writeObjects(File* f)
virtual bool readObjects(File* f)

These functions define what clustered persistent objects should be written and read along with instances of the class. ParentClass::readObjects(f) must be called in the readObjects function before anything else is read. Similarly, ParentClass::writeObjects(f) must be called in the writeObjects function before anything else is written. WriteObjects and readObjects operations typically perform WriteObjects and ReadObjects operations on references to other persistent objects that were written/read in the write and read functions. WriteObjects and readObjects return false if the operation was unsuccessful for any reason, otherwise they return true. These functions should not perform any operation that changes the position of the next input or output operation on the File.

virtual bool initialize()

Initialize can be used to initialize an object's internal state with pointers to its clustered objects. Dereferencing of Refs to clustered objects should only take place in this function, not in read or readObjects. ParentClass::initialize() should be called in this function before anything else is done.

virtual bool Save()

Explicitly saves the object. Persistent objects that are part of a cluster should not be saved explicitly since they are automatically written and read with the parent object.

virtual bool IsDirty()
virtual void Touch()
virtual void Clean()

A dirty bit is maintained for each persistent object. IsDirty returns the status of the dirty bit, Touch sets the dirty bit, and Clean resets it. Persistent objects are automatically touched when they are created.

The Ref class provides a mechanism for referring to a persistent object in a manner analogous to pointer references to conventional objects. Refs are dereferenced to yield the object to which they refer. They can be compared with each other, tested for validity, written to and read from disk. Each Ref has a unique universal identifier (UID) that serves as the object's ``address''. Ref is defined in <InterViews/Graphic/ref.h>.
Ref()
Ref(UID)
Ref(Persistent*)

A parameterless constructor creates a nil (undefined) reference. The constructor with a UID argument creates a reference with a particular UID; this constructor should not be used unless one knows what he or she is doing. The third constructor is the one most commonly used. It creates a reference to the given object.

Persistent* operator()()

Parenthesis are overloaded to perform the dereferencing operation on a Ref. The return value will most likely have to be cast into a pointer to the proper derived persistent class.

bool operator==(Ref r)
bool operator!=(Ref r)

Refs can be compared for equality and inequality using these overloaded operators.

bool Write(File*)
bool Read(File*)

Write or read a reference to an object. Theses functions return false if the operation is unsuccessful for any reason; otherwise true is returned.

bool WriteObjects(File*)
bool ReadObjects(File*)

Write or read consecutively the object(s) referenced by the Ref. If the referenced object is the head of a cluster, then these operations are nop's. These functions return false if the operation is unsuccessful for any reason; otherwise true is returned.

A RefList is class derived from Ref used to form circular doubly-linked lists of references to persistent objects. Each RefList object references a persistent object and contains pointers to the RefLists preceding and following it in the list. The RefList class is defined in <InterViews/Graphic/reflist.h>.

RefList()
RefList(UID u)
RefList(Persistent*)

RefList constructors perform the same functions as their Ref counterparts.

void SetRef(Ref r)

Explicitly set the reference to the given one.

bool IsEmpty()

Returns true if the RefList has no neighbors, false otherwise.

void Append(RefList*)
void Prepend(RefList*)

Append inserts the given RefList after this; prepend inserts it before this.

void Remove(RefList*)
void Delete(Ref)
RefList* Find(Ref)

Remove finds the given RefList and removes it from the list. Delete finds the given Ref and deletes the RefList containing it. Find returns the RefList containing the given Ref.

RefList* First()
RefList* Last()
RefList* End()
RefList* Next()
RefList* Prev()

These functions return a particular element of the list relative to the position of this RefList in the list. First returns a pointer to the RefList following this, Last returns a pointer to the last RefList starting from this, and End returns a pointer to the RefList marking the end of the list. Next and Prev return pointers to the RefLists following and preceding this in the list.

bool Write(File*)
bool Read(File*)
bool WriteObjects(File*)
bool ReadObjects(File*)

These functions behave just as their Ref counterparts do, except they perform their operations on all elements in the RefList.

RefList* operator[](int n)

Returns a pointer to the nth element in the RefList, returning this if n = 0, this->Next() for n = 1, etc.

The ObjectMan class implements the object manager, a one-of-a-kind global object responsible for reading and writing persistent objects to and from disk. The object manager also serves as a well-known entity from which programs can retrieve the persistent objects they have created. ObjectMan is derived from Persistent and so is itself persistent. There is exactly one object manager per group of related persistent objects; no references can exist between persistent objects created by different object managers (different in the sense that they use different files for storage). Most of the member functions defined in ObjectMan need never be used by programs unless they derive new persistent classes.

ObjectMan(char* filename, void (*userInit)(RefList*) = nil, Persistent* (*userCreator)(ClassId) = nil)

The filename parameter requires a null-terminated string which will be used to prefix the names of two files that will contain all persistent object information: filename.map and filename.sto. If these files do not already exist when the constructor is called, then they will be created and the function pointed to by userInit will be called. userInit must point to a function that creates primordial root objects needed by your application and installs them in the passed RefList. If you want to use the default persistent paint objects in Graphic, then this function should call InitPPaint, defined in . userCreator must point to a function that can create an instance of any persist object used in the application, given a ClassId. userCreator should call GraphicConstruct, defined in <InterViews/Graphic/grconstruct.h>, if it receives an unrecognized ClassId. If your application does not derive any new persistent objects, userCreator can simply point to GraphicConstruct. A newly allocated object manager should be assigned to the global variable TheManager. Further references to the object manager should be made via this global.

RefList* GetRoot()

Returns a pointer to the RefList containing well-known objects. Persist objects that are to be accessed directly should have references to them appended to the root RefList in a well-known order for later retrieval. For example, the default persistent paint objects defined in InitPPaint should be appended to the root RefList so that they can be accessed when the program is restarted.

Persistent* Create(ClassId)

Creates a persistent object of class specified by ClassId. Create calls the function pointed to by userCreator.

bool Invalidate(Persistent*)

Used to permanently deallocate a persistent object. Returns false if the operation was unsuccessful, otherwise returns true.

bool IsCached(Ref*)

Returns true if the referenced object has been read from disk into memory, false if not. IsCached updates the reference to reflect the address of the object if it is in memory.

bool Find(Ref*)

Seeks for and reads the referenced object from disk if it is not in memory and updates the reference to reflect the memory address of the object. Find returns true if the operation was successful.

bool Retrieve(Ref*)

Like Find except does not perform a seek; the object is read blindly from disk. Retrieve is used to read clustered objects.

bool Store(Persistent*)
bool Update(Persistent*)

Store allocates new disk space for an object and writes it to disk. Update rewrites an existing object and updates the map containing its disk offset. Both return true if the operation was successful.

bool ObjectIsDirty(Persistent*)
void ObjectTouch(Persistent*)
void ObjectClean(Persistent*)

The object manager maintains a dirty bit for each persistent object in its object cache. These functions allow the dirty bit for an object to be tested, set and reset. The dirty bit operations defined in Persistent actually call these functions through the global variable TheManager. Dirty objects are automatically written to disk when TheManager is deleted.

Introduction