Title: ACCU Mentored Developers XML Project

As MSXML is COM based, the COM runtime must be started before any COM objects can be instantiated. The COM runtime is started by the CoInitializeEx API function and stopped with CoUninitialize. MSDN states that every call to CoInitializeEx must be matched by a call to CoUninitialize, even if CoInitializeEx fails.

CoUninitialize must not be called until all COM objects have been released. For instance in the example above there is an extra scope wrapping the MSXML code so that the IXMLDOMDocument2Ptr smart pointer destructor is called, destroying the DOM, before CoUninitialize is called.

The easiest way to achieve this, even in the presence of exceptions, is to take advantage of C++'s RAII (Resource Acquisition Is Initialization) and place CoInitialiseEx in the constructor of a class and CoUninitialize in the destructor and to create an instance of the class on the stack, at the beginning of the program before anything else. COMRuntimeInit, shown below, is just such a class. The copy constructor and copy-assignment operator are both private and undefined, to prevent copying. A COMRuntimeInit object has no state and therefore it does not make sense to copy it. This method of preventing copying and some more of the reasons behind it are discussed by Scott Meyers in Effective C++[ECpp].

#include <stdexcept>
#include <string>
#include <windows.h>
class COMRuntimeInit {
public:
  COMRuntimeInit() {
    HRESULT hr = ::CoInitializeEx(0,
                         COINIT_APARTMENTTHREADED);
    if(FAILED(hr)) {
      UnInitialize();
      std::string errorMsg = "Failed to start COM "
                             "Runtime: ";
      switch(hr) {
        case E_INVALIDARG:
          errorMsg += "An invalid parameter was "
                      "passed to the returning "
                      "function.";
          break;
        case E_OUTOFMEMORY:
          errorMsg += "Out of memory.";
          break;
        case E_UNEXPECTED:
          errorMsg += "Unexpected error.";
          break;
        case S_FALSE:
          errorMsg += "The COM library is already "
                      "initialized on this "
                      "thread.";
          break;
        default:
          errorMsg += "Unknown.";
          break;
      }
      throw std::runtime_error(errorMsg);
    }
  }
  ~COMRuntimeInit() {
    UnInitialize();
  }
private:
  void UnInitialize() const {
    ::CoUninitialize();
  }
  COMRuntimeInit(const COMRuntimeInit&);
  COMRuntimeInit& operator=(const COMRuntimeInit&);
};

There are of course times when the initial call to CoInitialiseEx may fail. The cause of the failure can be ascertained from its return value. The obvious way to communicate the cause of the failure to the user is via an exception. This has the drawback that the destructor will not be called when the constructor throws and therefore CoUninitialize must be called manually. For now std::runtime_error will be thrown when CoInitializeEx fails, later on we'll look at a custom exception type.

As stated above, the COMRuntimeInit instance must be declared before any other object on the stack. The instance cannot be put at file scope as it throws an exception if it fails, so the obvious place is at the top of main's scope. A try/catch block is also needed to detect the failure.

#include <iostream>
#include "comruntimeinit.h"
int main() {
  try {
    COMRuntimeInit comRuntime;
  }
  catch( const std::runtime_error& e) {
    std::cout << e.what() << "\n";
  }
  return 0;
}

Code that uses COM, as with most Microsoft API code, is just plain ugly and really should be hidden behind an interface. Exercise 1 of the XML project states that either the Xerces parser or the MSXML parser can be used. Ideally they should be easily interchangeable and their use completely hidden from the user. Hiding the ugly code and making the parsers easily interchangeable can be achieved with the Pimpl Idiom, as discussed by Herb Sutter in Exceptional C++ [ExCpp].

The first stage in the exercise is to create the MSXML DOM parser. This is achieved with the DOM class:

// dom.h
// Forward declaration so that implementation 
// can be completely hidden.
class DOMImpl;
class DOM {
private:
  DOMImpl *impl_;
public:
  DOM();
  ~DOM();
private:
  DOM(const DOM&);
  DOM& operator=(const DOM&);
};

The DOM class will form a basic wrapper for the DOMImpl class which will do all the work. DOMImpl is forward declared, so that its implementation can be completely hidden.

The DOM class implementation is shown below. It creates an instance of the DOMImplclass on the heap in the constructor and deletes it in the destructor.

// dom.cpp
#include "dom.h"
#include "domimpl.h"
DOM::DOM() : impl_(new DOMImpl) {}
DOM::~DOM() { delete impl_; }

DOMImpl creates the MSXML DOM parser in the same way as the PerfectXML example:

// domimpl.h
#import "msxml4.dll"
class DOMImpl {
private:
  MSXML2::IXMLDOMDocument2Ptr xmlDoc_;
public:
  DOMImpl() : xmlDoc_(0) {
    xmlDoc_.CreateInstance(
                    "Msxml2.DOMDocument.4.0");
  }
private:
  DOMImpl(const DOMImpl&);
  DOMImpl& operator=(const DOMImpl&);
};

Both DOM and DOMImpl have private copy constructors and copy assignment operators, again to prevent copying.

