The Stingray XML serialization architecture has been designed to emulate, as closely as possible, MFC's serialization mechanism (based on CArchive and CDocument). Enabling the seamless transitioning of a standard document-view type application into the Stingray XML framework was among the architecture designers’ chief priorities.

The document adapter, SECXMLDocAdapter_T, is a template class that multiply inherits from your document's base class and IXMLSerialize. The document adapter is a core component of this architecture; it serves as a bridge between the standard MFC serialization mechanism and our XML archiving architecture. SECXMLDocAdapter_T overrides certain CDocument virtuals and creates the plumbing required for the XML serialization—such as creating the XML archive, and saving and opening .xml documents. All of this is completely transparent to the application. The developer is expected to provide only the implementation for the IXMLSerialize::XMLSerialize() override in the document.

The application's document class derives from the SECXMLDocAdapter_T class and provides the base document, either CDocument or its derivative, as a template parameter. As with ATL, because SECXMLDocAdapter_T is a template class and the CDocument-based template parameter is its base, users can conveniently retain existing custom document hierarchies—without the need for complex workarounds such as multiple-inheritance, abstraction models, etc. The application's document is hooked into the XML serialization framework. Attempting to open or save an .xml file will automatically invoke the XML serialization routine, the IXMLSerialize::XMLSerialize() override, in the document class.

If necessary, separate menu entries can be provided for the XML file open/save commands. These can be incorporated into the framework using existing command handlers in the document adapter base class. The message map entries needed for hooking the menu commands into the XML framework are shown below:

SECXMLArchive is the CArchive equivalent of MFC's binary serialization architecture. However, unlike CArchive, SECXMLArchive is just an interface; the actual implementation is provided in the SECXMLDOMArchive-derived class. SECXMLDOMArchive uses the XML DOM interfaces specified in the Microsoft XML SDK to interact with XML documents.

An SECXMLDOMArchive instance gets created and gets associated with an .xml file by the SECXMLDocAdapter_T class. However, you would only deal with the base SECXMLArchive interface in your application. You can also create and initialize SECXMLDOMArchive yourself, if you choose not to use the document adapter class in your application. Important interfaces in SECXMLArchive are discussed in the following sections. These include:

These public functions let you know whether the archive is in Storing or Loading mode.

This is one of the Write() overrides that allow you to insert primitive data types in your application as a child element node at the current node with the specified tagName in the XML document hierarchy. There are similar overrides for other primitive data types and CString.

It is almost always the case that you will have other non-primitive types (either custom classes or MFC classes) in your application. If you do, then you can associate such classes with an implementation of the IXMLSerialize interface—this implementation we call a formatter—and pass it on to the archive class using the following override:

Take a look at the IXMLSerialize interface and formatters discussion in “XML Formatters” for more information.

The following Read() overrides closely reflect the Write() operations shown in “Insertion Operations” above.

The return value indicates whether the specified tagName was found. If an element node with tagName was not found as a child of the current node, then the supplied data type is left uninitialized and a FALSE is returned. However, if you call the function with bAssertOnFailure set to TRUE (usually for critical elements) then Read() will ASSERT if the specified tagName is not found.

If you can make a single call into the SECXMLArchive— regardless of the serialization context (either loading or storing)— it makes your serialization code look simpler. That is just what the Serialize() overloads provide.

The Serialize() function will in turn call Read() or Write()— based on the archive's current context.

While serializing, at any layer you could create parent element nodes and insert your data structures as child elements to that parent node, using the following functions:

For example, consider the following code:

The above code will result in an XML segment as shown below:

You should have at least one implementation of the IXMLSerialize interface in your application, if you want to participate in the XML serialization framework. This one implementation should be associated with the class (usually CDocument) that contains the data in your application. This association is automatically set up for you when you derive your document class from the SECXMLDocAdapter_T base, which in turn multiply inherits IXMLSerialize. You should then provide an implementation of the XMLSerialize virtual in your document class.

You could serialize all your application data from this single XMLSerialize override of your single IXMLSerialize implementation or you could provide other IXMLSerialize implementations for other non-primitive data types in your application and use the corresponding Read()/Write()/Serialize() override to serialize those objects from within any other XMLSerialize override.

Every IXMLSerialize implementation should also be associated with a tagName, which will be the name for the corresponding element node in the resultant XML document.

For example, a Write() call with the following syntax will produce an XML document segment as shown below.

MyObjectFTR() is an implementation of IXMLSerialize with a tagName of say "MyObject." This will result in the following XML segment under the current node:

We will be referring to an implementation of IXMLSerialize associated to an object as a formatter for that object. “XML Formatters” will discuss formatters.