Persistent Base Class

Topics:

Overview
Conditional Directives
Constants
Type Definitions
Enumerations
Data Structures
Functions

Overview

The POD manager and Persistent base class comprise a persistent object framework used to create and maintain persistent objects. The Persistent base class is an abstract class used to define the interface that makes an object persistent. A persistent object is an object that saves its state in-between program invocations. Normally an object's data, stored in memory, is lost when the program terminates. Persistent objects store their data both in memory and in a disk file. When the program is terminated and restarted again, the persistent object can restore its last state by loading its data from the disk file.

In order for the objects of a class to become persistent, the class must inherit the Persistent base class, and define the methods needed to store its objects to disk. The Persistent base class will use the methods defined in the derived class to maintain the data file and index file(s) the database is connected to. The POD (Persistent Object Database) manager is used to manage file pointers to data files and multiple index files. Data files are used to store an object's data to disk. All data files are created by the 32/64-bit database engine and maintained by the Persistent base class. Index files are used to navigate the data file by associating a data key with the address where the object's data can be found in the data file. All index files are created by the 32/64-bit database engine and maintained by the B-tree class.

The public member functions of the Persistent base class will become public member functions in the derived class. The protected member functions and data members will become private members of the derived class. Pure virtual functions are used to define the persistent object interface. The derived class must override the pure virtual functions and define its own procedures for reading, writing, deleting, and searching for its objects in the database. This feature allows you to determine which data members of the derived class are stored in disk.

The Persistent base class is designed to work with or without index files. Index files add relational proprieties to the database. They are used to rapidly locate the objects in the data file using a B-tree algorithm. The B-tree nodes are composed of multiple entry keys consisting of a user-defined key type and a right child pointer. The entry keys are initialized and manipulated by the methods defined in the derived class. The Persistent base class provides the derived class with functions to add, remove, and find keys in the index file. The user-defined key type is responsible for associating data file addresses with the data key. This is generally accomplished by embedding an object ID in the data key. An object ID refers to the data file address of the object. Using data file addresses to identify objects ensures that each object will have a unique ID and allows the index file(s) to index duplicate key names.

The Persistent base class provides the derived class with special functions for reading and writing character strings to data files. Strings are stored by writing the length of the string in a 32-bit integer value and then writing the string itself to the file. If the string is zero bytes in length, one byte will be allocated for the string and a null byte is written in place of the zero length string. When reading a string from the data file, the string length stored on disk is used to allocate a memory buffer for the string plus a null byte. The last byte of the memory buffer is null-terminated. NOTE: With the exception of a zero length string, a null byte is never written at the end of the string. A string must always be null-terminated in memory, unless it is being used to represent a pattern of raw bytes.

Methods for reading and writing user defined types, pointers, and references within an object must be defined in the class derived from the Persistent base class. The gxDatabase engine provides its own platform interoperable integers to represent 16/32/64 bit signed and unsigned integers and 64 bit double precision floating point values. The persistent object database files will become platform dependent if built-in types such as short, int, long, float, or double are as persistent data members.

Data Structures

The object header data structure is used to represent the object headers. Object headers are an optional method used to identify objects in the data file by a unique class and object identification number.

// Object header use to ID objects in the data file
struct gxObjectHeader
{
  gxClassID ClassID;   // Class Identification number
  gxObjectID ObjectID; // Object Identification number
};

Object headers should always be stored directly after database block headers. The gxObjectHeader structure stores the class identification number and the object identification number for database objects. Unique object ID numbers can easily be obtained by using the data address to identify objects in the data and index file(s). Using the data file address ensures that the identity of each object will be unique and allows duplicate objects to be stored in the database. The class ID number is an arbitrary value used to identify an object in the database as being an object of a particular class. NOTE: Due to portability issues between the various C++ compilers the Persistent base class does not use RTTI (Run Time Type Information) to identify the objects in the database.

Functions

gxPersistent::gxPersistent()
gxPersistent::AddKey()
gxPersistent::Connect()
gxPersistent::Delete()
gxPersistent::DeleteKey()
gxPersistent::DeleteObject()
gxPersistent::Find()
gxPersistent::FindKey()
gxPersistent::FindObject()
gxPersistent::ObjectAddress()
gxPersistent::ObjectLength()
gxPersistent::Read()
gxPersistent::ReadObject()
gxPersistent::ReadObjectHeader()
gxPersistent::ReadString()
gxPersistent::StringFileLength()
gxPersistent::UsingIndex()
gxPersistent::Write()
gxPersistent::WriteObject()
gxPersistent::WriteObjectHeader()
gxPersistent::WriteString()

Derived class interface:
virtual int gxPersistent::Delete() - Protected pure virtual function that must be defined in the derived class as a private member function. Defines the procedure used to delete an object of the class inheriting the Persistent base class from disk. Must return true if the object was deleted or false if the object could not be deleted.

virtual int gxPersistent::Find() - Protected pure virtual function that must be defined in the derived class as a private member function. Used to find an object of the class inheriting the Persistent base class in the database. Must return true if the object was found or false if the object could not be found.

virtual __UWORD__ gxPersistent::ObjectLength() - Protected pure virtual function that must be defined in the derived class as a private member function. Returns the file length of the persistent data members in the derived class.

virtual gxDatabaseError gxPersistent::Read(FAU object_address) - Protected pure virtual function that must be defined in the derived class as a private member function. Defines the procedure used to read an object of the class inheriting the Persistent base class from disk at the file address specified. Must return zero if successful or a non-zero value corresponding to a gxDatabaseError enumerated type if an error occurs.

