http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Home

Readme
Download
Installation
Build Instructions

API Docs
Samples
Schema

FAQs
Programming
Migration

Releases
Bug-Reporting
Feedback

Y2K Compliance
PDF Document

CVS Repository
Mail Archive

This page has sections on the following topics:

SAX1 Programming Guide
 
Constructing a parser
 

In order to use Xerces-C++ to parse XML files, you will need to create an instance of the SAXParser class. The example below shows the code you need in order to create an instance of SAXParser. The DocumentHandler and ErrorHandler instances required by the SAX API are provided using the HandlerBase class supplied with Xerces-C++.

int main (int argc, char* args[]) {

    try {
        XMLPlatformUtils::Initialize();
    }
    catch (const XMLException& toCatch) {
        cout << "Error during initialization! :\n"
             << DOMString(toCatch.getMessage()) << "\n";
        return 1;
    }

    char* xmlFile = "x1.xml";
    SAXParser* parser = new SAXParser();
    parser->setDoValidation(true);    // optional.
	parser->setDoNamespaces(true);    // optional

    DocumentHandler* docHandler = new HandlerBase();
    ErrorHandler* errHandler = (ErrorHandler*) docHandler;
    parser->setDocumentHandler(docHandler);
    parser->setErrorHandler(errHandler);

    try {
        parser->parse(xmlFile);
    }
    catch (const XMLException& toCatch) {
        cout << "Exception message is: \n"
             << DOMString(toCatch.getMessage()) << "\n" ;
        return -1;
    }
    catch (const SAXParseException& toCatch) {
        cout << "Exception message is: \n"
             << DOMString(toCatch.getMessage()) << "\n" ;
        return -1;
    }
    catch (...) {
        cout << "Unexpected Exception \n" ;
        return -1;
    }
}

Using the SAX API
 

The SAX API for XML parsers was originally developed for Java. Please be aware that there is no standard SAX API for C++, and that use of the Xerces-C++ SAX API does not guarantee client code compatibility with other C++ XML parsers.

The SAX API presents a callback based API to the parser. An application that uses SAX provides an instance of a handler class to the parser. When the parser detects XML constructs, it calls the methods of the handler class, passing them information about the construct that was detected. The most commonly used handler classes are DocumentHandler which is called when XML constructs are recognized, and ErrorHandler which is called when an error occurs. The header files for the various SAX handler classes are in '<xerces-c1_6_0>/include/sax'

As a convenience, Xerces-C++ provides the class HandlerBase, which is a single class which is publicly derived from all the Handler classes. HandlerBase's default implementation of the handler callback methods is to do nothing. A convenient way to get started with Xerces-C++ is to derive your own handler class from HandlerBase and override just those methods in HandlerBase which you are interested in customizing. This simple example shows how to create a handler which will print element names, and print fatal error messages. The source code for the sample applications show additional examples of how to write handler classes.

This is the header file MySAXHandler.hpp:

#include <sax/HandlerBase.hpp>

class MySAXHandler : public HandlerBase {
public:
    void startElement(const XMLCh* const, AttributeList&);
    void fatalError(const SAXParseException&);
};

This is the implementation file MySAXHandler.cpp:

#include "MySAXHandler.hpp"
#include <iostream.h>

MySAXHandler::MySAXHandler()
{
}

MySAXHandler::startElement(const XMLCh* const name,
                           AttributeList& attributes)
{
    // transcode() is an user application defined function which
    // converts unicode strings to usual 'char *'. Look at
    // the sample program SAXCount for an example implementation.
    cout << "I saw element: " << transcode(name) << endl;
}

MySAXHandler::fatalError(const SAXParseException& exception)
{
    cout << "Fatal Error: " << transcode(exception.getMessage())
         << " at line: " << exception.getLineNumber()
         << endl;
}

The XMLCh and AttributeList types are supplied by Xerces-C++ and are documented in the include files. Examples of their usage appear in the source code to the sample applications.



SAX2 Programming Guide
 
Constructing an XML Reader
 

In order to use Xerces-C++ to parse XML files, you will need to create an instance of the SAX2XMLReader class. The example below shows the code you need in order to create an instance of SAX2XMLReader. The ContentHandler and ErrorHandler instances required by the SAX API are provided using the DefaultHandler class supplied with Xerces-C++.

