Creating an RWCollectable Object

Essential Tools Module User's Guide
Rogue Wave web site: Home Page | Main Documentation Page

6.17 Creating an RWCollectable Object

Here is an outline of how to make your object inherit from RWCollectable. Additional information about how to do each step appears in the indicated section.

Define a default constructor. See Section 6.17.1.

Add the macro RW_DECLARE_COLLECTABLE_CLASS to your class declaration. See Section 6.17.2.

Provide a class identifier for your class by adding one of two definition macros, RW_DEFINE_COLLECTABLE_CLASS_BY_ID or RW_DEFINE_COLLECTABLE_CLASS_BY_NAME, to one and only one source file (.cpp), to be compiled. See Section 6.17.3.
Add definitions for inherited virtual functions as necessary. You may be able to use inherited definitions. Section 6.17.4 discusses the following virtual functions:
Consider whether you need to define a destructor. See Section 6.17.5.

Add persistence to the class. You may be able to use inherited definitions, or you may have to add definitions for the following functions. See Section 6.17.6.

RWspace     binaryStoreSize() const; 
void        restoreGuts(RWFile&); 
void        restoreGuts(RWvistream&); 
void        saveGuts(RWFile&) const; 
void        saveGuts(RWvostream&) const;

A note on RWFactory follows these steps. See Section 6.17.7.

6.17.1 Define a Default Constructor

All RWCollectable classes must have a default constructor. The default constructor takes no arguments. The persistence mechanism uses this constructor to create an empty object, then restore that object with appropriate contents.

Default constructors are necessary in order to create vectors of objects in C++, so providing a default constructor is a good habit to get into anyway. Here's a possible definition of a default constructor for our Bus class.

Bus::Bus() :
  busNumber_  (0),
  driver_     ("Unknown"),
  passengers_ (rwnil)
{
}

6.17.2 Add RW_DECLARE_COLLECTABLE_CLASS() to your Class Declaration

The example in Section 6.16.3 includes the macro invocation RW_DECLARE_COLLECTABLE_CLASS(USER_MODULE, Bus) in the declaration for Bus. You must put this macro in your class declaration, using the class name as the argument. Using the macro guarantees that all necessary member functions are declared correctly.

6.17.3 Provide a Class Identifier for Your Class

Polymorphic persistence lets you save a class in one executable, and restore it in a different executable or in a different run of the original executable. The restoring executable can use the class, without prior knowledge of its type. In order to provide polymorphic persistence, a class must have a unique, unchanging identifier. Because classes derived from RWCollectable are polymorphically persistent, they must have such an identifier.

Identifiers can be either numbers or strings. A numeric identifier is an unsigned short with a typedef of RWClassID. A string identifier has a typedef of RWStringID. If you choose to specify a numeric identifier, your class will have an automatically generated string identifier, which will be the same sequence of characters as the name of the class. Similarly, if you choose to specify a string identifier, your class will have an automatically generated numeric ID when used in an executable.

The Essential Tools Module includes two definition macros to provide an identifier for the class you design. If you want to specify a numeric ID, use:

RW_DEFINE_COLLECTABLE_CLASS_BY_ID (USER_MODULE, className, numericID)

If you want to specify a string ID, use:

RW_DEFINE_COLLECTABLE_CLASS_BY_NAME (USER_MODULE, className, stringID)

Note that you do not include the definition macros in the header file for the class. Rather, the macros are part of a .cpp file that uses the class. You must include exactly one define macro for each RWCollectable class that you're creating, in one and only source file (.cpp). Use the class name as the first argument, and a numeric class ID or string class ID as the second argument. For the bus example, you can include the following definition macros:

RW_DEFINE_COLLECTABLE_CLASS_BY_ID(USER_MODULE, Bus, 200)

or:

RW_DEFINE_COLLECTABLE_CLASS_BY_NAME(USER_MODULE, Client, "a client")

The first use provides a numeric ID 200 for class Bus, and the second provides a string ID, "a client", for class Client.

In the remainder of this manual, we use RWDEFINITION_MACRO to indicate that you can choose either of these macros. In example code, we will pick one or the other macro.

Either macro will automatically supply the definitions for the virtual functions isA() and newSpecies(). In Section 6.17.3.1 through Section 6.17.7, we describe these virtual functions, discuss the stringID() method and provide a brief introduction to the RWFactory class, which helps implement polymorphic persistence.

The RWDEFINITION_MACROs do more than merely implement the two mentioned methods. Before you choose not to use one of the provided macros, review them in detail to be sure you understand all that they do.

6.17.3.1 Virtual Function isA()