virtual gxDatabaseError gxPersistent::Write() - Protected pure virtual function that must be defined in the derived class as a private member function. Defines the procedure used to write an object of the class inheriting the Persistent base class to disk. Must return zero if successful or a non-zero value corresponding to a gxDatabaseError enumerated type if an error occurs.

Member Functions:
gxPersistent::gxPersistent(POD *DB) - Class constructor responsible for connecting the Persistent base class to a POD manager object that represents the open data file and the open index file.

gxPersistent::gxPersistent(const POD *DB) - Class constructor responsible for connecting the Persistent base class to a POD manager object that represents the open data file and the open index file.

gxPersistent::gxPersistent() - Default constructor used for creating objects that are connected to an open database when initially constructed.

gxPersistent::gxPersistent(const gxPersistent &ob) - Private class copy constructor used to disallow copying.

void gxPersistent::operator=(const gxPersistent &ob) - Private class assignment operator used to disallow assignment.

int gxPersistent::AddKey(DatabaseKeyB &key, DatabaseKeyB &compare_key, unsigned index_number = 0, int flush = 1) - Protected member function used to insert a key into the index file specified by the "index_number" variable. By default all disk buffers will be flushed following an insertion to maintain synchronization during multiple file access. NOTE: The "DatabaseKeyB& compare_key" is a type cast from the derived key class back to a DatabaseKeyB base type and is required to perform comparisons because the comparison operators are not defined in the DatabaseKeyB base class. Returns true if successful or false if the key could not be inserted.

gxDatabaseError gxPersistent::Connect(POD *DB) - Protected member function used to connect the Persistent base class to a POD manager object that represents the open database.

gxDatabaseError gxPersistent::Connect(const POD *DB) - Protected member function used to connect the Persistent base class to a POD manager object that represents the open database.

int gxPersistent::DeleteKey(DatabaseKeyB &key, DatabaseKeyB &compare_key, unsigned index_number = 0, int flush = 1) - Protected member function used to delete a key from the index file specified by the "index_number" variable. By default all disk buffers will be flushed following an insertion to maintain synchronization during multiple file access. NOTE: The "DatabaseKeyB& compare_key" is a type cast from the derived key class back to a DatabaseKeyB base type and is required to perform comparisons because the comparison operators are not defined in the DatabaseKeyB base class. Returns true if successful or false if the key could not be deleted.

int gxPersistent::DeleteObject(FAU object_address) - Public member function used to delete the object at the specified address according to the method defined in the derived class version of the Persistent::Delete() function. Return true if the object was deleted or false if the object could not be deleted.

int gxPersistent::DeleteObject() - Public member function used to delete this object according to the method defined in the derived class version of the Persistent::Delete() function. Return true if the object was deleted or false if the object could not be deleted.

int gxPersistent::FindKey(DatabaseKeyB &key, DatabaseKeyB &compare_key,unsigned index_number = 0, int test_tree = 1) - Protected member function used find a key in the index file specified by the "index_number" variable. NOTE: The "DatabaseKeyB& compare_key" is a type cast from the derived key class back to a DatabaseKeyB base type and is required to perform comparisons because the comparison operators are not defined in the DatabaseKeyB base class. Returns true if successful or false if the key could not be found.

int gxPersistent::FindObject() - Public member function used to find this object in the database according to the method defined in the derived class version of the Persistent::Find() function. Returns true if successful or false if the key could not be found.

FAU gxPersistent::ObjectAddress() - Public member function that returns the data file address of this object or zero if the object address is not known.

int gxPersistent::ReadObject(FAU object_address) - Public member function used to read an object from the database according to the method defined in the derived class version of the Persistent::Read() function. The object will be read at the specified file address. Returns true if successful or false if the object could not be read.

int gxPersistent::ReadObject() - Public member function used to read this object from the database according to the method defined in the derived class version of the Persistent::Read() function. Returns true if successful or false if the object could not be read.

gxDatabaseError gxPersistent::ReadObjectHeader(gxObjectHeader &oh, FAU object_address = (FAU_t)-1) - Protected member function used to read an object header. Returns zero if successful or a non-zero value corresponding to a gxDatabaseError enumerated type if an error occurs.

char *gxPersistent::ReadString(FAU file_address = (FAU_t) - Protected member function used to read a character string from the data file. Returns a pointer to a null terminated string or a null value if an error occurs. NOTE: The calling function must free the memory allocated for this string.

__UWORD__ gxPersistent::StringFileLength(const char *s) - Protected member function used to calculate the total number of bytes to be allocated for a character string in the data file.

__UWORD__ gxPersistent::StringFileLength(char *s) - Protected member function used to calculate the total number of bytes to be allocated for a character string in the data file.

int gxPersistent::UsingIndex() - Public member function that returns true if this database if using an index file.

int gxPersistent::WriteObject(int find = 1) - Public member function used to add a new object to the database according to the method defined in the derived class version of the Persistent::Write() function. By default this function will search the entire index file or data file for the object according to the derived class version of the Persistent::Find() function to determine if the object already exists. If find is false the object will be added without searching the database for duplicate entries. Returns true if successful or false if the object could not be added.

gxDatabaseError gxPersistent::WriteObjectHeader(const gxObjectHeader &oh, FAU object_address = (FAU_t) - Protected member function used to write an object header. Returns zero if successful or a non-zero value corresponding to a gxDatabaseError enumerated type if an error occurs.

gxDatabaseError gxPersistent::WriteString(const char *s, FAU file_address = (FAU_t) - Protected member function used to write a null terminated character string to the data file. Returns a non-zero value to indicate an error condition or zero if successful.

gxDatabaseError gxPersistent::WriteString(char *s, FAU file_address = (FAU_t) - Protected member function used to write a null terminated character string to the data file. Returns a non-zero value to indicate an error condition or zero if successful.