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.
2. Add the macro
RW_DECLARE_COLLECTABLE_CLASS to your class declaration. See
Section 6.17.2.
3. 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.
4. 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:
Int compareTo(const RWCollectable*) const;
bool isEqual(const RWCollectable*) const;
unsigned hash() const;
5. Consider whether you need to define a destructor. See
Section 6.17.5.
6. 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:
1. Save the state of your base class by calling its version of saveGuts().
2. 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:
RWvostream& operator<<(RWvostream&,
const RWCString& str);
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:
RWspace RWCollectable::recursiveStoreSize();
For objects that inherit from
RWCollectable, if the pointer is nil, use the static member function:
RWspace RWCollectable::nilStoreSize();
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.