Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
Essential Tools Module User's Guide

9.5 Isomorphic Persistence

Isomorphic persistence is the storage and retrieval of objects to and from a stream such that the pointer relationships between the objects are preserved. If there are no pointer relationships, isomorphic persistence effectively saves and restores objects the same way as simple persistence. When a collection is isomorphically persisted, all objects within that collection are assumed to have the same type. (A collection of objects of the same type is called a homogeneous collection.)

You can use isomorphic persistence to save and restore any Essential Tools Module class listed in Table 14 in Section 6.9.1, "The Standard C++ Library Containers." above. In addition, you can add isomorphic persistence to a class by following the technique described in Section 9.5.3.

Note that in this implementation of the Essential Tools Module, isomorphic persistence of types templatized on pointers is not supported. For example, saving and restoring RWTValDlist<int*> is not supported. C++ template mechanisms prevent us from being able to do this. However, this restriction is probably a good thing -- pointers saved at one location are likely to be troublesome indeed when injected into another. In this case, we suggest that you use RWTPtrDlist<int> instead..

Table 19: Isomorphic persistence classes  

Category Description

Rogue Wave Standard C++ Library-based collection classes

RWTValDeque<T,A>, RWTPtrMap<K,T,C,A>, ...

RWCollectable (Smalltalk-like) classes

RWCollectableDate, RWCollectableString... Note that RWCollectable classes also provide polymorphic persistence (see Section 9.6)

RWCollection classes that derive from RWCollectable

RWBinaryTree, RWBag, ...

Rogue Wave traditional Tools.h++ templatized collections

RWTPtrDlist<T,A>, RWTValDlist<T,A>, RWTPtrSlist<T.A>, RWTValSlist<T,A>, RWTPtrOrderedVector<T,A>, RWTValOrderedVector<T,A>, RWTPtrSortedVector<T,C,A>, RWTValSortedVector<T,A>, RWTPtrVector<T>, RWTValVector<T>

9.5.1 Isomorphic versus Simple Persistence

Here are two illustrations that show the difference between isomorphic and simple persistence. In Figure 4, a collection of multiple pointers to the same object is saved to and restored from a stream, using simple persistence. Notice that when the collection is stored and restored in Figure 4, each pointer points to a distinct object. Contrast this with the isomorphic persistence of the same collection, shown in Figure 5, in which all of the restored pointers point to the same object, just as they did in the original collection.

Figure 4: Saving and restoring with simple persistence.

Figure 5: Saving and restoring a Collection with isomorphic persistence

In Figure 6, we attempt to save and restore a circularly-linked list, using simple persistence. As shown in the figure, any attempt to use simple persistence to save a circularly-linked list results in an infinite loop.

The simple persistence mechanism creates a copy of each object that is pointed to and saves that object to a stream. But the simple persistence mechanism doesn't remember which objects it has already saved. When the simple persistence mechanism encounters a pointer, it has no way of knowing whether it has already saved that pointer's object. So in a circularly-linked list, the simple persistence mechanism saves the same objects over and over and over as the mechanism cycles through the list forever.

On the other hand, as shown in Figure 7, isomorphic persistence allows us to save the circularly-linked list. The isomorphic persistence mechanism uses a table to keep track of pointers it has saved. When the isomorphic persistence mechanism encounters a pointer to an unsaved object, it copies the object data, saves that object data -- not the pointer -- to the stream, then keeps track of the pointer in the save table. If the isomorphic persistence mechanism later encounters a pointer to the same object, instead of copying and saving the object data, the mechanism saves the save table's reference to the pointer.

When the isomorphic persistence mechanism restores pointers to objects from the stream, the mechanism uses a restore table to reverse the process. When the isomorphic persistence mechanism encounters a pointer to an unrestored object, it recreates the object with data from the stream, then changes the restored pointer to point to the recreated object. The mechanism keeps track of the pointer in the restore table. If the isomorphic persistence mechanism later encounters a reference to an already-restored pointer, then the mechanism looks up the reference in the restore table, and updates the restored pointer to point to the object referred to in the table.

Figure 6: Attempt to save and restore a circularly-linked list with simple persistence

Figure 7: Saving and restoring a circularly-linked list with isomorphic persistence

9.5.2 Isomorphic Persistence of an Essential Tools Module Class

The following example shows the isomorphic persistence of a templatized collection of RWCollectable integers, RWTPtrDlist<RWCollectableInt>. RWTPtrDlist is a templatized, reference-based, doubly-linked list that uses isomorphic persistence to store pointer references to values in memory.