The virtual function isA() returns a class identifier: a unique number that identifies an object's class. It can be used to determine the class to which an object belongs. Here's the function declaration provided by macro RW_DECLARE_COLLECTABLE_CLASS:

virtual RWClassID isA() const;

RWClassID is actually a typedef to an unsigned short. Numbers from 0x8000 (hex) and up are reserved for use by Rogue Wave. You may choose a numeric class ID from 0x0001 to 0x7fff. There is a set of class symbols defined in <rw/tooldefs.h> for the Essential Tools Module. Generally, these follow the pattern of a double underscore followed by the class name with all letters in upper case. For example:

RWCollectableString yogi;
yogi.isA() == __RWCOLLECTABLESTRING;           // Evaluates true

The macro RW_DECLARE_COLLECTABLE_CLASS(USER_MODULE, className) will automatically provide a declaration for isA(). Either RWDEFINITION_MACRO will supply the definition.

6.17.3.2 Virtual Function newSpecies()

The job of this function is to return a pointer to a brand new object of the same type as self. Here is the function declaration provided by macro RW_DECLARE_COLLECTABLE_CLASS:

virtual RWCollectable*  newSpecies() const;

The definition is automatically provided by either version of RWDEFINITION_MACRO.

6.17.3.3 Function stringID()

The stringID() function acts like a virtual function, but it is not. It returns an instance of RWStringID, a unique string that identifies an object's class. RWStringID is derived from class RWCString. By default, the string identifier for a class is the same as the name of the class. RWStringID can be used instead of, or as a supplement to, RWClassIDs.

6.17.4 Add Definitions for Virtual Functions

Class RWCollectable declares the following virtual functions:

virtual                 ~RWCollectable();
virtual RWspace         binaryStoreSize() const;
virtual int             compareTo(const RWCollectable*) const;
virtual unsigned        hash() const;
virtual RWClassID       isA() const;
virtual bool            isEqual(const RWCollectable*) const;
virtual RWCollectable*  newSpecies() const;
virtual void            restoreGuts(RWvistream&);
virtual void            restoreGuts(RWFile&);
virtual void            saveGuts(RWvostream&) const;
virtual void            saveGuts(RWFile&) const;

Any class that derives from class RWCollectable should be able to understand any of these methods. Although default definitions are given for all of them in the base class RWCollectable, it is best for you as the class designer to provide definitions tailored to the class at hand.

We've split our discussion of these virtual functions. We discuss the destructor in Section 6.17.5, and the binaryStoreSize(), saveGuts(), and restoreGuts() functions in Section 6.17.6, where we describe how to add persistence to a class. Virtual functions isA() and newSpecies() are declared and defined by macros, so they were discussed above, in Section 6.17.3.1 and Section 6.17.3.2. This section presents discussion on the remaining functions: compareTo(), isEqual(), and hash(). A very brief example, showing how all three functions deal with the same data, appears in Section 6.17.4.4.

6.17.4.1 Virtual Function compareTo()

The virtual function compareTo() is used to order objects relative to each other. This function is required in collection classes that depend on such ordering, such as RWBinaryTree or RWBTree. Here is its declaration:

virtual int  compareTo(const RWCollectable*) const;

The function int compareTo(const RWCollectable*) const should return a number greater than zero if self is greater than the argument, a number less than zero if self is less than the argument, and zero if self is equal to the argument.

The definition and meaning of whether one object is greater than, less than, or equal to another object is left to the class designer. The default definition, found in class RWCollectable, is to compare the two addresses of the objects. This default definition should be considered a placeholder; in practice, it is not very useful and could vary from run to run of a program.

Here is a possible definition of compareTo():

int Bus::compareTo(const RWCollectable* c) const
{  const Bus* b = (const Bus*)c;
   if (busNumber_ == b->busNumber_) return 0;
   return busNumber_ > b->busNumber_ ? 1 : -1;
}

Here we are using the bus number as a measure of the ordering of buses. If we need to insert a group of buses into an RWBinaryTree, they would be sorted by their bus number. Note that there are many other possible choices—we could have used the driver name, in which case they would have been sorted by the driver name. Which choice you use will depend on your particular problem.

There is a hazard here. We have been glib in assuming that the actual type of the RWCollectable which c points to is always a Bus. If a careless user inserted, say, an RWCollectableString into the collection, then the results of the cast (const Bus*)c would be invalid, and dereferencing it could bring disaster. Section 8.7.3 describes this problem. The necessity for all overloaded virtual functions to share the same signatures requires that they return the lowest common denominator, in this case, class RWCollectable. The result is that much compile-time type checking breaks down.