The above code does not include any error checking. It is possible for the call to CreateInstance to fail. The msxml4.dll may not be registered, for example. The success or failure of the CreateInstance call can be detected by its return value.

DOMImpl() : xmlDoc_(0) {
  HRESULT hr = xmlDoc_.CreateInstance(
                   "Msxml2.DOMDocument.4.0");
  if(FAILED(hr)) {
    std::string errorMsg = "Failed to start "
                           "create MSXML "
                           "DOM: ";
    switch(hr) {
      case CO_E_NOTINITIALIZED:
        errorMsg += "CoInitialize has not "
                    "been called.";
        break;
      case CO_E_CLASSSTRING:
        errorMsg += "Invalid class string.";
        break;
      case REGDB_E_CLASSNOTREG:
        errorMsg += "A specified class is "
                    "not registered."
        break;
      case CLASS_E_NOAGGREGATION:
        errorMsg += "This class cannot be "
                    "created as part of an "
                    "aggregate.";
        break;
      case E_NOINTERFACE:
        errorMsg += "The specified class "
                    "does not implement the "
                    "requested interface";
        break;
      default:
        errorMsg += "Unknown error.";
        break;
    }
    throw std::runtime_error(errorMsg );
  }
}

We now have three classes which are "copy prevented", with a private copy constructor and copy assignment operator. There is a clearer way to document the fact that a class is not intended to be copied. When used by a number of different classes it also reduces the amount of code.

The NonCopyable class, show below, has a private copy constructor and assignment operator to prevent prevent copying. When another class inherits from NonCopyable, the private copy constructor and assignment operator are also inherited. This both prevents the subclass from being copied and documents the intention. The relationship between NonCopyable and its subclass is not IS-A and therefore the inheritance can be private.

As NonCopyable is intended only to provide behaviour to a derived class, rather than act as a class in its own right, its default constructor is protected, preventing a free NonCopyable object being created. Its destructor too, is protected to prevent a subclass being deleted via a pointer to NonCopyable. To further document this intention, the destructor is not virtual.

class NonCopyable {
protected:
  NonCopyable() {}
  ~NonCopyable() {}
private:
  NonCopyable(const NonCopyable&);
  NonCopyable& operator=(const NonCopyable&);
};

The NonCopyable class was written by Dave Abrahams for the boost [boost] library. I have recreated it here so that a dependency on the boost library is avoided.

Now that the NonCopyable class is in place the copy constructors and assignment operators can be removed from COMRuntimeInit, DOM and DOMImpl. They can then be changed to privately inherit from NonCopyable.

class COMRuntimeInit : private NonCopyable {
  ...
};

class DOM : private NonCopyable {
  ...
};

class DOMImpl : private NonCopyable {
  ...
};

The MSXML DOM has a method that loads and parses an XML file. While parsing the file it is checked to make sure it is well formed and if there is a DTD or Schema specified it is also validated. If the file cannot be opened, is not well formed or cannot be validated the call fails.

The method is called load and takes a single parameter which is the full path to the XML file. To load and parse an XML file, a similar method can be added to DOMImpl and a corresponding forwarding function added to DOM.

class DOMImpl : private NonCopyable {
public:
  ...
  void Load(const std::string& fullPath) {
    xmlDoc_->load(fullPath.c_str());
  }
};

main can then be modified to call the new function with the path to an XML file.

try {
  COMRuntimeInit comRuntime;
  DOM dom;
  dom.Load("poem.xml");
}
catch(const std::runtime_error& e) {
  std::cout << e.what() << "\n";
}

Once again there is no way of detecting failure and the return value of the MSXML DOM load method must be tested to find out if it failed. If a failure has occurred an exception should be thrown.

void Load(const std::string& fullPath) {
  if(!xmlDoc_->load( fullPath.c_str())) {
    throw std::runtime_error(ErrorMessage());
  }
}

The method of extracting an error message from an MSXML DOM is a little fiddly, so I have placed it in its own function, ErrorMessage.

class DOMImpl : private NonCopyable {
public:
  ...
  std::string ErrorMessage() const {
    std::string result = "Failed to extract "
                         "error.";
    MSXML2::IXMLDOMParseErrorPtr pError =
                         xmlDoc_->parseError;
    if(pError->reason.length()) {
      result = pError->reason;
    }
    return result;
  }
};

A parse error is extracted from an MSXML DOM as an XMLDOMParserError object. The error description is fetched from the reason property. If no description is available, the bstr_t returned by reason has a length of 0. bstr_t is a wrapper class for COM's native unsigned short* string type. It provides a conversion to const char*, and thus can be assigned to a std::string.

Our main function's body is

try {
  COMRuntimeInit comRuntime;
  DOM dom;
  dom.Load("poem.xml");
}
catch(const std::runtime_error& e) {
  std::cout << e.what() << "\n";
}