int main (int argc, char* args[]) {

    try {
        XMLPlatformUtils::Initialize();
    }
    catch (const XMLException& toCatch) {
        cout << "Error during initialization! :\n"
             << DOMString(toCatch.getMessage()) << "\n";
        return 1;
    }

    char* xmlFile = "x1.xml";
    SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
    parser->setFeature(XMLString::transcode("http://xml.org/sax/features/validation", true)   // optional
    parser->setFeature(XMLString::transcode("http://xml.org/sax/features/namespaces", true)   // optional

    ContentHandler* contentHandler = new DefaultHandler();
    ErrorHandler* errHandler = (ErrorHandler*) contentHandler;
    parser->setContentHandler(contentHandler);
    parser->setErrorHandler(errHandler);

    try {
        parser->parse(xmlFile);
    }
    catch (const XMLException& toCatch) {
        cout << "Exception message is: \n"
             << DOMString(toCatch.getMessage()) << "\n" ;
        return -1;
    }
    catch (const SAXParseException& toCatch) {
        cout << "Exception message is: \n"
             << DOMString(toCatch.getMessage()) << "\n" ;
        return -1;
    }
    catch (...) {
        cout << "Unexpected Exception \n" ;
        return -1;
    }
}

Using the SAX2 API
 

The SAX2 API for XML parsers was originally developed for Java. Please be aware that there is no standard SAX2 API for C++, and that use of the Xerces-C++ SAX2 API does not guarantee client code compatibility with other C++ XML parsers.

The SAX2 API presents a callback based API to the parser. An application that uses SAX2 provides an instance of a handler class to the parser. When the parser detects XML constructs, it calls the methods of the handler class, passing them information about the construct that was detected. The most commonly used handler classes are ContentHandler which is called when XML constructs are recognized, and ErrorHandler which is called when an error occurs. The header files for the various SAX2 handler classes are in '<xerces-c1_6_0>/include/sax2'

As a convenience, Xerces-C++ provides the class DefaultHandler, which is a single class which is publicly derived from all the Handler classes. DefaultHandler's default implementation of the handler callback methods is to do nothing. A convenient way to get started with Xerces-C++ is to derive your own handler class from DefaultHandler and override just those methods in HandlerBase which you are interested in customizing. This simple example shows how to create a handler which will print element names, and print fatal error messages. The source code for the sample applications show additional examples of how to write handler classes.

This is the header file MySAX2Handler.hpp:

#include <sax2/DefaultHandler.hpp>

class MySAX2Handler : public DefaultHandler {
public:
    void startElement(
        const   XMLCh* const    uri,
        const   XMLCh* const    localname,
        const   XMLCh* const    qname,
        const   Attributes&     attrs
    );
    void fatalError(const SAXParseException&);
};

This is the implementation file MySAX2Handler.cpp:

#include "MySAX2Handler.hpp"
#include <iostream.h>

MySAX2Handler::MySAX2Handler()
{
}

MySAX2Handler::startElement(const   XMLCh* const    uri,
                            const   XMLCh* const    localname,
                            const   XMLCh* const    qname,
                            const   Attributes&     attrs)
{
    // transcode() is an user application defined function which
    // converts unicode strings to usual 'char *'. Look at
    // the sample program SAX2Count for an example implementation.
    cout << "I saw element: " << transcode(qname) << endl;
}

MySAX2Handler::fatalError(const SAXParseException& exception)
{
    cout << "Fatal Error: " << transcode(exception.getMessage())
         << " at line: " << exception.getLineNumber()
         << endl;
}

The XMLCh and Attributes types are supplied by Xerces-C++ and are documented in the include files. Examples of their usage appear in the source code to the sample applications.


Xerces SAX2 Supported Features
 

The behavior of the SAX2XMLReader is dependant on the values of the following features. All of the features below can be set using the function SAX2XMLReader::setFeature(cons XMLCh* const, const bool). And can be queried using the function bool SAX2XMLReader::getFeature(const XMLCh* const).

None of these features can be modified in the middle of a parse, or an exception will be thrown.

http://xml.org/sax/features/namespaces 
true:  Perform Namespace processing (default) 
false:  Optionally do not perform Namespace processing 

http://xml.org/sax/features/namespace-prefixes 
true:  Report the orignal prefixed names and attributes used for Namespace declarations (default) 
false:  Do not report attributes used for Namespace declarations, and optionally do not report original prefixed names.  

http://xml.org/sax/features/validation 
true:  Report all validation errors. (default) 
false:  Do not report validation errors.  

http://apache.org/xml/features/validation/dynamic 
true:  The parser will validate the document only if a grammar is specified. (http://xml.org/sax/features/validation must be true) 
false:  Validation is determined by the state of the http://xml.org/sax/features/validation feature (default) 

http://apache.org/xml/features/validation/schema 
true:  Enable the parser's schema support. (default)  
false:  Disable the parser's schema support.  

http://apache.org/xml/features/validation/schema-full-checking 
true:  Enable full schema constraint checking, including checking which may be time-consuming or memory intensive. Currently, particle unique attribution constraint checking and particle derivation resriction checking are controlled by this option.  
false:  Disable full schema constraint checking (default).  

http://apache.org/xml/features/validation/reuse-grammar 
true:  The parser will reuse grammar information from previous parses in subsequent parses.  
false:  The parser will not reuse any grammar information. (default) 

http://apache.org/xml/features/validation/reuse-validator (deprecated)
Please use http://apache.org/xml/features/validation/reuse-grammar  
true:  The parser will reuse grammar information from previous parses in subsequent parses.  
false:  The parser will not reuse any grammar information. (default) 

Xerces SAX2 Supported Properties
 

The behavior of the SAX2XMLReader is dependant on the values of the following properties. All of the properties below can be set using the function SAX2XMLReader::setProperty(const XMLCh* const, void*). It takes a void pointer as the property value. Application is required to initialize this void pointer to a correct type. Please check the column "Value Type" below to learn exactly what type of property value each property expects for processing. Passing a void pointer that was initialized with a wrong type will lead to unexpected result. If the same property is set more than once, the last one takes effect.

Property values can be queried using the function void* SAX2XMLReader::getFeature(const XMLCh* const). The parser owns the returned pointer, and the memory allocated for the returned pointer will be destroyed when the parser is deleted. To ensure assessiblity of the returned information after the parser is deleted, callers need to copy and store the returned information somewhere else. Since the returned pointer is a generic void pointer, check the column "Value Type" below to learn exactly what type of object each property returns for replication.

None of these properties can be modified in the middle of a parse, or an exception will be thrown.

http://apache.org/xml/properties/schema/external-schemaLocation 
Description  The XML Schema Recommendation explicitly states that the inclusion of schemaLocation/ noNamespaceSchemaLocation attributes in the instance document is only a hint; it does not mandate that these attributes must be used to locate schemas. Similar situation happens to <import> element in schema documents. This property allows the user to specify a list of schemas to use. If the targetNamespace of a schema specified using this method matches the targetNamespace of a schema occurring in the instance document in schemaLocation attribute, or if the targetNamespace matches the namespace attribute of <import> element, the schema specified by the user using this property will be used (i.e., the schemaLocation attribute in the instance document or on the <import> element will be effectively ignored). 
Value  The syntax is the same as for schemaLocation attributes in instance documents: e.g, "http://www.example.com file_name.xsd". The user can specify more than one XML Schema in the list. 
Value Type  XMLCh*  

http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation 
Description  The XML Schema Recommendation explicitly states that the inclusion of schemaLocation/ noNamespaceSchemaLocation attributes in the instance document is only a hint; it does not mandate that these attributes must be used to locate schemas. This property allows the user to specify the no target namespace XML Schema Location externally. If specified, the instance document's noNamespaceSchemaLocation attribute will be effectively ignored. 
Value  The syntax is the same as for the noNamespaceSchemaLocation attribute that may occur in an instance document: e.g."file_name.xsd". 
Value Type  XMLCh*  


DOM Programming Guide
 
Java and C++ DOM comparisons
 

The C++ DOM API is very similar in design and use, to the Java DOM API bindings. As a consequence, conversion of existing Java code that makes use of the DOM to C++ is a straight forward process.

This section outlines the differences between Java and C++ bindings.


Accessing the API from application code
 
// C++
#include <dom/DOM.hpp>
// Java
import org.w3c.dom.*

The header file <dom/DOM.hpp> includes all the individual headers for the DOM API classes.


Class Names
 

The C++ class names are prefixed with "DOM_". The intent is to prevent conflicts between DOM class names and other names that may already be in use by an application or other libraries that a DOM based application must link with.

The use of C++ namespaces would also have solved this conflict problem, but for the fact that many compilers do not yet support them.

DOM_Document   myDocument;   // C++
DOM_Node       aNode;
DOM_Text       someText;
Document       myDocument;   // Java
Node           aNode;
Text           someText;

If you wish to use the Java class names in C++, then you need to typedef them in C++. This is not advisable for the general case - conflicts really do occur - but can be very useful when converting a body of existing Java code to C++.

typedef DOM_Document  Document;
typedef DOM_Node      Node;

Document   myDocument;        // Now C++ usage is
                              // indistinguishable from Java
Node       aNode;

Objects and Memory Management
 

The C++ DOM implementation uses automatic memory management, implemented using reference counting. As a result, the C++ code for most DOM operations is very similar to the equivalent Java code, right down to the use of factory methods in the DOM document class for nearly all object creation, and the lack of any explicit object deletion.

Consider the following code snippets

// This is C++
DOM_Node       aNode;
aNode = someDocument.createElement("ElementName");
DOM_Node docRootNode = someDoc.getDocumentElement();
docRootNode.AppendChild(aNode);
// This is Java
Node       aNode;
aNode = someDocument.createElement("ElementName");
Node docRootNode = someDoc.getDocumentElement();
docRootNode.AppendChild(aNode);

The Java and the C++ are identical on the surface, except for the class names, and this similarity remains true for most DOM code.

However, Java and C++ handle objects in somewhat different ways, making it important to understand a little bit of what is going on beneath the surface.

In Java, the variable aNode is an object reference , essentially a pointer. It is initially == null, and references an object only after the assignment statement in the second line of the code.

In C++ the variable aNode is, from the C++ language's perspective, an actual live object. It is constructed when the first line of the code executes, and DOM_Node::operator = () executes at the second line. The C++ class DOM_Node essentially a form of a smart-pointer; it implements much of the behavior of a Java Object Reference variable, and delegates the DOM behaviors to an implementation class that lives behind the scenes.

Key points to remember when using the C++ DOM classes:

  • Create them as local variables, or as member variables of some other class. Never "new" a DOM object into the heap or make an ordinary C pointer variable to one, as this will greatly confuse the automatic memory management.
  • The "real" DOM objects - nodes, attributes, CData sections, whatever, do live on the heap, are created with the create... methods on class DOM_Document. DOM_Node and the other DOM classes serve as reference variables to the underlying heap objects.
  • The visible DOM classes may be freely copied (assigned), passed as parameters to functions, or returned by value from functions.
  • Memory management of the underlying DOM heap objects is automatic, implemented by means of reference counting. So long as some part of a document can be reached, directly or indirectly, via reference variables that are still alive in the application program, the corresponding document data will stay alive in the heap. When all possible paths of access have been closed off (all of the application's DOM objects have gone out of scope) the heap data itself will be automatically deleted.
  • There are restrictions on the ability to subclass the DOM classes.

DOMString
 

Class DOMString provides the mechanism for passing string data to and from the DOM API. DOMString is not intended to be a completely general string class, but rather to meet the specific needs of the DOM API.

The design derives from two primary sources: from the DOM's CharacterData interface and from class java.lang.string.

Main features are:

  • It stores Unicode text.
  • Automatic memory management, using reference counting.
  • DOMStrings are mutable - characters can be inserted, deleted or appended.

When a string is passed into a method of the DOM, when setting the value of a Node, for example, the string is cloned so that any subsequent alteration or reuse of the string by the application will not alter the document contents. Similarly, when strings from the document are returned to an application via the DOM API, the string is cloned so that the document can not be inadvertently altered by subsequent edits to the string.

NoteThe ICU classes are a more general solution to UNICODE character handling for C++ applications. ICU is an Open Source Unicode library, available at the IBM DeveloperWorks website.

Equality Testing
 

The DOMString equality operators (and all of the rest of the DOM class conventions) are modeled after the Java equivalents. The equals() method compares the content of the string, while the == operator checks whether the string reference variables (the application program variables) refer to the same underlying string in memory. This is also true of DOM_Node, DOM_Element, etc., in that operator == tells whether the variables in the application are referring to the same actual node or not. It's all very Java-like

  • bool operator == () is true if the DOMString variables refer to the same underlying storage.
  • bool equals() is true if the strings contain the same characters.

Here is an example of how the equality operators work:

DOMString a = "Hello";
DOMString b = a;
DOMString c = a.clone();
if (b == a)           //  This is true
if (a == c)           //  This is false
if (a.equals(c))       //  This is true
b = b + " World";
if (b == a)           // Still true, and the string's
                      //    value is "Hello World"
if (a.equals(c))      // false.  a is "Hello World";
                      //    c is still "Hello".

Downcasting
 

Application code sometimes must cast an object reference from DOM_Node to one of the classes deriving from DOM_Node, DOM_Element, for example. The syntax for doing this in C++ is different from that in Java.

// This is C++
DOM_Node       aNode = someFunctionReturningNode();
DOM_Element    el = (DOM_Element &) aNode;
// This is Java
Node       aNode = someFunctionReturningNode();
Element    el = (Element) aNode;

The C++ cast is not type-safe; the Java cast is checked for compatible types at runtime. If necessary, a type-check can be made in C++ using the node type information:

// This is C++

DOM_Node       aNode = someFunctionReturningNode();
DOM_Element    el;    // by default, el will == null.

if (anode.getNodeType() == DOM_Node::ELEMENT_NODE)
   el = (DOM_Element &) aNode;
else
   // aNode does not refer to an element.
   // Do something to recover here.

Subclassing
 

The C++ DOM classes, DOM_Node, DOM_Attr, DOM_Document, etc., are not designed to be subclassed by an application program.

As an alternative, the DOM_Node class provides a User Data field for use by applications as a hook for extending nodes by referencing additional data or objects. See the API description for DOM_Node for details.



Experimental IDOM Programming Guide
 

The experimental IDOM API is a new design of the C++ DOM API. Please note that this experimental IDOM API is only a prototype and is subject to change.

Constructing a parser
 

In order to use Xerces-C++ to parse XML files using IDOM, you will need to create an instance of the IDOMParser class. The example below shows the code you need in order to create an instance of the IDOMParser.

int main (int argc, char* args[]) {

    try {
        XMLPlatformUtils::Initialize();
    }
    catch (const XMLException& toCatch) {
        cout << "Error during initialization! :\n"
             << DOMString(toCatch.getMessage()) << "\n";
        return 1;
    }

    char* xmlFile = "x1.xml";
    IDOMParser* parser = new IDOMParser();
    parser->setValidationScheme(IDOMParser::Val_Always);    // optional.
    parser->setDoNamespaces(true);    // optional

    ErrorHandler* errHandler = (ErrorHandler*) new HandlerBase();
    parser->setErrorHandler(errHandler);

    try {
        parser->parse(xmlFile);
    }
    catch (const XMLException& toCatch) {
        cout << "Exception message is: \n"
             << DOMString(toCatch.getMessage()) << "\n" ;
        return -1;
    }
    catch (const SAXParseException& toCatch) {
        cout << "Exception message is: \n"
             << DOMString(toCatch.getMessage()) << "\n" ;
        return -1;
    }
    catch (...) {
        cout << "Unexpected Exception \n" ;
        return -1;
    }

    return 0;
}
      

Comparision of C++ DOM and IDOM
 

This section outlines the differences between the C++ DOM and IDOM APIs.


Motivation behind new design
 

The performance of the C++ DOM has not been as good as it might be, especially for use in server style applications. The DOM's reference counted automatic memory management has been the biggest time consumer. The situation becomes worse when running multi-threaded applications.

The experimental C++ IDOM is a new alternative to the C++ DOM, and aims at meeting the following requirements:

  • Reduced memory footprint.
  • Fast.
  • Good scalability on multiprocessor systems.
  • More C++ like and less Java like.

Class Names
 

The IDOM class names are prefixed with "IDOM_". The intent is to prevent conflicts between IDOM class names and DOM class names that may already be in use by an application or other libraries that a DOM based application must link with.

IDOM_Document*   myDocument;   // IDOM
IDOM_Node*       aNode;
IDOM_Text*       someText;
      
DOM_Document     myDocument;   // DOM
DOM_Node         aNode;
DOM_Text         someText;
      

Objects Management
 

Applications would use normal C++ pointers to directly access the implementation objects for Nodes in IDOM C++, while they would use object references in DOM C++.

Consider the following code snippets

// IDOM C++
IDOM_Node*       aNode;
IDOM_Node* docRootNode;
aNode = someDocument->createElement("ElementName");
docRootNode = someDocument->getDocumentElement();
docRootNode->appendChild(aNode);
      
// DOM C++
DOM_Node       aNode;
DOM_Node docRootNode;
aNode = someDocument.createElement("ElementName");
docRootNode = someDocument.getDocumentElement();
docRootNode.appendChild(aNode);
      

Memory Management
 

The C++ IDOM implementation no longer uses reference counting for automatic memory management. The C++ IDOM uses an independent storage allocator per document. The storage for a DOM document is associated with the document node object. The advantage here is that allocation would require no synchronization in most cases (based on the the same threading model that we have now - one thread active per document, but any number of documents running in parallel with separate threads).

The allocator does not support a delete operation at all - all allocated memory would persist for the life of the document, and then the larger blocks would be returned to the system without separately deleting all of the individual nodes and strings within the document.

The C++ DOM and IDOM are similar in the use of factory methods in the document class for all object creation. They differ in the object deletion mechanism.

In C++ DOM, there is no explicit object deletion. The deallocation of memory is automatically taken care of by the reference counting.

In C++ IDOM, there is an implict and explict object deletion.


Implicit Object Deletion
 

When parsing a document using an IDOMParser, all memory allocated for a DOM tree is associated to the DOM document. And this storage will be automatically deleted when the parser instance is deleted (implicit).

If you do multiple parse using the same IDOMParser instance, then multiple DOM documents will be generated and saved in a vector pool. All these documents (and thus all the allocated memory) won't be deleted until the parser instance is destroyed. If you want to release the memory back to the system but don't want to destroy the IDOMParser instance at this moment, then you can call the method IDOMParser::resetDocumentPool to reset the document vector pool, provided that you do not need access to these documents anymore.

Consider the following code snippets:

   // C++ IDOM - implicit deletion
   IDOMParser* parser = new IDOMParser();
   parser->parse(xmlFile)
   IDOM_Document *doc = parser->getDocument();

   unsigned int i = 1000;
   while (i > 0) {
      parser->parse(xmlFile)
      IDOM_Document* myDoc = parser->getDocument();
      i--;
   }

   // all allocated memory associated with these 1001 DOM documents
   // will be deleted implicitly when the parser instance is destroyed
   delete parser;
         
   // C++ IDOM - implicit deletion
   // optionally release the memory
   IDOMParser* parser = new IDOMParser();
   unsigned int i = 1000;
   while (i > 0) {
      parser->parse(xmlFile)
      IDOM_Document *doc = parser->getDocument();
      i--;
   }

   // instead of waiting until the parser instance is destroyed,
   // user can optionally choose to release the memory back to the system
   // if does not need access to these 1000 parsed documents anymore.
   parser->resetDocumentPool();

   // now the parser has some fresh memory to work on for the following
   // big loop
   i = 1000;
   while (i > 0) {
      parser->parse(xmlFile)
      IDOM_Document *doc = parser->getDocument();
      i--;
   }
   delete parser;

         

Explicit Object Deletion
 

If user is manually building a DOM tree in memory using the document factory methods, then the user needs to explicilty delete the document object to free all the allocated memory. It normally falls under the following 3 scenarios:

  • If a user is manually creating a DOM document using the document implementation factory methods, IDOM_DOMImplementation::getImplementation()->createDocument, then the user needs to explicilty delete the document object to free all allocated memory.
  • If a user is creating a DocumentType object using the document implementation factory method, IDOM_DOMImplementation::getImplementation()->createDocumentType, then the user also needs to explicilty delete the document type object to free the allocated memory.
  • Special case: If a user is creating a DocumentType using the document implementation factory method, and clone the node WITHOUT assigning a document owner to that documentType object, then the cloned node also needs to be explicitly deleted.

Consider the following code snippets:

// C++ IDOM - explicit deletion
// use the document implementation factory method to create a document type and a document
IDOM_DocumentType* myDocType;
IDOM_Document*   myDocument;
IDOM_Node*       root;
IDOM_Node*       aNode;

myDocType  = IDOM_DOMImplementation::getImplementation()->createDocumentType(name, 0, 0);
myDocument = IDOM_DOMImplementation::getImplementation()->createDocument(0, name, myDocType);
root       = myDocument->getDocumentElement();
aNode      = myDocument->createElement(anElementname);

root->appendChild(aNode);

// need to delete both myDocType and myDocument which are created through DOM Implementation
delete myDocType;
delete myDocument;
      
// C++ IDOM - explicit deletion
// use the document implementation factory method to create a document
IDOM_DocumentType* myDocType;
IDOM_Document*   myDocument;
IDOM_Node*       root;
IDOM_Node*       aNode;

myDocument = IDOM_DOMImplementation::getImplementation()->createDocument();
myDocType  = myDocument->createDocumentType(name);
root       = myDocument->createElement(name);
aNode      = myDocument->createElement(anElementname);

myDocument->appendChild(myDocType);
myDocument->appendChild(root);
root->appendChild(aNode);

// the myDocType is created through myDocument, not through Document Implementation
// thus no need to delete myDocType
delete myDocument;
      
// C++ IDOM - explicit deletion
// manually build a DOM document
// clone the document type object which does not have an owner yet
IDOM_DocumentType* myDocType1;
IDOM_DocumentType* myDocType;
IDOM_Document*   myDocument;
IDOM_Node*       root;
IDOM_Node*       aNode;

myDocType  = IDOM_DOMImplementation::getImplementation()->createDocumentType(name, 0, 0);
myDocType1 = (IDOM_DocumentType*) myDocType->cloneNode(false);
myDocument = IDOM_DOMImplementation::getImplementation()->createDocument(0, name, myDocType);

root       = myDocument->getDocumentElement();
aNode      = myDocument->createElement(anElementname);

root->appendChild(aNode);

// myDocType does not have an owner yet when myDocType1 was cloned.
// thus need to explicitly delete myDocType1
delete myDocType1;
delete myDocType;
delete myDocument;
      
// C++ IDOM - explicit deletion
// manually build a DOM document
// clone the document type object that has an owner already
//   thus no need to delete the cloned object
IDOM_DocumentType* myDocType1;
IDOM_DocumentType* myDocType;
IDOM_Document*   myDocument;
IDOM_Node*       root;
IDOM_Node*       aNode;

myDocType  = IDOM_DOMImplementation::getImplementation()->createDocumentType(name, 0, 0);
myDocument = IDOM_DOMImplementation::getImplementation()->createDocument(0, name, myDocType);
myDocType1 = (IDOM_DocumentType*) myDocType->cloneNode(false);

root       = myDocument->getDocumentElement();
aNode      = myDocument->createElement(anElementname);

root->appendChild(aNode);

// myDocType already has myDocument as the owner when myDocType1 was cloned
// thus NO need to explicitly delete myDocType1
delete myDocType;
delete myDocument;
      

Key points to remember when using the C++ IDOM classes:

  • The DOM objects are accessed via C++ pointers.
  • The DOM objects - nodes, attributes, CData sections, etc., are created with the factory methods (create...) in the document class.
  • If you are manually building a DOM tree in memory, you need to explicitly delete the document object. Memory management will be automatically taken care of by the IDOM parser when parsing an instance document.
DOMString vs. XMLCh
 

The IDOM C++ no longer uses DOMString to pass string data to and from the DOM API. Instead, the IDOM C++ uses plain, null-terminated (XMLCh *) utf-16 strings. The (XMLCh*) utf-16 type string is much simpler with lower overhead. All the string data would remain in memory until the document object is deleted.

//C++ IDOM
const XMLCh* nodeValue = aNode->getNodeValue();
    
//C++ DOM
DOMString    nodeValue = aNode.getNodeValue();
    



Copyright © 2001 The Apache Software Foundation. All Rights Reserved.