Serialization of the objects

First of all the user has to create the data manager (serializer) to handle instances of the serializable classes. Data manager can be created as the instance of the wxXmlSerializer class.

There are two possibly ways how to add the serializable objects to the serializer:

Individual serializable object can be set as s root node of the serializer
Several serializable objects can be appended to a root node of the serializer (list of the objects) or to any previously serialized object (tree structure of the objects).

The content of the serializer can be saved to the output XML file by using the function wxXmlSerializer::SerializeToXml(const wxString &file, bool withroot = false) where parameter file means the output XML file and parameter withroot indicates whether the root node's properties will also be serialized.

Serialization of the individual object

Individual objects can be added to the serializer as its root node. We can do this by using the function wxXmlSerializer::SetRootItem(xsSerializable *root) where the parameter is the pointer to the object which we want to serialize.

Adding object to the serializer as its root node demonstrates the following example:

int main( int argc, char ** argv )
{	
    // create instance of XML serializer
    wxXmlSerializer Serializer;
    // initialize the serializer
    Serializer.SetSerializerOwner(wxT("Example"));
    Serializer.SetSerializerRootName(wxT("object"));
    Serializer.SetSerializerVersion(wxT("1.0.0"));
    // create the serializable object with default values
    SerializableObject *object = new SerializableObject();
    if (object)
    {
        // insert the objects the serializer as its root node
        Serializer.SetRootItem(object);	
        // store the serializer's content to an output XML file
        Serializer.SerializeToXml( wxT("data.xml"), xsWITH_ROOT );	
    }	
}

Note that the content of the serializer must be stored to the XML file with its root node in this case.

A content of the output XML file:

<?xml version="1.0" encoding="utf-8"?>
<object owner="Example" version="1.0.0">
    <object_properties>
        <object type="SerializableObject">
            <property name="id" type="long">-1</property>
            <property name="wxStringProperty" type="string">Object No. 1 encapsulates wxString, wxPoint and Integer data members</property>
            <property name="wxPointProperty" type="point">1,2</property>
            <property name="IntegerProperty" type="int">1</property>
        </object>
    </object_properties>
</object>

Serialization of a list of the objects

If we want to serialize a list of objects we should add each object to the serializer's root node. For this task we can use these two methods:

An overloaded operator '<<'
The function wxXmlSerializer::AddItem(xsSerializable *parent, xsSerializable *item)
with parameters:
parent - Pointer to parent serializable object (if NULL then the object is added directly to the root item)
item - Added serializable object

Both posible methods descripted above are shown in the following example:

int main( int argc, char ** argv )
{
    // create the serializer
    wxXmlSerializer serializer;
    // create a list of serializable objects
    for(int i=0; i<2; i++)
    {
        serializer << new SerializableObject();
        serializer.AddItem(serializer.GetRootItem(), new SerializableObject());
    }
    // store the content of the serializer to the output XML file
    serializer.SerializeToXml(wxT("data.xml"));
}

For store the content of the serializer is used the same function like in the previous example but in this case the argument withroot is set to its default value (false) which indicates that the serializer's root node will not be serialized.

A content of the output XML file:

<?xml version="1.0" encoding="utf-8"?>
<root owner="" version="">
    <object type="SerializableObject">
        <property name="id" type="long">1</property>
        <property name="wxStringProperty" type="string">Object No. 1 encapsulates wxString, wxPoint and Integer data type members</property>
        <property name="wxPointProperty" type="point">1,2</property>
        <property name="IntegerProperty" type="int">1</property>
    </object>
    <object type="SerializableObject">
        <property name="id" type="long">2</property>
        <property name="wxStringProperty" type="string">Object No. 2 encapsulates wxString, wxPoint and Integer data type members</property>
        <property name="wxPointProperty" type="point">2,4</property>
        <property name="IntegerProperty" type="int">4</property>
    </object>
    <object type="SerializableObject">
        <property name="id" type="long">3</property>
        <property name="wxStringProperty" type="string">Object No. 3 encapsulates wxString, wxPoint and Integer data type members</property>
        <property name="wxPointProperty" type="point">3,6</property>
        <property name="IntegerProperty" type="int">9</property>
    </object>
    <object type="SerializableObject">
        <property name="id" type="long">4</property>
        <property name="wxStringProperty" type="string">Object No. 4 encapsulates wxString, wxPoint and Integer data type members</property>
        <property name="wxPointProperty" type="point">4,8</property>
        <property name="IntegerProperty" type="int">16</property>
    </object>
</root>

As you can se from the output XML file there is no difference between using the operator '<<' and the function AddItem().

Serialization of a tree structure

Objects can be appended to the root node of the serializer or to any previously serialized object. So from it is obvious that any n-ary tree structure can be constructed in this way.

Following sample sourcecode shows how a tree structure consisting of serializable class instances can be serialized by the library:

int main( int argc, char ** argv )
{
    // create the wxXmlSerializer class instance
    wxXmlSerializer serializer;    
    // create the set of serializable objects
    SerializableObject *object1 = new SerializableObject();
    SerializableObject *object2 = new SerializableObject();
    SerializableObject *object3 = new SerializableObject();
    SerializableObject *object4 = new SerializableObject();
    // insert objects to the serializer
    serializer << object1;
    *object1 << object2;
    serializer << object3;
    *object3 << object4;
    // store content of the serializer to the output XML file
    serializer.SerializeToXml(wxT("data.xml"));
}

The object No. 1 and No. 3 are appended to the serializer's root node and the another two are appended to them (No. 2 to No. 1 and No. 4 to No. 3).

A content of the output XML file:

<?xml version="1.0" encoding="utf-8"?>
<root owner="" version="">
    <object type="SerializableObject">
        <property name="id" type="long">1</property>
        <property name="wxStringProperty" type="string">Object No. 1 encapsulates wxString, wxPoint and Integer data type members</property>
        <property name="wxPointProperty" type="point">1,2</property>
        <property name="IntegerProperty" type="int">1</property>
        <object type="SerializableObject">
            <property name="id" type="long">2</property>
            <property name="wxStringProperty" type="string">Object No. 2 encapsulates wxString, wxPoint and Integer data type members</property>
            <property name="wxPointProperty" type="point">2,4</property>
            <property name="IntegerProperty" type="int">4</property>
        </object>
    </object>
    <object type="SerializableObject">
        <property name="id" type="long">3</property>
        <property name="wxStringProperty" type="string">Object No. 3 encapsulates wxString, wxPoint and Integer data type members</property>
        <property name="wxPointProperty" type="point">3,6</property>
        <property name="IntegerProperty" type="int">9</property>
        <object type="SerializableObject">
            <property name="id" type="long">4</property>
            <property name="wxStringProperty" type="string">Object No. 4 encapsulates wxString, wxPoint and Integer data type members</property>
            <property name="wxPointProperty" type="point">4,8</property>
            <property name="IntegerProperty" type="int">16</property>
        </object>
    </object>
</root>