Currently the example throws a std::runtime_error if the COM runtime fails to initialise or if there is an XML failure. In both cases the error message is prefixed with a description of the type of error. Exceptions thrown as a result of the COM runtime failing to initialise are probably fatal and it may be appropriate for the program to exit, while for exceptions thrown due to an XML parse fail it might be more appropriate to log the error and move on to the next file.

These different categories of error would be better communicated by the exception's actual type and it is easy to add custom exceptions. Throwing different types of exceptions helps to maintain the context in which the exception was thrown and enables the behaviour of a program to change based on the type of exception that is thrown.

Deriving from std::exception not only means that custom exception types can be caught along with other standard exception types in a single catch statement if necessary, but also provides an implementation for the custom exception object.

class BadCOMRuntime : public std::exception {
public:
  BadCOMRuntime(const std::string& msg)
        : exception(msg.c_str()) {}
};

std::exception's constructor takes a char*, but I know that I will be building exception messages with strings and following the model of std::runtime_error, BadCOMRuntime's constructor takes a std::string.

COMRuntimeInit's constructor must be modified for the new exception:

COMRuntimeInit() {
  HRESULT hr = ::CoInitialize(0);
  if(FAILED(hr)) {
    UnInitialize();
    std::string errorMsg = "Unknown.";
    switch(hr) {
      case E_INVALIDARG:
        errorMsg = "An invalid parameter was "
                   "passed to the returning "
                   "function.";
        break;
      ...
      default:
        break;
    }
    throw BadCOMRuntime(errorMsg);
  }
}

and main must be modified to catch the new exception:

try {
  COMRuntimeInit comRuntime;
  DOM dom;
  dom.Load("poem.xml");
}
catch(const BadCOMRuntime& e) {
  std::cout << "COM initialisation error: "
            << e.what()
            << "\n";
}
...

The exceptions thrown by DOMImpl are a little more complicated. DOMImpl throws exceptions when two different things happen and therefore requires two different exception types, which should be in some way related. One way to solve this is to have a common exception type for DOMImpl from which two other exception types derive.

DOMImpl is the implementation of DOM and any exception thrown by DOMImpl is most likely to be caught outside DOM. Therefore, to the user of DOM, who is unaware of DOMImpl, it is more logical for DOM to be throwing exceptions of type BadDOM rather than BadDOMImpl.

#include <stdexcept>
#include <string>
class BadDOM : public std::exception {
public:
  BadDOM(const std::string& msg)
        : exception(msg.c_str()) {}
};
class CreateFailed : public BadDOM {
public:
  CreateFailed(const std::string& msg)
        : BadDOM(msg) {}
};
class BadParse : public BadDom {
public:
  BadParse(const std::string& msg)
        : BadDOM(msg) {}
};

The constructor and Load function in DOMImpl can now be modified to use the new exception types and main modified to catch a BadDOM exception. For completeness sake, we also need a third catch block. The COM smart pointers generated by #import raise a _com_error if a function call fails.

try {
  COMRuntimeInit comRuntime;
  DOM dom;
  dom.Load("poem.xml");
}
catch(const BadCOMRuntime& e) {
  std::cout << "COM initialisation error: "
            << e.what() << "\n";
}
catch(const BadDOM& e) {
  std::cout << "DOM error: "
            << e.what() << "\n";
}
catch(const _com_error& e) {
  std::cout << "COM error: "
            << e.ErrorMessage() << "\n";
}

The first step in enabling the elements to be written to an output stream is to pass one in. The obvious way to do this is to is to add a function to DOMImpl, and a forwarding function to DOM, which takes a std::ostream reference.

#include <ostream>
class DOMImpl : private NonCopyable {
...
public:
  void WriteTree(std::ostream& out) {}
...
};

Modifying main to call the new function means that results can be seen straight away as the WriteTree implementation is developed.

try {
  COMRuntimeInit comRuntime;
  DOM dom;
  dom.Load("poem.xml");
  dom.WriteTree(std::cout);
}
...

In order to write the complete tree, every element must be visited. Starting with the root element, the rest of the elements can then be visited in a depth-first traversal. I wrote the following function, based on some Delphi written by Adrian Fagg, which gets a pointer to the root element and then calls the function WriteBranch which recurses the rest of the tree.

void WriteTree(std::ostream& out) {
  MSXML2::IXMLDOMElementPtr root =
                     xmlDoc_->documentElement;
  WriteBranch(root, 0, out);
}

The WriteBranch function is also based on Adrian Fagg's Delphi code. The code is self explanatory, but basically it:

void WriteBranch(
            MSXML2::IXMLDOMElementPtr element, 
            unsigned long indentation,
            std::ostream& out) {
  bstr_t cbstr element->tagName;
  out << std::string(2 * indentation, ' ') 
      << cbstr << std::endl;
  MSXML2::IXMLDOMNodePtr child =
                          element->firstChild;
  while(child != 0) {
    if(child->nodeType ==
                      MSXML2::NODE_ELEMENT) {
      WriteBranch(child,
                  indentation + 1, out);
    }
    child = child->nextSibling;
  }
}

The result of running the program is now that the following is written to the console:

poem
  line
  line
  line
  line

With that the exercise is complete.