This example uses RWCollectableInt instead of int because int uses simple persistence. By using RWCollectableInts, we can implement isomorphic persistence.

When RWTPtrDlist is saved and then restored, the pointer relationships of the restored list has the same morphology as the original list.

Figure 8: After isomorphic save and restore of RWTPtrDlist<RWCollectableInt>

9.5.3 Designing Your Class to Use Isomorphic Persistence

Table 19 lists the Essential Tools Module classes that implement isomorphic persistence. You can also add isomorphic persistence to an existing class, even if you only have the header files for that class. Before you can add isomorphic persistence to a class, it must meet the following requirements:

If your class T will be stored in a Standard C++ Library container or a Standard C++ Library-based collection, you may need to implement operator<(const T&, const T&) and operator==(const T&, const T&). See Section 6.15 for more information.

To create an isomorphically persistent class or to add isomorphic persistence to an existing class, follow these steps:

  1. Make all necessary class data available.

  2. Add RWDECLARE_PERSISTABLE to your header file.

  3. Add RWDEFINE_PERSISTABLE to one source file.

  4. Check for possible problems.

  5. Define rwSaveGuts() and rwRestoreGuts().

9.5.3.1 Make All Necessary Class Data Available

All class data that will be isomorphically persisted must be accessible to the global functions, rwSaveGuts() and rwRestoreGuts(), used to implement persistence for the class. Note that only the information necessary to recreate an object of that class must be accessible to rwSaveGuts() and rwRestoreGuts(). Other data can be kept protected or private.

There are several ways to make protected and private data members of classes accessible. First, your class could make friends with rwSaveGuts() and rwRestoreGuts():

Or your class could have accessor functions to the restricted but necessary members:

If you can not change the source code for the class to which you want to add isomorphic persistence, then you could consider deriving a new class that provides access via public methods or friendship:

If you can not change the source code for a class, you will be unable to isomorphically persist private members of that class. But remember: you only need access to the data necessary to recreate the class object, not to all the members of the class. For example, if your class has a private cache that is created at run time, you probably do not need to save and restore the cache. Thus, even though that cache is private, you do not need access to it in order to persist the class object.

9.5.3.2 Add RWDECLARE_PERSISTABLE to Your Header File

Once you have determined that all necessary class data is accessible, you must add declaration statements to your header files. These statements declare the global functions operator<< and operator>> for your class. The global functions permit storage to and retrieval from RWvistream, RWvostream and RWFile.

The Essential Tools Module provides several macros that make adding these declarations easy. The macro you choose depends upon whether your class is templatized or not, and if it is templatized, how many templatized parameters it has.

9.5.3.3 Add RWDEFINE_PERSISTABLE to One Source File

After you have declared the global storage and retrieval operators, you must define them. The Essential Tools Module provides macros that add code to your source file to define the global functions operator<< and operator>> for storage to and retrieval from RWvistream, RWvostream, and RWFile. RWDEFINE_PERSISTABLE macros will automatically create global operator<< and operator>> functions that perform isomorphic persistence duties and call the global persistence functions rwSaveGuts() and rwRestoreGuts() for your class. (You may find, for template classes, that with some compilers the source file must have the same base name as the header file where RWDECLARE_PERSISTABLE was used.) More about rwSaveGuts() and rwRestoreGuts() later.

Again, your choice of which macro to use is determined by whether your class is templatized, and if so, how many parameters it requires.

9.5.3.4 Check for Possible Problems

You have made the necessary data accessible, and declared and defined the global functions required for isomorphic persistence. Before you go any further, you need to review your work for possible problems.

If you have defined any of the following global operators and you use the RWDEFINE_PERSISTABLE macro, you will get compiler ambiguity errors.

The compiler errors occur because using RWDEFINE_PERSISTABLE along with a different definition of the operators defines the operators twice. This means that the compiler does not know which operator definition to use. In this case, you have two choices:

  1. Remove the operator<< and operator>> global functions that you previously defined for YourClass and replace them with the operators generated by the RWDEFINE_PERSISTABLE(YourClass).

  2. Modify your operator<< and operator>> global functions for YourClass using the contents of the RWDEFINE_PERSISTABLE macro in rw/epersist.h as a guide.

9.5.3.5 Define rwSaveGuts and rwRestoreGuts

Now you must add to one and only one source file the global functions rwSaveGuts() and rwRestoreGuts(), which will be used to save and restore the internal state of your class. These functions are called by the operator<< and operator>> that were declared and defined as discussed in Section 9.5.3.2 and Section 9.5.3.3 above.