You must be careful that the members of a collection are either homogeneous (i.e., all of the same type), or that there is some way of telling them apart. The member functions isA() or stringID() can be used for this.

6.17.4.2 Virtual Function isEqual()

The virtual function isEqual() is a tester function whose purpose is to signal when a certain member of the collection has been identified.

bool  isEqual(const RWCollectable* c) const;

The function bool isEqual(const RWCollectable*) should return true if the object and its argument are considered equal, and false otherwise. The definition of equality is left to the class designer. The default definition, as defined in class RWCollectable, is to test the two addresses for equality, that is, to test for identity.

Note that isEqual() does not have to be defined as being identical. Rather isEqual can mean that two objects are equivalent in some sense. In fact, the two objects need not even be of the same type. The only requirement is that the object passed as an argument must inherit type RWCollectable. You are responsible for making sure that any typecasts you do are appropriate.

Also note that there is no formal requirement that two objects that compare equal (i.e., compareTo() returns zero) must also return true from isEqual(), although it is hard to imagine a situation where this wouldn't be the case. It is also possible to design a class for which the isEqual test returns true for objects that have different hash values. This would make it impossible to search for such objects in a hash-based collection.

For the Bus class, an appropriate definition of isEqual might be:

bool Bus::isEqual(const RWCollectable* c) const {
   const Bus* b = (const Bus*)c;
   return busNumber_ == b->busNumber_;
}

Here we are considering buses to be equal if their bus numbers are the same. Again, other choices are possible.

6.17.4.3 Virtual Function hash()

The function hash() should return an appropriate hashing value for the object. Here is the function's declaration:

unsigned  hash() const;

A possible definition of hash() for our class Bus might be:

unsigned Bus::hash() const{
  return (unsigned)busNumber_;
}

The example above simply returns the bus number as a hash value. Alternatively, we could choose the driver's name as a hash value:

unsigned Bus::hash() const{
  return driver_.hash();
}

In the above example, driver_ is an RWCString that already has a hash function defined.

We expect that two objects that test true for isEqual will hash to the same value.

6.17.4.4 An Example of compareTo(), isEqual(), and hash()

We have described three inherited virtual functions: compareTo(), isEqual(), and hash(). Here is an example that defines a set of objects, and applies the functions. The results of the functions appear as comments in the code.

RWCollectableString a("a");
RWCollectableString b("b");
RWCollectableString a2("a");
a.compareTo(&b);      // Returns -1
a.compareTo(&a2);     // Returns 0 ("compares equal")
b.compareTo(&a);      // Returns 1
a.isEqual(&a2);       // Returns true
a.isEqual(&b);        // Returns false
a.hash()              // Returns 96 (operating system dependent)

Note that the compareTo() function for RWCollectableStrings has been defined to compare strings lexicographically in a case sensitive manner. See class RWCString in the SourcePro C++ API Reference Guide for details.

6.17.5 Object Destruction

All objects inheriting from class RWCollectable inherit a virtual destructor. Hence, the actual type of the object need not be known until run time in order to delete the object. This allows all items in a collection to be deleted without knowing their actual type.

As with any C++ class, objects inheriting from RWCollectable may need a destructor to release the resources they hold. In the case of Bus, the names of passengers and customers are RWCollectableStrings that were allocated off the heap. Hence, they must be reclaimed. Because these strings never appear outside the scope of the class, we do not have to worry about the user having access to them. Hence, we can confidently delete them in the destructor, knowing that no dangling pointers will be left.

Furthermore, because the set pointed to by customers_ is a superset of the set pointed to by passengers_, it is essential that we delete only the contents of customers_.

Here is a possible definition:

Bus::~Bus() {
   customers_.clearAndDestroy();
   delete passengers_;
}

Note that the language guarantees that it is okay to call delete on the pointer passengers_ even if it is nil. See Section 18.4.1.1.13p1 of the C++ Standard.

6.17.6 How to Add Polymorphic Persistence

The saveGuts() and restoreGuts() virtual functions are responsible for saving and restoring the internal state of RWCollectable objects. To add persistence to your RWCollectable class, you must override the saveGuts() and restoreGuts() virtual member functions so that they write out all of your object's member data. Section 6.17.6.1 and Section 6.17.6.2 describe approaches you can use to correctly define these functions. Section 6.17.6.3 describes how these functions handle multiply-referenced objects.

Polymorphically saving an object to a file may require some knowledge of the number of bytes that need to be allocated for storage of an object. The binaryStoreSize() function calculates this value. Section 6.17.6.4 describes how to use binaryStoreSize().

