XmlUtil

Not much to say about this namespace. You probably won't use the initialization and termination functions directly, you'll use the ones in the DOM and SAX namespaces which call these to handle the common initialization. The Exception class you'll likewise rarely use directly, if you create exceptions at all you'll use it's children XmlDOMException or XmlSAXException depending on whether you're using the DOM or SAX routines. And even then you'll usually only use the single-string-argument constructor, the more exotic variants are used within the library to create exceptions with information from one of the underlying XercesC exception classes.

The only class you might use commonly is XmlStr. It's a fairly basic class, just constructors and two access methods. You pass it either one of the normal C++ string types or a XercesC Unicode string pointer, and then use the U() and S() accessors to get at either the Unicode or normal string representations. About the only reason for the class to exist is to wrap up the XercesC translation functions so the library code doesn't have to keep repeating the same fragment of Unicode-to-string or string-to-Unicode translation code all the time. You may need this functionality if you're working directly with the XercesC routines themselves to do things, but within this library the routines all do the translation under the hood and let you work with plain vanilla C++ strings.

Library utility

Startup and termination

Prototypes:

• Initialize()
• Terminate()

These two routines initialize and clean up the library when the program's done using it, taking care of calling the necessary Xercesc library routines in the process. They contain checks to prevent incorrect operation if called too many times or in the wrong order. Don't attempt to use XML Library routines before initialization has been done, or after the termination routine's been called. The DOM and SAX libraries use XmlUtil's Initialize() and Terminate() routines in their own initialization and termination.

Namespace checking

Prototype:

• bool isXMLStdNamespace( const XMLCh * )

Checks whether a given namespace matches the standard prefixes used for XML namespaces, currently "xsi" and "xmlns". Normally these two prefixes are used for attributes defined by XML itself, and those attributes often need to be ignored (eg. when looking for an attribute named "type" without namespace qualification, the attribute "xsi:type" should be ignored since it didn't come from the actual document).

Exception

This is a fairly simple class designed to contain data from various kinds of exceptions the library can encounter. XercesC provides several types of exceptions, and the XML library also needs to throw it's own exceptions. Wrapping them all in a single class hierarchy makes it easy to catch all varieties of exceptions without having to write a half-dozen catch blocks (for cases where you only care about knowing that an exception occurred and being able to print a sensible error message for a human) while still letting you get at all the information contained in the original exceptions and being able to distinguish between exceptions thrown by the XML library vs. ones thrown by the underlying XercesC library.

Constructors: default, copy, char *, std::string, xercesc::XMLException

Prototypes:

• Exception()
• Exception( const Exception& )
• Exception( const char * const )
• Exception( const std::string )
• Exception( const xercesc::XMLException& )

The standard complement of constructors. You can construct an empty exception (no type, code or message), copy exceptions, and initialize them from character pointers and strings (empty type string, zero code, the message is the string you provide) or from a XercesC XMLException object (type "XML", the code and message are taken from the code and message of the Xercesc exception). Normally you won't need to worry about construction exception objects, and if you do need to construct them you'd normally be using one of the constructors that takes a string argument. The only exception would be if you're using the underlying XercesC routines in your own code and need to construct Exception objects to simplify exception handling in higher layers of code.

The type strings used by this class are "XML" (coming from an XMLException object) and "" (coming from a user-supplied string. For type "" the code field is always zero, for type "XML" it comes from the code field of the underlying XMLException object.

Assignment operator

Prototype:

• Exception& operator=( const Exception& )

The standard assignment operator.

Field get operations

Prototypes:

• const std::string& getType() const
• unsigned int getCode() const
• const std::string& getMessage() const

These return the values of the data fields in the exception. The type field can be used to determine what kind of exception generated this object, the code field holds the numeric code for those source exceptions that have an error code, and the message field holds the message text from the source exception.

XmlStr

I found I was calling translation functions a lot to turn Unicode strings into standard C++ strings, and vice versa, in the course of passing data between my own C++ code and the XercesC library. So I wrapped it all up in a single class that'd let you create objects from either kind of string and get either representation back whenever you needed it. It involves some dynamic memory allocation, because that's the way the XercesC library does it's Unicode strings.

Constructors: default, copy, std::string, char *, XMLCh *, XMLCh * + length

Prototypes:

• XmlStr()
• XmlStr( const XmlStr& )
• XmlStr( const std::string& )
• XmlStr( const char * const )
• XmlStr( const XMLCh * const )
• XmlStr( const XMLCh * const, XMLSize_t )

The expected set of constructors to create XmlStr objects from various kinds of ordinary strings. The default constructor creates an empty object (no string contained), the copy constructor copies the object. The rest create objects initialized with the strings you provide, translating into both representations in the process. Presumably if you only need the same representation as your input you won't be using an XmlStr object, so they're not highly efficient when you don't actually use the other representation.

Assignment operators

Prototypes:

• XmlStr& operator=( const XmlStr& )

The standard assignment operator.

Destructor

Prototype:

• ~XmlStr()

Standard destructor, cleans up the object completely.

Relational operators

Prototypes:

• bool operator==( const XmlStr& ) const
• bool operator!=( const XmlStr& ) const
• bool operator>( const XmlStr& ) const
• bool operator>=( const XmlStr& ) const
• bool operator<( const XmlStr& ) const
• bool operator<=( const XmlStr& ) const

The standard complement of relational operations. These work on the standard C++ string representation of the string. This will normally be a UTF-8 string so the comparisons will be correct.

Data extraction methods

Prototypes:

• const XMLCh * const U() const
• const std::string& S() const

U() returns a pointer to the XercesC Unicode string form of the contained string. S() returns a reference to the standard C++ string form. Don't try to override the constness to change the representations in-place, this'll cause inconsistencies in the object.

Reset function

Prototype:

• void Reset()

Resets the object to the state it would be in immediately after being constructed via the default constructor.