Using the Stream Contents Macros

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

6.3 Using the Stream Contents Macros

The stream contents macros are added to a class so that its objects can be serialized. This section introduces the streaming macros you need to use in most situations. For details of these macros and additional macros, required in some cases, see Advanced Tools Module | Serialization | Serialization Macros on the Modules tab of the SourcePro C++ API Reference Guide.

The serialization support macros include macros for the header file and macros for the source file. The header file macros declare the underlying streaming implementation methods that make your C++ class serializable. The source file macros define some required streaming functions and help you define the streamContents() function.

6.3.1 Header File Macros

The simplest and most efficient way to serialize your classes is to build serialization directly into your objects (intrusive serialization) using these macros:

RW_DECLARE_VIRTUAL_STREAM_FNS(className)
RW_DECLARE_STREAMABLE_POINTER(className)
RW_DECLARE_STREAMABLE_AS_SELF(className)
RW_DECLARE_STREAMABLE_AS_BASE(className)

The RW_DECLARE_VIRTUAL_STREAM_FNS macro should be placed inside the class declaration—just inside the opening curly brace is a good place to put it. This macro declares, among other things, a streamContents() method, used to add the contents of your object to a virtual stream.

The RW_DECLARE_STREAMABLE_POINTER macro should be placed in the header file outside the class declaration. This macro declares global serialization operators.

The RW_DECLARE_STREAMABLE_AS_SELFmacro should be placed in the header of the class outside the class declaration. This macro declares the factory for your class and declares its registrar.

The RW_DECLARE_STREAMABLE_AS_BASEmacro should be placed after the above macro in the header of your class. It declares a registrar for your class' factory for when the class it's serialized through a base pointer.

You can also enable streaming with these macros, which provide special handling for certain data types:

RW_DECLARE_STREAMABLE_VAL_SEQUENCE for streaming Rogue Wave value-based template collections

RW_DECLARE_STREAMABLE_PTR_SEQUENCE for streaming Rogue Wave pointer-based template collections

RW_DECLARE_STREAMABLE_STD_SEQUENCE for streaming Standard C++ Library sequences

RW_DECLARE_STREAMABLE_COLLECTABLE_SEQUENCE for streaming Rogue Wave RWCollectable-based sequences

To enable streaming of maps (associations), use the corresponding macros:

RW_DECLARE_STREAMABLE_VAL_MAP
RW_DECLARE_STREAMABLE_PTR_MAP
RW_DECLARE_STREAMABLE_STD_MAP
RW_DECLARE_STREAMABLE_COLLECTABLE_MAP

6.3.2 Source File Macros

Preparing the source file to define a serializable class is nearly as straightforward as modifying the header file. As in the case of the class declaration, there are two primary macros you must place in the source file.

RW_DEFINE_STREAMABLE_POINTER(className)

Apply this macro to all classes involved in the serialization, including abstract base classes, non-abstract base classes, and derived classes. For abstract base classes, apply only this macro.
RW_DEFINE_STREAMABLE_AS_SELF(className)

Apply this macro to a class if its instantiations will be serialized as pointers directly to the instantiations. This macro can be applied to non-abstract base classes or derived classes. It cannot be applied to abstract base classes because the macro generates code for the instantiation of the class, which is impossible for abstract base classes.
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. The base class may be either abstract or non-abstract. The important distinction is that the derived class is being serialized through virtual indirection.

Be sure to indicate all inheritance relationships with RW_DEFINE_STREAMABLE_AS_BASE. For instance, if you have the inheritance relationship C->B->A (C inherits from B, which inherits from A), you need to add the following three lines:

RW_DEFINE_STREAMABLE_AS_BASE(B, A)
RW_DEFINE_STREAMABLE_AS_BASE(C, B)
RW_DEFINE_STREAMABLE_AS_BASE(C, A)

Just having

RW_DEFINE_STREAMABLE_AS_BASE(B, A)
RW_DEFINE_STREAMABLE_AS_BASE(C, B)

is not enough to allow serializing a C* through an A*.

The streaming support macros also include a set of helper macros to help you define the streamContents() member function used for object serialization. The ones you'll use most often are:

RW_BEGIN_STREAM_CONTENTS(className)

Begins the streamContents() function.
RW_END_STREAM_CONTENTS

Ends the streamContents() function.
RW_STREAM_ATTR_GET_SET(attrName, attrType, get, set)

Streams the member data accessed by get() and set() member functions.
RW_STREAM_ATTR_MEMBER(attrName, memberName)

Streams the member data indicated by memberName using the label attrName.
RW_STREAM_PARENT(parentClass)