RWCollection has its own versions of the saveGuts() and restoreGuts() functions that are used to polymorphically save collections that inherit from that class. Section 6.17.6.5 briefly describes how these functions work.

6.17.6.1 Virtual Functions saveGuts(RWFile&) and saveGuts(RWvostream&)

The saveGuts(RWFile&) and saveGuts(RWvostream&) virtual functions are responsible for polymorphically saving the internal state of an RWCollectable object on either a binary file, using class RWFile, or on a virtual output stream, using class RWvostream. For a description of the persistence mechanism, see Chapter 8. This allows the object to be restored at some later time, or in a different location. Here are some rules for defining a saveGuts() function:

Save the state of your base class by calling its version of saveGuts().

For each type of member data, save its state. How to do this depends upon the type of the member data:

Primitives. For primitives, save the data directly. When saving to RWFiles, use RWFile::Write(); when saving to virtual streams, use the insertion operator RWvostream::operator<<().
Rogue Wave classes. Most Rogue Wave classes offer an overloaded version of the insertion operator. For example, RWCString offers:
Hence, many Rogue Wave classes can simply be shifted onto the stream.

Objects inheriting from RWCollectable. For most of these objects, use the global function:

   
   RWvostream& operator<<(RWvostream&, 
                          const RWCollectable& obj);

This function will call saveGuts() recursively for the object.

With these rules in mind, let's look at a possible definition of the saveGuts() functions for the Bus example:

void Bus::saveGuts(RWFile& f) const {
   RWCollectable::saveGuts(f);    // Save base class
   f.Write(busNumber_);           // Write primitive directly
   f << driver_ << customers_;    // Use Rogue Wave- 
                                  // provided versions
   f << passengers_;              // Will detect nil pointer
                                  // automatically
}
void Bus::saveGuts(RWvostream& strm) const {
   RWCollectable::saveGuts(strm); // Save base class
   strm << busNumber_;            // Write primitives directly
   strm << driver_ << customers_; // Use Rogue Wave 
                                  // provided versions
   strm << passengers_;           // Will detect nil pointer
                                  // automatically
}

Member data busNumber_ is an int, a C++ primitive. It is stored directly using either RWFile::Write(int), or RWvostream::operator<<(int).

Member data driver_ is an RWCString. It does not inherit from RWCollectable. It is stored using:

RWvostream& operator<<(RWvostream&, const RWCString&);

Member data customers_ is an RWSet. It does inherit from RWCollectable. It is stored using:

RWvostream& operator<<(RWvostream&, const RWCollectable&);

Finally, member data passengers_ is a little tricky. This data is a pointer to an RWSet, which inherits from RWCollectable. However, there is the possibility that the pointer is nil. If it is nil, then passing it to:

RWvostream& operator<<(RWvostream&, const RWCollectable&);

would be disastrous, as we would have to dereference passengers_:

strm << *passengers_;

Instead, since our class has declared passengers_ as an RWSet*, we pass it to:

RWvostream& operator<<(RWvostream&, const RWCollectable*);

which automatically detects the nil pointer and stores a record of it.

6.17.6.2 Virtual Functions restoreGuts(RWFile&) and restoreGuts(RWvistream&)

In a manner similar to saveGuts(), these virtual functions are used to restore the internal state of an RWCollectable from a file or stream. Here is a definition of these functions for the Bus class:

void Bus::restoreGuts(RWFile& f) {
   RWCollectable::restoreGuts(f);   // Restore base class
   f.Read(busNumber_);              // Restore primitive
   f >> driver_ >> customers_;      // Uses Rogue Wave provided
                                    // versions
   delete passengers_;              // Delete old RWSet
   f >> passengers_;                // Replace with a new one
}
void Bus::restoreGuts(RWvistream& strm) {
   RWCollectable::restoreGuts(strm);   // Restore base class
   strm >> busNumber_ >> driver_ >> customers_;
   delete passengers_;                 // Delete old RWSet
   strm >> passengers_;                // Replace with a new one
}

Note that the pointer passengers_ is restored using:

RWvistream& operator>>(RWvistream&, RWCollectable*&);

If the original passengers_ is non-nil, then this function restores a new RWSet off the heap and returns a pointer to it. Otherwise, it returns a nil pointer. Either way, the old contents of passengers_ are replaced. Hence, we must call delete passengers_ first.

6.17.6.3 Multiply-referenced Objects

A passenger name can exist in the set pointed to by customers_ and in the set pointed to by passengers_; that is, both collections might contain the same string. When the Bus is restored, we want to make sure that the pointer relationship is maintained, and that our restoration does not create another copy of the string.

