Introduction

This article discusses the new C++ Elmax XML Library feature to use Linq-To-XML node creation to write XML files. Currently, there is no plans to implement this feature for C# Elmax. C# users can use .NET Linq-To-XML to achieve the same XML writing. For those readers who might want to learn more about Elmax XML library, they may read this tutorial article and the documentation but their reading are not required to understand this article. The intended audience for this article, are XML library authors who may be interested in implementing this Linq-To-XML node creation feature for their XML libraries. Though Linq-To-XML node creation has already been mentioned several times, C++ programmers who work primarily in native C++, may be not familiar with Linq-To-XML node creation syntax and what it does and how it does it. Linq-To-XML node creation, simply said, is the natural way to create nodes with code structurally identical to resultant XML. To prove my point, I will show a .NET C# Linq-To-XML node creation code snippet to add a movie information to movies element.

For reader's information, the Visual Studio IDE will automatically indent your C# Linq-To-XML node creation code for you when you hit the enter key. The Movies1.xml output looks similar to what is displayed right below.

As the reader may notice, the C++ syntax does not allocate the elements on the heap using the new keyword, unlike the C# version; in other words, the elements are allocated on the stack. C# Linq-To-XML allocates the elements on the heap which needs to be garbage-collected by the garbage-collector which hurts performance and requires more memory. For elements allocated on the stack, we do not have this massive memory consumption problem because they are popped off the stack immediately when the elements goes out of scope.

Underneath the surface, the memory is still allocated on the heap to construct the internal tree structure. Then the internal tree structure is converted to MS XML DOM elements recursively in the Save method. Just before the Save method returns, the internal tree structure is destroyed. If user wants to retain the tree structure for either another Save call or append the tree structure to a larger tree structure, he/she might not want to destroy the tree structure during Save; he/she can specify false for discard argument (default value is true) in the Save method.

By now, the reader may be curious to know how the original Elmax node creation stack up against the new Linq-To-XML node creation syntax. The example below shows how to save the same Movies2.xml, using original Elmax code.

As the reader can see that it can be hard to discern the structure of the XML just by casually glancing at the original Elmax code of node creation.

How the Library is Written

Surprisingly, the Linq-To-XML node creation library code is very simple and can be written under a couple of hours. To create nodes, using the new syntax, we are required to use NewElement, NewAttribute, NewCData and NewComment class. These new classes are derived from NewNode class and they do most of their useful work in their constructors.

As you can see, NewElement constructors and its Add methods do nothing except appending the nodes to the vector. Below is the code listing for the declaration of NewAttribute class and definition of its only constructor.

The reader may ask the author why he chose to create new classes to do this, instead of modifying the old classes like Element, Attribute, CData and Comment. The reason is because these original classes contain many data members; To construct these class excessively on the stack and pop them out of the stack, would seriously hurt performance. As you would see from the above listing for new classes, I did not list their data member. That's because their only data member is ptr which exists in their base class, NewNode.

ptr is of type NewTreeNode. I had intended to name this tree structure, TreeNode but TreeNode is a reserved keyword in Visual C++ 10 because there is another TreeNode class defined in Visual C++ libraries.

NewTreeNode has Traverse method which creates MS XML DOM element as it traverse the tree recursively and it also has a Delete method which deletes the tree structure recursively. You see, to allocate and deallocate NewNode/NewElement objects on the stack, it is only a matter of pushing and popping 64bit/32bit pointers. Compare this in contrast to pushing and poping the heavy-duty Element class which contains these many data members below. For reader information, though the 64bit/32bit pointer is popped whenever NewNode object goes out of scope, the tree data which the pointer is pointed to, still lives on until they are saved to a file on disk.

How About Linq-To-XML Query?

While Elmax does not support Linq-To-XML style queries, it has some powerful query mechanism which is based on Lambda(anonymous function) to decide which elements to fetch back. Let me acquaint you with some of Elmax query mechanism.

Elmax has AsCollection and GetCollection methods which fetches a collection of siblings of the same name and fetches a collection of children of the same name, respectively. They both have an overloaded version which takes in an additional Lambda as predicate to filter the elements you want.

//! type of element vector
typedef std::vector< Element > collection_t;
//! Get the collection of sibling elements with the same name
collection_t AsCollection();
//! Get the collection of sibling elements with the same name
//! which satisfy the boolean predicate
template<typename Predicate>
collection_t AsCollection(Predicate pred);
//! Get the collection of child elements with same name
collection_t GetCollection(const std::wstring& name);
//! Get the collection of child elements with same name,
//! which satisfy the boolean predicate
template<typename Predicate>
collection_t GetCollection(const std::wstring& name,
Predicate pred);

Elmax provides HyperElement class which allows joining elements with another element which satisfies certain criteria. For example, in a Books application, Book element under the main Books section will be joined with the Author element (through AuthorID) under the main Authors section to retrieve the author name for the books. Books section and Authors section are 2 separate sections. A sample of the XML is provided below.

<?xmlversion="1.0"encoding="UTF-16"?><All><Version>1</Version><Books><BookISBN="1111-1111-1111"><Title>2001: A Space Odyssey</Title><Price>12.990000</Price><AuthorID>111</AuthorID></Book><BookISBN="2222-2222-2222"><Title>Rendezvous with Rama</Title><Price>15.000000</Price><AuthorID>111</AuthorID></Book><BookISBN="3333-3333-3333"><Title>Foundation</Title><Price>10.000000</Price><AuthorID>222</AuthorID></Book><BookISBN="4444-4444-4444"><Title>Currents of Space</Title><Price>11.900000</Price><AuthorID>222</AuthorID></Book><BookISBN="5555-5555-5555"><Title>Pebbles in the Sky</Title><Price>14.000000</Price><AuthorID>222</AuthorID></Book></Books><Authors><AuthorName="Arthur C. Clark"AuthorID="111"><Bio>Sci-Fic author!</Bio></Author><AuthorName="Isaac Asimov"AuthorID="222"><Bio>Sci-Fic author!</Bio></Author></Authors></All>

