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 the "Serialization Macros" listing in the Advanced Tools Module 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.
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_SELF macro 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_BASE macro 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
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.
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
Table 4 lists the macros most commonly used for serialization. The following sections explain how to use these macros.
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 | 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_ |
RW_DEFINE_STREAMABLE_POINTER | Defines the global serialization operators for pointers. Put in source file for class. |
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.) |
© 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.