If your serializable class is derived from a serializable base class, place RW_STREAM_PARENT(parentClass) just after the begin macro. This calls streamContents() on the base class, effectively chaining the function calls to stream the contents of the base class before streaming the derived class.

6.3.3 Macros for External Serialization

Some of the macros mentioned earlier can be used for either intrusive or external serialization. Others, such as RW_DECLARE_VIRTUAL_STREAM_FNS, for example, can only be used in the class files. In those cases, the Serialization package provides equivalent external macros:

RW_DECLARE_EXTERNAL_STREAM_FNS

RW_DECLARE_EXTERNAL_STREAMABLE_POINTER

RW_DEFINE_EXTERNAL_STREAMABLE_POINTER

RW_DECLARE_EXTERNAL_STREAMABLE_AS_SELF

RW_DEFINE_EXTERNAL_STREAMABLE_AS_SELF

RW_DECLARE_EXTERNAL_STREAMABLE_AS_BASE

RW_DEFINE_EXTERNAL_STREAMABLE_AS_BASE

RW_BEGIN_EXTERNAL_STREAM_CONTENTS

RW_STREAM_EXTERNAL_PARENT

6.3.4 Macro Summary

Table 3 lists the macros most commonly used for serialization. The following sections explain how to use these macros.

Table 3: Header file macros for serialization

Name	Use
Intrusive or external serialization
`RW_DECLARE_FRIEND_CTOR_METHOD (derivedClass, baseClass)`	When a derived class has a non-public default constructor, use this macro for each base class that might be streamed in as a polymorphic pointer. Intrusive or external. Put in header file inside the derived class declaration.
`RW_DECLARE_STREAMABLE_PTR_MAP (container)`	Declares global serialization operators for streaming maps (associations) of pointers. Intrusive or external. Put in header file outside the class declaration.
`RW_DECLARE_STREAMABLE_PTR_SEQUENCE (container)`	Declares global serialization operators for streaming Rogue Wave pointer-based template collections. Intrusive or external. Put in header file outside the class declaration.
`RW_DECLARE_STREAMABLE_STD_MAP (container)`	Declares global serialization operators for streaming maps (associations) of Standard C++ Library types. Intrusive or external. Put in header file outside the class declaration.
`RW_DECLARE_STREAMABLE_STD_SEQUENCE (container)`	Declares global serialization operators for streaming Standard C++ Library sequences. Intrusive or external. Put in header file outside the class declaration.
`RW_DECLARE_STREAMABLE_VAL_MAP (container)`	Declares global serialization operators for streaming maps (associations) of value-based templates. Intrusive or external. Put in header file outside the class declaration.
`RW_DECLARE_STREAMABLE_VAL_SEQUENCE (container)`	Declares global serialization operators for streaming Rogue Wave value-based template collections. Intrusive or external. Put in header file outside the class
`RW_DECLARE_STREAMABLE_COLLECTABLE_MAP (container)`	Declares global serialization operators for streaming maps (associations) of `RWCollectable`-based associative collections. Intrusive or external. Put in header file outside the class declaration.
`RW_DECLARE_STREAMABLE_COLLECTABLE_ SEQUENCE(container)`	Declares global serialization operators for streaming Rogue Wave RWCollectable based collections. Intrusive or external. Put in header file outside the class declaration.
`RW_DEFINE_STREAMABLE_TEMPLATE_POINTER (className)`	Defines global serialization operators to provide serialization support for template classes. (For other classes, use `RW_DEFINE_STREAMABLE_ POINTER` in the source file.)
`RW_DEFINE_STREAMABLE_TEMPLATE_AS_SELF (className)`	Apply this macro to a template class if its instantiations will be serialized as pointers directly to the instantiations. (For other classes, use `RW_DEFINE_STREAMABLE_AS_SELF` in the source file.)
Intrusive serialization only
`RW_DECLARE_VIRTUAL_STREAM_FNS (className)`	Declares `streamContents()`, used to add the contents of your object to a virtual stream, and other things. Put in header file inside the class declaration. (For external, use `RW_DECLARE_EXTERNAL_STREAM_FNS`).
`RW_DECLARE_STREAMABLE_POINTER (className)`	Declares global serialization operators, for streaming most class types. Intrusive. Put in header file outside the class declaration.
`RW_DECLARE_STREAMABLE_AS_SELF (className)`	Declares class's factory and its registrar. Intrusive. Place in header file outside class declaration.
`RW_DECLARE_STREAMABALE_AS_BASE (className)`	Declares class's factory registrar for serialization through base class pointers. Place in header file outside class declaration.
External serialization only
`RW_DECLARE_EXTERNAL_STREAM_FNS (className)`	Declares `streamContents()`, used to add the contents of your object to a virtual stream, and other things. (For intrusive, use `RW_DECLARE_VIRTUAL_STREAM_FNS`.)
`RW_DECLARE_EXTERNAL_STREAMABLE_ POINTER(className)`	Declares the serialization streaming perators for streaming objects through pointers to class objects.
`RW_DECLARE_EXTERNAL_STREAMABLE_AS_ SELF(className)`	Declares the factory for the class and declares the factory's registrar. Place in header file outside the class declaration.
`RW_DECLARE_EXTERNAL_STREAMABLE_AS_ BASE(className, baseClassName)`	Declares the factory registrar for streaming objects through pointers to base classes. Place after the macro above.

