Generics Reference Manual

CClass
|--CSerialized

Serialization Abstraction

    Serialization introduces the instance dump capabilities notion. Every class derived from the generics CSerialized base class should be able to dump or load its data in/from an xml format or binary chunk.

   CSerialized derives the abstract base CClass definition and is so metaclass described. A final CSerialized derived class must be associated to a dynamic metaclass if such a definition should be able to dump or reload its whole content from a given format.

    With such definitions and process handling, a core application will be able to reload its complete state "from scratch" (i.e. from class instances automatic allocations and reloading) as it was when it finished the last time it was launched, dynamically linked metamodules included.



Chunk based serialization

    This functionnality will probably disapear in the next generics version because of native recursive algorithms restrictions. So, it won't be detailed in this section, see the cserialized.h header file for prototypes declarations and associated explanations.



Xml based serialization

    <cserialized name="classtype" tag="classtag">
    ...
    </cserialized>

    In this case, the serialization process will be based on the libxml2 and generics xml services. The CSerialized class declares 4 functions :

static bool                            IsSerializable    (const CMetaClass *inMetaClass);
    This functions checks if the specified metaclass describes a class that may be serialized i.e. if it is a dynamic one that has a pointer on the default constructor of the class. Such classes may be automatically instanciated from the generics CSerialied definition.

virtual void                          Serialize            (CXMLElementNode *&ioXMLElementNode, const int inMode);
    This virtual function is the base declaration of a CSerialized instance dump / load capabilities. This version writes or reads the class tag and class name of the current class into a dedicated <cserialized> xml element, child of the specified incoming ioXMLElementNode xml element node. The inMode parameter specifies a XML_WRITE or XML_READ value and should be interpreted accordinaly. The Serialize virtual function should be overwritten foreach derived definition that has to store or load its data into / from an xml format. Every overloaded definition has to call its generic definition it overwrittes in order each class level to store and retrieve its expected informations.

static const CMetaClass *    GetMetaClass    (CXMLElementNode *inXMLElementNode);
    This functions returns the accessible metaclass on the current inXMLElementNode xml node or on any of its direct children if the current element is not a "cserialized" one, NULL if any.

static CSerialized *              Instanciate         (CXMLElementNode *inXMLElementNode);
    This function instanciate any CSerialized derived class from the specified inXMLElementNode xml node or its direct children, NULL if any. It searches for the metaclass associated tag, checks it is a dynamic one, instanciates the described class and calls its specific Serialize virtual function to load it from the current resource. It returns the full loaded instance when done.

class CSerialized : public CClass
{
    public :

        CSerialized                        ();
        virtual ~CSerialized           () =0;

        static bool                            IsSerializable      (const CMetaClass *inMetaClass);

        virtual void                          Serialize             (CXMLElementNode *&ioXMLElementNode, const int inMode) THROWABLE;

        static const CMetaClass *    GetMetaClass    (CXMLElementNode *inXMLElementNode);

        static CSerialized *              Instanciate         (CXMLElementNode *inXMLElementNode) THROWABLE;

        // generic metaclass association
        SECTION_GENERIC_METACLASS;
};

// classtag and metaclass declaration
DECLARE_GENERIC_METACLASS ('slzd', CSerialized, CClass);

   Since the 1.2-9 Generics version, the CSerialized::Serialize function writes the xml class tag attribute as a 4 char array and no more as an unsigned long. Because of this new handling wich purpose is to give the xml dump output a more readable shape, the metaclasses definitions must define classes tags with unsigned long values that match ASCII correspondances i.e. define classes tags with 4 char automatically converted to unsigned long. See the "CClass base class metaclass association" section to avoid compilation warnings with such constants declarations.

    Convenience functions are provided to convert unsigned long tags to char arrays and char arrays to unsigned long tags if needed while overloaded serialization defintion :
CString ClassTagToString (const UInt32);
UInt32  StringToClassTag (const CString &);