3.4 Examining the Code

The code for this example is presented in three parts:

• declaring the basic classes

• making the basic classes serializable

• persisting the serializable objects

The code below shows the base class real_property and its two derived classes residential and rural_land.

Here is the declaration for the base class real_property:

class real_property
{
   public:
      real_property();                               //1
      virtual ~real_property();
      real_property (const RWCString& address,
                     const RWCString& size);
      virtual void printMe();

   private:
      RWCString address_;
      RWCString size_;
};

Here are the declarations for the two derived classes residential and rural_land:

class residential : public real_property
{
   public:
      residential();                                  //1
      residential (const RWCString& address, 
           const RWCString& size, long footage);
      void printMe();                                 //2

   private:
      long footage_;
};

class rural_land : public real_property
{
   public:

      rural_land();                                   //1
      rural_land (const RWCString& address,
         const RWCString& size, unsigned irrigation = 0);
      void printMe();                                 //2

   private:
      unsigned irrigation_;     //irrigation acres for property
};

The real estate application references the residential and rural_land objects as pointers to the real_property base class. As stated in Section 3.3 above, to make these classes serializable as pointers you must:

• Declare the streamContents() function and the global operators for streaming pointers by putting macros in the header file for each class.

• Define the streamContents() function and the global operators for streaming pointers by putting macros in the source file for each class.

Starting with the header files, add the following macros:

• RW_DECLARE_VIRTUAL_STREAM_FNS(classname), which declares the streamContents() member function needed to serialize a class out to a virtual stream. Place this within the class declaration.

• RW_DECLARE_STREAMABLE_POINTER(classname), which declares the global input and output operators needed for an object pointer to be written out and later restored. Because this macro declares global operators, you must place it outside the class declaration. The safest location for this macro declaration is immediately following the declaration of the class to which it applies.

Here is the revised code for the header files:

// from real_property.h

class real_property
{
   RW_DECLARE_VIRTUAL_STREAM_FNS(real_property)

   public:
      real_property ();
      real_property (const RWCString& address,
                     const RWCString& size);
      virtual void printMe() = 0;

   private:
      RWCString address_;
      RWCString size_;
};

RW_DECLARE_STREAMABLE_POINTER(real_property)
RW_DECLARE_STREAMABLE_AS_SELF(real_property)

// from residential.h

class residential : public real_property
{
   RW_DECLARE_VIRTUAL_STREAM_FNS(residential)

   public:
      residential ();
      residential (const RWCString& address, 
           const RWCString& size, long footage);
      void printMe();

   private:
      long footage_;  
};

RW_DECLARE_STREAMABLE_POINTER(residential)
RW_DECLARE_STREAMABLE_AS_SELF(residential)

// from rural_land.h

class rural_land : public real_property
{
   RW_DECLARE_VIRTUAL_STREAM_FNS(rural_land)

   public:

      rural_land ();
      rural_land (const RWCString& address, 
         const RWCString& size, unsigned irrigation = 0);
      void printMe();

   private:
      unsigned irrigation_; 
};

RW_DECLARE_STREAMABLE_POINTER(rural_land)
RW_DECLARE_STREAMABLE_AS_SELF(rural_land)

Moving on to the source files, you must now:

• Define the streamContents() function using the following macro set:

• RW_BEGIN_STREAM_CONTENTS(className)

• RW_STREAM_PARENT(parentClass)

• RW_STREAM_ATTR_MEMBER(variableLabel,variableName)

• RW_END_STREAM_CONTENTS()

The definitions generated through these macros guarantee symmetry between the serialization output and input operations.

• Define the global insertion and extraction operators that support the serialization of pointers to objects, using the following macro set:

• RW_DEFINE_STREAMABLE_POINTER(className)

Apply this macro to all classes involved in the serialization.

• RW_DEFINE_STREAMABLE_AS_SELF(className)

Apply this macro to a class if its instantiations will be serialized as pointers directly to the instantiations.

• RW_DEFINE_STREAMABLE_AS_BASE(derivedClass,baseClass)

Apply this macro to a class derived from a base class if its instantiations will be serialized as pointers to the base class.

If you want to allow for the possibility that these objects might be serialized as pointers directly to themselves, you need to apply RW_DEFINE_STREAMABLE_AS_SELF as well. In the code that follows, both RW_DEFINE_STREAMABLE_AS_BASE and RW_DEFINE_STREAMABLE_AS_SELF are applied.

Here is the source code for your three classes, modified as needed with the macros described above:

// from real_property.cpp

RW_BEGIN_STREAM_CONTENTS(real_property)                        //1
   RW_STREAM_ATTR_MEMBER(address,address_)                     //2
   RW_STREAM_ATTR_MEMBER(size,size_)
RW_END_STREAM_CONTENTS                                         //3

RW_DEFINE_STREAMABLE_AS_SELF(real_property)                    //4
RW_DEFINE_STREAMABLE_POINTER(real_property)                    

Note that the code below parallels the code for residential.

RW_BEGIN_STREAM_CONTENTS(rural_land)
   RW_STREAM_PARENT(real_property)
   RW_STREAM_ATTR_MEMBER(irrigation,irrigation_)
RW_END_STREAM_CONTENTS

RW_DEFINE_STREAMABLE_AS_SELF(rural_land)
RW_DEFINE_STREAMABLE_AS_BASE(rural_land, real_property)
RW_DEFINE_STREAMABLE_POINTER(rural_land)

Now that the classes have been prepared with serialization support, consider the code that could be used to persist the residential and rural_land objects -- as pointers to real_property -- at application shutdown, and restore these objects when the application is restarted. The main logic for the example application is in listing.cpp.

But before looking at the main logic, there is one more setup requirement. Recall from the use case description that at application shutdown the RWTPtrOrderedVector collection of real_property objects is written out to a file as a single operation. When the application is restarted, it reads in the file and restores the RWTPtrOrderedVector collection with all its real_property objects.

For this to work, you must make the RWTPtrOrderedVector collection serializable. To do this, apply the macro RW_DECLARE_STREAMABLE_PTR_SEQUENCE() on the collection. This macro declares the global input and output operators needed for streaming a collection of pointers. This macro can occur anywhere in the code so long as it is guaranteed to occur after the #include of the header file for RWTPtrOrderedVector, which is tpordvec.h. Since this include occurs in listing.cpp, this is the safest place to apply the macro.

Here is the code that includes the collection and prepares it for serialization:

// from listing.cpp

// Get the header file for RWTPtrOrderedVector
#include <rw/tpordvec.h>

// Create global operators to support streaming of an
// RWTPtrOrderedVector collection
RW_DECLARE_STREAMABLE_PTR_SEQUENCE(RWTPtrOrderedVector)

Now you are ready to look at the main logic, beginning with the code for persisting the collection of real_property objects at application shutdown.

// Here is the shutdown processing, which
// - creates an output stream to a file
// - serializes out the RWTPtrOrderedVector collection,
//   whose name is "properties"

ofstream fout("properties.xml");                      //1

RWObjectOutputStream out =                            //2
  RWXmlObjectOutputStreamImp::make(fout,
  RWXmlObjectOutputStreamImp::sequence);              //3
out << properties;                                    //4

Next, look at the code for restoring the collection at application startup.

// Here is the startup processing, closely mirrors
// the shutdown processing.

ifstream fin("properties.xml");                       //1

RWObjectInputStream in =                              //2
  RWXmlObjectInputStreamImp::make(fin,
  RWXmlObjectInputStreamImp::sequence);               //3

RWTPtrOrderedVector(real_property) properties;        //4
in >> properties;                                     //5

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, 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.