xercesDomUtil.h

Go to the documentation of this file.

#ifndef XERCESDOMUTIL_H
#define XERCESDOMUTIL_H

#include <exception>
#include <string>
#include <vector>
#include <xercesc/dom/DOM.hpp>
#include <xercesc/util/XMLString.hpp>
#include <sys/time.h>

#include "Exceptions.h"

BOREALIS_NAMESPACE_BEGIN;

#ifdef XERCES_CPP_NAMESPACE
using namespace xercesc;
#endif

//===============================================================================

// Creates an XML file with the specified name, whose contents is the specified
// subtree.
void writeDomDocToFile(const DOMDocument & doc, string filename)
  throw (exception);

// Creates a DOMDocument from the specified XML file using the provided
// implementation object.
DOMDocument * readDomDocFromFile(DOMImplementationLS & impl, string filename)
  throw (exception);

// Uses the DOMImplementationRegistry. Will throw an exception rather than 
// returning NULL.
DOMImplementationLS * getDomImplementationLs()
  throw (exception);

// Uses the DOMImplementationRegistry
DOMImplementation * getDomImplementation()
  throw (exception);

DOMElement * createDomElement(DOMDocument & docOwner, string elementName)
  throw (exception);

// Returns a pointer to the one and only child element with the the specified
// tag. Throws an exception if there wasn't exactly one such child.
DOMElement * getDomChildByKeyTag(const DOMElement & parent, string childTagName)
  throw (exception);

//===============================================================================

// Tries to parse the specified string as a bool ('T' or 'F'). Throws an 
// exception if it can't.
bool parseXmlStringAsBool(const XMLCh * pXml)
  throw (exception);

// Parse the XML string as the specified kind of number. Throw an exception if it
// can't be done...

int parseXmlStringAsInt(const XMLCh * pXml)
  throw (exception);

unsigned int parseXmlStringAsUInt(const XMLCh * pXml)
  throw (exception);

unsigned long parseXmlStringAsLong(const XMLCh * pXml)
  throw (exception);

unsigned long parseXmlStringAsULong(const XMLCh * pXml)
  throw (exception);

// Note: This won't necessarily discover overflow, because I had to implement 
// this on my own and didn't want to take the time to make a perfect bad-parse
// detector. -cjc
unsigned long long parseXmlStringAsULongLong(const XMLCh * pXml)
  throw (exception);

double parseXmlStringAsDouble(const XMLCh * pXml)
  throw (exception);

//===============================================================================

// Creates an XML subtree, rooted at 'elem', representing the content of the 
// vector.
void saveIntVectorToXml(const vector<int> & v, DOMDocument & doc, DOMElement & elem)
  throw (exception);

// Given an element populated by saveIntVectorToXml, this will append 'v' with
// the saved vector's elements (in proper order).
void loadIntVectorFromXml(vector<int> & v, DOMElement & elem)
  throw (exception);

//===============================================================================

// Creates an XML subtree, rooted at 'elem', representing the content of the 
// timeval.
void saveTimevalToXml(const timeval & tv, DOMDocument & doc, DOMElement & elem)
  throw (exception);

// Given an element populated by saveTimevalToXml, this will populate 'tv' with
// the saved timeval's fields.
void loadTimevalFromXml(timeval & tv, DOMElement & elem)
  throw (exception);

//===============================================================================

// Numeric type promotion + normal overloading keeps us out of trouble here, so
// we can avoid user-specified templates. Thus, the proper version of this 
// function will always be called for parameters like size_t and ssize_t.

void setDomAttribute(DOMElement & elem, string attributeName, bool newValue)
  throw (exception);

void setDomAttribute(DOMElement & elem, string attributeName, int newValue)
  throw (exception);

void setDomAttribute(DOMElement & elem, string attributeName, unsigned int newValue)
  throw (exception);

void setDomAttribute(DOMElement & elem, string attributeName, long newValue)
  throw (exception);

void setDomAttribute(DOMElement & elem, string attributeName, unsigned long newValue)
  throw (exception);

void setDomAttribute(DOMElement & elem, string attributeName, unsigned long long newValue)
  throw (exception);

// NOTE! This might produce a messed up XML file if 'newValue' has characters 
// that are XML control characters. If/when we need to handle this, we can must 
// an encoding scheme in this function and the corresponding 'getDomAttribute' 
// function.
void setDomAttribute(DOMElement & elem, string attributeName, string newValue)
  throw (exception);

void setDomAttribute(DOMElement & elem, string attributeName, double newValue)
  throw (exception);



void getDomAttribute(const DOMElement & elem, string attributeName, bool & value)
  throw (exception);