We do not have to do anything special to insure that the pointer relationship stays as it should be. Consider the call:

Bus aBus;
RWFile aFile("busdata.dat");
aBus.addPassenger("John");
aFile << aBus;

Because passenger_ is a subset of customer_, the function addPassenger puts the name on both the customer list and the passenger list. When we save aBus to aFile, both lists are saved in a single call: first the customer list, then the passenger list. The polymorphic persistence machinery saves the first reference to John, but for the second reference it merely stores a reference to the first copy. During the restore, both references will resolve to the same object, replicating the original morphology of the collection.

6.17.6.4 Virtual Function binaryStoreSize()

The binaryStoreSize() virtual function calculates the number of bytes necessary to store an object using RWFile. The function is:

virtual Rwspace  binaryStoreSize() const;

This function is useful for classes RWFileManager and RWBTreeOnDisk, which require allocation of space for an object before it can be stored. The non-virtual function recursiveStoreSize() returns the number of bytes actually stored. Recursive store size uses binaryStoreSize() to do its work.

Writing a version of binaryStoreSize() is usually straightforward. You just follow the pattern set by saveGuts(RWFile&), except that instead of saving member data, you add up their sizes. The only real difference is a syntactic one: instead of insertion operators, you use sizeof() and the member functions indicated below:

For primitives, use sizeof();

For objects that inherit from RWCollectable, if the pointer is non-nil, use function:

For objects that inherit from RWCollectable, if the pointer is nil, use the static member function:

For other objects, use member function binaryStoreSize().

Here is a sample definition of a binaryStoreSize() function for class Bus:

RWspace Bus::binaryStoreSize() const{
   RWspace count = RWCollectable::binaryStoreSize() 
     +customers_.recursiveStoreSize() 
     +sizeof(busNumber_) 
     +driver_.binaryStoreSize();
   if (passengers_)
     count += passengers_->recursiveStoreSize();
   else
     count += RWCollectable::nilStoreSize();
   return count;
}

6.17.6.5 Polymorphically Persisting Custom Collections

The versions of saveGuts() and restoreGuts() that the Essential Tools Module built into class RWCollection are sufficient for most collection classes. The function RWCollection::saveGuts() works by repeatedly calling:

RWvostream& operator<<(RWvostream&, const RWCollectable&);

for each item in the collection. Similarly, RWCollection::restoreGuts() works by repeatedly calling:

RWvistream& operator>>(RWvistream&, RWCollectable*&);

This operator allocates a new object of the proper type off the heap, then calls insert(). Because all of the Rogue Wave Smalltalk-like collection classes inherit from RWCollection, they all use this mechanism.

If you decide to write your own collection classes that inherit from class RWCollection, you will rarely have to define your own saveGuts() or restoreGuts().

There are exceptions. For example, class RWBinaryTree has its own version of saveGuts(). This is necessary because the default version of saveGuts() stores items in order. For a binary tree, this would result in a severely unbalanced tree when the tree was read back in—essentially, the degenerate case of a linked list. Hence, RWBinaryTree's version of saveGuts() stores the tree level-by-level.

When you design your class, you must determine whether it has similar special requirements which may need a custom version of saveGuts() and restoreGuts().

6.17.7 A Note on the RWFactory

The RWDEFINITION_MACROs can appear as the following:

RW_DEFINE_COLLECTABLE_CLASS_BY_ID(USER_MODULE, className, numericID)

or, using a string ID:

RW_DEFINE_COLLECTABLE_CLASS_BY_NAME(USER_MODULE, className, stringID)

In the .cpp file for the bus example, the macros appear like this:

RW_DEFINE_COLLECTABLE_CLASS_BY_ID(USER_MODULE, Bus, 200)

and:

RW_DEFINE_COLLECTABLE_CLASS_BY_NAME(USER_MODULE, Client, "a client")

Because you use these macros, a program can allow a new instance of your class to be created given only its RWClassID:

Bus* newBus = (Bus*)theFactory->create(200);

or its RWStringID:

Client* aClient = (Client*)theFactory->create("a client");

The pointer theFactory is a global pointer that points to a one-of-a-kind global instance of class RWFactory, used to hold information about all RWCollectable classes that have instances in the executable. The create() method of RWFactory is used internally by the polymorphic persistence machinery to create a new instance of a persisted object whose type is not known at run time. You will not normally use this capability in your own source code, because the use of RWFactory is generally transparent to the user. See the SourcePro C++ API Reference Guide for more details on RWFactory.

The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.