Note: Section 9.5.4 provides guidelines about how to write rwSaveGuts() and rwRestoreGuts() global functions.

Function rwSaveGuts() saves the state of each class member necessary for persistence to an RWvostream or an RWFile. If the members of your class can be persisted (see Table 2 above), and if the necessary class members are accessible to rwSaveGuts(), you can use operator<< to save the class members.

Function rwRestoreGuts() restores the state of each class member necessary for persistence from an RWvistream or an RWFile. Provided that the members of your class are types that can be persisted, and provided that the members of your class are accessible to rwRestoreGuts(), you can use operator>> to restore the class members.

9.5.4 Writing rwSaveGuts and rwRestoreGuts Functions

The next two sections discuss guidelines for writing rwSaveGuts() and rwRestoreGuts() global functions. To illustrate these guidelines, the following class will be used:

The discussion in the next two sections describes how to write rwSaveGuts() and rwRestoreGuts() functions for non-templatized classes. However, the descriptions also apply to the templatized rwSaveGuts() and rwRestoreGuts() that are written for templatized classes.

9.5.4.1 Guidelines for Writing rwSaveGuts

The global overloaded functions:

are responsible for saving the internal state of a YourClass object to either a binary file (using class RWFile) or to a virtual output stream (an RWvostream). This allows the object to be restored at some later time.

The rwSaveGuts() functions that you write must save the state of each member in YourClass, including the members of the class from which you inherited.

How you write the functions depends upon the type of the member data:

Using these guidelines, you can write rwSaveGuts() functions for the example class Gut as follows:

9.5.4.2 Guidelines for Writing rwRestoreGuts

The global overloaded functions:

are responsible for restoring the internal state of a YourClass object from either a binary file (using class RWFile) or from a virtual input stream (an RWvistream).

The rwRestoreGuts() functions that you write must restore the state of each member in YourClass, including the members of the class that you inherited from. The functions must restore member data in the order that it was saved.

How you write the functions depends upon the type of the member data:

Using these guidelines, you can write the rwRestoreGuts() functions for the example class Gut as follows:


NOTE -- The order of the data is not important as long as the rwSaveGuts and rwRestoreGuts are isomorphic (See Section 9.7 for guidelines).

9.5.5 Isomorphic Persistence of a User-designed Class

Section 9.4.1.2 described some example code that implements simple persistence on a collection that includes pointers. That example illustrated how simple persistence does not maintain the original collection's morphology.

This example implements isomorphic persistence on the collection we set up in Section 9.4.1.2: Team, which contains three Developers. Figure 9 shows the morphology of the original Team collection and of the Team collection after we saved and restored it with isomorphic persistence.

Figure 9: Isomorphic Persistence

As you read the code, notice how the Developer::alias_ member, which points to other Developers, is saved and restored. You'll find that after saving Developer::name_, the rwSaveGuts() function for Developer checks to see if alias_ is pointing to a Developer in memory. If not, rwSaveGuts() stores a boolean FALSE to signify that alias_ is a nil pointer. If alias_ is pointing to a Developer, rwSaveGuts() stores a boolean TRUE. It is only afterwards that rwSaveGuts() finally stores the value of the Developer that alias_ is pointing to.

This code can distinguish between new Developers and existing
Developers because the insertion operators generated by RWDEFINE_PERSISTABLE(Developer) keep track of Developers that have been stored previously. The insertion operator, operator<<, calls the rwSaveGuts() if and only if a Developer has not yet been stored in the stream by operator<<.

When a Developer object is restored, the extraction operator, operator>>, for Developer is called. Like the insertion operators, the extraction operators are generated by RWDEFINE_PERSISTABLE(Developer). If a Developer object has already been restored, then the extraction operator will adjust the Developer::alias_ pointer so that it points to the already existing Developer. If the Developer has not yet been restored, then rwRestoreGuts() for Developer will be called.

After restoring Developer::name_, rwRestoreGuts() for Developer restores a boolean value to determine whether Developer::alias_ should point to a Developer in memory or not. If the boolean is TRUE, then alias_ should point to a Developer, so rwRestoreGuts() restores the Developer object. Then rwRestoreGuts() updates alias_ to point to the restored Developer.

The isomorphic persistence storage and retrieval process described above for Developer.alias_ can also be applied to the Developer pointers in Team.

Here is the code:

Output:



Previous fileTop of DocumentContentsIndex pageNext file

©2004 Copyright Quovadx, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.