void getDomAttribute(const DOMElement & elem, string attributeName, int & value)
  throw (exception);

void getDomAttribute(const DOMElement & elem, string attributeName, unsigned int & value)
  throw (exception);

void getDomAttribute(const DOMElement & elem, string attributeName, long & value)
  throw (exception);

void getDomAttribute(const DOMElement & elem, string attributeName, unsigned long & value)
  throw (exception);

void getDomAttribute(const DOMElement & elem, string attributeName, unsigned long long & value)
  throw (exception);

void getDomAttribute(const DOMElement & elem, string attributeName, string & newValue)
  throw (exception);

void getDomAttribute(const DOMElement & elem, string attributeName, double & newValue)
  throw (exception);


// Returns true if the attribute with the specified name is defined in the 
// element, otherwise returns false.
bool isDomAttributePresent(const DOMElement & elem, string attributeName)
  throw (exception);




//*******************************************************************************
// Alternative approach to Xerces stuff that Jon Salz from MIT wrote.  Should 
// peacefully coexist with the stuff above, and have only partial overlap of
// functionality...
//*******************************************************************************

// Utility functions for XML parsing.  (There's some overlap with xercesDomUtil.H.)

enum XmlAttrReq {
    ATTR_NOT_REQUIRED = 0,
    ATTR_REQUIRED = 1,
    ATTR_NON_EMPTY = 2
};

// Parse a whole XML file.  (Differs from readDomDocFromFile in that
// you don't need to create your own DOMImplementationLS.)
ptr<DOMDocument> parseXmlFile(string filename) throw (AuroraBadXmlException);

// Parse a string as an XML document.
ptr<DOMDocument> parseXmlString(string data) throw (AuroraBadXmlException);

// Parse data as an XML document.
ptr<DOMDocument> parseXmlString(const void *data, unsigned int length) throw (AuroraBadXmlException);

// Return an attribute of an elemnt.  If req is ATTR_REQUIRED and the
// attribute is not specified, or if req is ATTR_NON_EMPTY and the the
// attribute is not specified or empty (""), throws an exception.
string xmlAttribute(const DOMElement *element, string name,
                    XmlAttrReq req = ATTR_NOT_REQUIRED) throw(AuroraBadEntityException);

// Return an attribute of an element, or def if the attribute is not
// present.
string xmlAttribute(const DOMElement *element, string name, string def) throw (AuroraBadEntityException);

// Throw an exception unless the given tag has a particular name.
// (Basically an assert.)
void xmlExpectTag(const DOMElement *element, string name) throw (AuroraBadEntityException);

// Reads an attribute value into the "value" argument.  Throws an
// exception if (a) a value is specified but has an invalid format, or
// (b) req is ATTR_REQUIRED but the attribute value is not specified.
//
// You can specify an optional value by setting value before calling
// this method.
template <class T>
inline bool xmlTypedAttribute(const DOMElement *element, string name, T& value,
                              XmlAttrReq req = ATTR_NOT_REQUIRED) throw (AuroraBadEntityException)
{
    XMLCh xname[64];
    XMLString::transcode(name.c_str(), xname, sizeof xname - 1);

    const DOMAttr *attr = element->getAttributeNode(xname);
    if (!attr) {
        if (req != ATTR_NOT_REQUIRED) {
            Throw(AuroraBadEntityException,
                  "<" + to_string(element->getTagName()) + "> lacks "
                  "required attribute \"" + name + "\"");
        }
        return false;
    }

    // It's provided; coerce it
    string val = to_string(attr->getValue());

    istringstream i(val);
    if (i >> value)
        return true;

    Throw(AuroraBadEntityException, "Invalid format for <" +
          to_string(element->getTagName()) + " " + name + "=\"" + val + "\">");
}

// Escapes the &<>"' characters in a string.
string xmlEscape(string in);

// Returns the only tag within parent (or zero if none).  Throws an exception
// if there more than one tag, or if there are no tags and required is true.
DOMElement* xmlOnlyTag(const DOMElement* parent, bool required = true)
    throw (AuroraException);

// Returns the only tag with a particular name within parent (or zero
// if none).  Throws an exception if there more than one tag, or if
// there are no tags and required is true.
DOMElement* xmlOnlyTag(const DOMElement* parent, string tag, bool required = true)
    throw (AuroraException);

// Returns immediate subnodes with a given tag.  Clears children first.
void xmlChildElements(vector<DOMElement*>& children, const DOMElement* parent, string tag = string());

// Serialize a DOM node as text.
string xmlSerialize(const DOMNode *node);

BOREALIS_NAMESPACE_END;

#endif

---