Table 4: Source file macros for serialization

Name	Use
Intrusive or external serialization
`RW_END_STREAM_CONTENTS`	Ends the `streamContents()` function.
`RW_INPUT_STREAM`	Used in custom code to access the object input stream.
`RW_OUTPUT_STREAM`	Used in custom code to access the object output stream.
`RW_STREAM_ATTR_GET_SET(attrName, attrType, get, set)`	Identifies an attribute of the class to be streamed in terms of a `get()` and `set()` function pair. This is useful in external streaming when the internal data member is private but has public `get()` and `set()` functions.
`RW_STREAM_ATTR_MEMBER(attrName, memberName)`	Identifies a data member as an attribute of the class. If using external streaming, the data member must be public.
`RW_WHEN_INPUT`	Used to insert custom code into stream contents that only executes during input operations.
`RW_WHEN_OUTPUT`	Used to insert custom code into stream contents that only executes during output operations.
Intrusive serialization only
`RW_BEGIN_STREAM_CONTENTS(className)`	Starts the `streamContents()` function. Put in source file for class. (For external, use `RW_BEGIN_EXTERNAL_STREAM_CONTENTS`.)
`RW_DEFINE_STREAMABLE_AS_BASE (derivedClass, baseClass)`	Allows concrete derived types to be streamed out and streamed back in as pointers to their base class. Put in source file for class. (For external, use `RW_DEFINE_EXTERNAL_STREAMABLE_AS_BASE`.)
`RW_DEFINE_STREAMABLE_AS_SELF (className)`	Apply this macro to a class if its instantiations will be serialized as pointers directly to the instantiations. (For external, use `RW_DEFINE_EXTERNAL_STREAMABLE_AS_ SELF.` For template classes, use `RW_DEFINE_STREAMABLE_TEMPLATE_AS_SELF` in the header file.) Do not use these macros with abstract base classes (See Section 6.3.2.).
`RW_DEFINE_STREAMABLE_POINTER (className)`	Defines the global serialization operators for pointers. Put in source file for class. (For external, use `RW_DEFINE_EXTERNAL_STREAMABLE_POINTER`. For template classes, use `RW_DEFINE_STREAMABLE_TEMPLATE_POINTER` in the header file.)
`RW_STREAM_PARENT(parentClass)`	For classes derived from a serializable base class. Calls `streamContents()` on the base class to stream the contents of the base class before streaming the derived class. Put in source file for class. (For external, use `RW_STREAM_EXTERNAL_PARENT`.)
External serialization only
`RW_BEGIN_EXTERNAL_STREAM_CONTENTS (className)`	Starts the `streamContents()` function. Put in separate source file. (For intrusive, use `RW_BEGIN_STREAM_CONTENTS`.)
`RW_DEFINE_EXTERNAL_STREAMABLE_AS_BASE(derivedClass, baseClass)`	Allows concrete derived types to be streamed out and streamed back in as pointers to their base class. Put in separate source file. (For intrusive, use `RW_DEFINE_STREAMABLE_AS_BASE`.)
`RW_DEFINE_EXTERNAL_STREAMABLE_POINTER (className)`	Defines the global serialization operators. Put in separate source file. (For intrusive, use `RW_DEFINE_STREAMABLE_POINTER`.)
`RW_DEFINE_EXTERNAL_STREAMABLE_AS_SELF (className)`	Apply this macro to a class if its instantiations will be serialized as pointers directly to the instantiations. Put in separate source file. (For intrusive, use `RW_DEFINE_STREAMABLE_AS_SELF`.)
`RW_STREAM_EXTERNAL_PARENT(parentClass)`	For classes derived from a serializable base class. Calls `streamContents()` on the base class to stream the contents of the base class before streaming the derived class. Put in separate source file. (For intrusive, use `RW_STREAM_PARENT`.)

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.
Contact Rogue Wave about documentation or support issues.