List of books by Arthur C. Clark
=============================================
2001: A Space Odyssey
Rendezvous with Rama
List of books by Isaac Asimov
=============================================
Foundation
Currents of Space
Pebbles in the Sky

In addition to these 2 methods of query, Elmax supports XPath expression through its various SelectNode methods.

Adding Beyond 16 Nodes

The overloaded constructors and Add methods of NewElement are ranged from taking 1 NewNode object to maximum 16 NewNode objects. What if the user need to add more than 16 nodes (like 17) for each element? Ans: he/she can use the Add method because Add method returns itself though (*this). Let me show you an example of adding 32 sub-elements to an element without using for-loop. In practice, a for-loop is the preferred method for adding elements more than 16.

There is another way to add more than 16 elements; There is an overloaded Add method which takes in an lambda. This method is only available on Visual C++ 11. On earlier version of Visual C++ (such as Visual C++ 10), the method is disabled by a _MSC_VER check due to lambda support in Visual C++ 10 is partially broken. Below is the definition of the Add method.

Memory Leak Prevention

If you construct a NewElement object and its children without saving, you will have memory leak. Because Save method will delete internal tree structure after saving, user need to call Discard method to delete the internal tree structure, if he/she, for some reason, decide not to save. User need to be careful here to avoid memory leak. I chose the option not to use smart pointer to store the tree structure for performance and memory reasons. I am not fond of the idea of using smart pointer in my code.

Points of Interest(SAX and ORM)

I am currently writing the SAX version of Elmax and also its article titled "The XML SAX Article that Programmers Should (not) be Reading" as a sequel to the original Elmax DOM article titled "The XML Parsing Article that Should (not) be Written". For reader who is not familiar with SAX XML; SAX stands for Simple API for XML. SAX simply reads a node at time during reading from a file. When writing to a file, SAX writes 1 node at a time. SAX does not store the XML node in a tree structure like XML DOM, thus SAX memory requirement to read a similar file is minimal compared to DOM. The Reader and Writer class of the SAX version is kept similar to the Elmax DOM version, whenever possible. For the SAX writer class, the Linq-To-XML node creation syntax is similar except for 1 additional requirement.

For elements which are not created in the scope of its constructors or Add methods, WriteEndElement needs to be called on them. For every XML element, there is always a start element stub(eg, <Book>) and end element stub (eg, </Book>) unless it does not have a value, (eg, <Book />). The reason for this requirement is the SAX library has no way of knowing when the user stops adding child elements and wants to close it.

This is how the SAX version of movie code will look like, with the WriteEndElement call.

So what is the rationale in keeping the DOM and SAX syntax similar? The reason are 2 fold. First of all, user does not need to learn a new syntax or totally new library to use SAX: Learning curve is lower. 2nd reason is I am writing a XML Object Relational Mapping (ORM) library using Elmax, when I keep the 2 syntax similar, then the ORM code generator for DOM and SAX Elmax would be similar to write as well. (Saves me some coding effort).

Uncommon Pitfall

I do not know if it is just me: When I use Linq-To-XML node creation, I made the mistake a few times of using names with whitespace for my elements and attributes. According to the XML specification, names with whitespace are simply not allowed. I rarely make this mistake while using other traditional ways of creating XML. This is perhaps due to Linq-To-XML syntax 'mixes' the name and value together: In the traditional API of creating XML, I will know very well whether I are specifying for a name or a value. If any of you have problems getting the XML out, please check if any of your element and attribute name has whitespace. I am pointing this out in case any of readers here share the same level of intelligence as the author.

Conclusion

We have looked at the different syntax of .NET C# Linq-To-XML, C++ Elmax Linq-To-XML and C++ Elmax original way of node creation. We have briefly discussed the internal workings of C++ Elmax Linq-To-XML node creation. We have also looked at ways to reduce memory consumption and eliminate memory leaks. Lastly I want to leave you with full code listings of each node creation method to add 4 movie information and save them to XML. Elmax is hosted at Codeplex: you can always get the latest version there. Any constructive feedback on the article, good or bad, is welcome.

2012-04-09 : Updated the source code (to version 0.83 beta) to include PJ Arends fix for missing closing tag (if there is no child elements) for PrettySave and Save methods.

2011-11-04 : Updated the source code (to version 0.82 beta) not to use MS XML for saving to reduce memory requirement and improve performance. Fixed PrettySave method as the previous one from MSDN forum does not work. Memory consumption section is removed from article.

As you can see the third line <Profile Name="Temperatures" Active="1" is not properly closed. It is an element that has attributes but no sub elements so the line should have the /> closing tag appended to it.

Make toll free long distance calls from your smart phone with ACN Mobile World. When connected via wifi, calls will not use any of your minutes or data, nor will there be any roaming charges. Certain conditions apply. See my website for details.Within you lies the power for good - Use it!

Very sorry about the bug. It is very gracious of you to not only report the bug and also provide a sample code to reproduce it and the code to fix the problem. I have fixed the problem for PrettySave and Save functions. The source code in the article is updated to include your fix.

BTW, I have changed the file save method not to use MS XML DOM to do the saving. In other words, I did the saving myself without relying on any third party XML library, so now the file saving is faster and requires less memory.