Newer
Older
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="DOM Programming Guide">
<anchor name="Objectives"/>
<s2 title="Design Objectives">
<p>The C++ DOM implementation is based on the
<jump href="ApacheDOMC++Binding.html">Apache Recommended DOM C++ binding</jump>.</p>
<p>The design objective aims at meeting the following requirements:
</p>
<ul>
<li>Reduced memory footprint.</li>
<li>Fast - especially for use in server style and multi-threaded applications.</li>
<li>Good scalability on multiprocessor systems.</li>
<li>More C++ like and less Java like.</li>
</ul>
</s2>
<anchor name="DOM3"/>
<s2 title="DOM Level 3 Support in &XercesCName;">
<p>The &XercesCName; &XercesCVersion; contains a partial implementation of the W3C
Document Object Model Level 3. This implementation is experimental. See the document
<jump href="dom3.html"> DOM Level 3 Support</jump> for details.
</p>
</s2>
<anchor name="UsingDOMAPI"/>
<s2 title="Using DOM API">
<anchor name="AccessAPI"/>
<s3 title="Accessing API from application code">
<source>
#include <xercesc/dom/DOM.hpp></source>
<p>The header file <dom/DOM.hpp> includes all the
individual headers for the DOM API classes. </p>
</s3>
<anchor name="DOMClassNames"/>
<s3 title="Class Names">
<p>
The DOM class names are prefixed with "DOM" (if not already), e.g. "DOMNode". 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.</p>
<source>
DOMDocument* myDocument;
DOMNode* aNode;
DOMText* someText;
</source>
</s3>
<anchor name="DOMObjMgmt"/>
<s3 title="Objects Management">
<p>Applications would use normal C++ pointers to directly access the
implementation objects for Nodes in C++ DOM.
</p>
<p>Consider the following code snippets</p>
<source>
DOMNode* aNode;
DOMNode* docRootNode;
aNode = someDocument->createElement(anElementName);
docRootNode = someDocument->getDocumentElement();
docRootNode->appendChild(aNode);
</source>
</s3>
<anchor name="DOMMemMgmt"/>
<s3 title="Memory Management">
<p>The C++ DOM implementation provides a release() method for releasing any "orphaned"
resources that were created through createXXXX factory method.
Memory for any returned object are owned by implementation. Please see
<jump href="ApacheDOMC++Binding.html#release"> Apache Recommended DOM C++ binding</jump>
for details.</p>
<s4 title="Objects created by DOMImplementation::createXXXX">
<p>Users <em>must</em> call the release() function when finished using any objects that
were created by the DOMImplementation::createXXXX (e.g. DOMBuilder, DOMWriter, DOMDocument,
DOMDocumentType).</p>
<p>Acesss to a released object will lead to unexpected behaviour.</p>
<note>When a DOMDocument is released, all its associated children AND any objects it owned
(e.g. DOMRange, DOMTreeWalker, DOMNodeIterator or any orphaned nodes) will also be released.
</note>
Tinny Ng
committed
<note>When a DOMDocumentType has been inserted into a DOMDocument and thus has a owner,
it will then be released automatically when its owner document is released.
</note>
</s4>
<s4 title="Objects created by DOMDocument::createXXXX">
<p>Users <em>can</em> call the release() function to indicate the release of any orphaned nodes.
When an orphaned Node is released, its associated children will also be released.
Acesss to a released Node will lead to unexpected behaviour. These orphaned Nodes will
eventually be released, if not already done so, when its owner document is released</p>
Tinny Ng
committed
<note>DOMException::INVALID_ACCESS_ERR will be raised if releasing a Node that has a parent
(has a owner).</note>
</s4>
<s4 title="Objects created by DOMDocumentRange::createRange or DOMDocumentTraversal::createXXXX">
<p>Users <em>can</em> call release() function when finished using the DOMRange,
DOMNodeIterator, DOMTreeWalker.
Acesss to a released object will lead to unexpected behaviour. These objects will
Tinny Ng
committed
eventually be released, if not already done so, when its owner document is released
</p>
</s4>
<p>Here is an example</p>
<source>
//
// Create a small document tree
//
{
XMLCh* tempStr[100];
XMLString::transcode("Range", tempStr, 99);
DOMImplementation* impl = DOMImplementationRegistry::getDOMImplementation(tempStr, 0);
XMLString::transcode("root", tempStr, 99);
DOMDocument* doc = impl->createDocument(0, tempStr, 0);
DOMElement* root = doc->getDocumentElement();
XMLString::transcode("FirstElement", tempStr, 99);
DOMElement* e1 = doc->createElement(tempStr);
root->appendChild(e1);
XMLString::transcode("SecondElement", tempStr, 99);
DOMElement* e2 = doc->createElement(tempStr);
root->appendChild(e2);
XMLString::transcode("aTextNode", tempStr, 99);
DOMText* textNode = doc->createTextNode(tempStr);
e1->appendChild(textNode);
// optionally, call release() to release the resource associated with the range after done
DOMRange* range = doc->createRange();
range->release();
// removedElement is an orphaned node, optionally call release() to release associated resource
DOMElement* removedElement = root->removeChild(e2);
removedElement->release();
// no need to release this returned object which is owned by implementation
XMLString::transcode("*", tempStr, 99);
DOMNodeList* nodeList = doc->getElementsByTagName(tempStr);
// done with the document, must call release() to release the entire document resources
doc->release();
</source>
</s3>
<anchor name="XMLCh"/>
<s3 title="String Type">
<p>The C++ DOM uses the plain, null-terminated (XMLCh *) utf-16 strings
as the String type. The (XMLCh*) utf-16 type string has low overhead.
All the string data would remain in memory until the document object is released.</p>
<source>
//C++ DOM
const XMLCh* nodeValue = aNode->getNodeValue();
</source>
</s3>
</s2>
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
<anchor name="XercesDOMParser"/>
<s2 title="XercesDOMParser">
<anchor name="ConstructXercesDOMParser"/>
<s3 title="Constructing a XercesDOMParser">
<p>In order to use &XercesCName; to parse XML files using DOM, you
can create an instance of the XercesDOMParser class. The example
below shows the code you need in order to create an instance of the
XercesDOMParser.</p>
<source>
#include <xercesc/parsers/XercesDOMParser.hpp>
#include <xercesc/dom/DOM.hpp>
#include <xercesc/sax/HandlerBase.hpp>
#include <xercesc/util/XMLString.hpp>
int main (int argc, char* args[]) {
try {
XMLPlatformUtils::Initialize();
}
catch (const XMLException& toCatch) {
char* message = XMLString::transcode(toCatch.getMessage());
cout << "Error during initialization! :\n"
<< message << "\n";
delete [] message;
return 1;
}
XercesDOMParser* parser = new XercesDOMParser();
parser->setValidationScheme(XercesDOMParser::Val_Always); // optional.
parser->setDoNamespaces(true); // optional
ErrorHandler* errHandler = (ErrorHandler*) new HandlerBase();
parser->setErrorHandler(errHandler);
char* xmlFile = "x1.xml";
try {
parser->parse(xmlFile);
}
catch (const XMLException& toCatch) {
char* message = XMLString::transcode(toCatch.getMessage());
cout << "Exception message is: \n"
<< message << "\n";
delete [] message;
return -1;
}
catch (const DOMException& toCatch) {
char* message = XMLString::transcode(toCatch.getMessage());
cout << "Exception message is: \n"
<< message << "\n";
delete [] message;
return -1;
}
catch (...) {
cout << "Unexpected Exception \n" ;
return -1;
}
delete parser;
delete errHandler;
return 0;
</source>
</s3>
<anchor name="XercesDOMFeatures"/>
<s3 title="XercesDOMParser Supported Features">
<p>The behavior of the XercesDOMParser is dependant on the values of the following features. All
of the features below are set using the "setter" methods (e.g. <code>setDoNamespaces</code>),
and are queried using the corresponding "getter" methods (e.g. <code>getDoNamespaces</code>).
The following only gives you a quick summary of supported features. Please
refer to <jump href="api.html">API Documentataion</jump> for complete detail.
</p>
<anchor name="createEntityRef"/>
<table>
<tr><th colspan="2"><em>void setCreateEntityReferenceNodes(const bool)</em></th></tr>
<tr><th><em>true:</em></th><td> Create EntityReference nodes in the DOM tree. The
EntityReference nodes and their child nodes will be read-only. </td></tr>
<tr><th><em>false:</em></th><td> Do not create EntityReference nodes in the DOM tree. No
EntityReference nodes will be created, only the nodes corresponding to their fully
expanded sustitution text will be created. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>note:</em></th><td> This feature only affects the appearance of
EntityReference nodes in the DOM tree. The document will always contain the entity
reference child nodes. </td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>void setExpandEntityReferences(const bool)</em> (deprecated) <br/>
please use <link anchor="createEntityRef">setCreateEntityReferenceNodes</link> </th></tr>
<tr><th><em>true:</em></th><td> Do not create EntityReference nodes in the DOM tree. No
EntityReference nodes will be created, only the nodes corresponding to their fully
expanded sustitution text will be created. </td></tr>
<tr><th><em>false:</em></th><td> Create EntityReference nodes in the DOM tree. The
EntityReference nodes and their child nodes will be read-only. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="createEntityRef">setCreateEntityReferenceNodes</link>
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>void setIncludeIgnorableWhitespace(const bool)</em></th></tr>
<tr><th><em>true:</em></th><td> Include text nodes that can be considered "ignorable
<tr><th><em>false:</em></th><td> Do not include ignorable whitespace in the DOM tree. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>note:</em></th><td> The only way that the parser can determine if text is
ignorable is by reading the associated grammar and having a content model for the
document. When ignorable whitespace text nodes are included in the DOM tree,
they will be flagged as ignorable; and the method DOMText::isIgnorableWhitespace()
will return true for those text nodes. </td></tr>
</table>
<p/>
<anchor name="namespaces"/>
<table>
<tr><th colspan="2"><em>void setDoNamespaces(const bool)</em></th></tr>
<tr><th><em>true:</em></th><td> Perform Namespace processing </td></tr>
<tr><th><em>false:</em></th><td> Do not perform Namespace processing</td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> If the validation scheme is set to Val_Always or Val_Auto, then the
document must contain a grammar that supports the use of namespaces </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="validation-dynamic">setValidationScheme</link>
</td></tr>
</table>
<p/>
<anchor name="validation"/>
<table>
<tr><th colspan="2"><em>void setDoValidation(const bool)</em> (deprecated) <br/>
please use <link anchor="validation-dynamic">setValidationScheme</link>
</th></tr>
<tr><th><em>true:</em></th><td> Report all validation errors. </td></tr>
<tr><th><em>false:</em></th><td> Do not report validation errors. </td></tr>
<tr><th><em>default:</em></th><td> see the default of
<link anchor="validation-dynamic">setValidationScheme</link>
</td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="validation-dynamic">setValidationScheme</link>
</td></tr>
</table>
<p/>
<anchor name="validation-dynamic"/>
<table>
<tr><th colspan="2"><em>void setValidationScheme(const ValSchemes)</em></th></tr>
<tr><th><em>Val_Auto:</em></th><td> The parser will report validation errors only if a grammar is specified.</td></tr>
<tr><th><em>Val_Always:</em></th><td> The parser will always report validation errors. </td></tr>
<tr><th><em>Val_Never:</em></th><td> Do not report validation errors. </td></tr>
<tr><th><em>default:</em></th><td> Val_Auto </td></tr>
<tr><th><em>note:</em></th><td> If set to Val_Always, the document must
specify a grammar. If this feature is set to Val_Never and document specifies a grammar,
that grammar might be parsed but no validation of the document contents will be
performed. </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="load-external-dtd">setLoadExternalDTD</link>
</td></tr>
</table>
<p/>
<anchor name="schema"/>
<table>
<tr><th colspan="2"><em>void setDoSchema(const bool)</em></th></tr>
<tr><th><em>true:</em></th><td> Enable the parser's schema support. </td></tr>
<tr><th><em>false:</em></th><td> Disable the parser's schema support. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note</em></th><td> If set to true, namespace processing must also be turned on. </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="namespaces">setDoNamespaces</link>
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>void setValidationSchemaFullChecking(const bool)</em></th></tr>
<tr><th><em>true:</em></th><td> Enable full schema constraint checking, including checking
which may be time-consuming or memory intensive. Currently, particle unique
attribution constraint checking and particle derivation restriction checking
are controlled by this option. </td></tr>
<tr><th><em>false:</em></th><td> Disable full schema constraint checking . </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> This feature checks the Schema grammar itself for
additional errors that are time-consuming or memory intensive. It does <em>not</em> affect the
level of checking performed on document instances that use Schema grammars.</td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="schema">setDoSchema</link>
</td></tr>
</table>
<p/>
<anchor name="load-external-dtd"/>
<table>
<tr><th colspan="2"><em>void setLoadExternalDTD(const bool)</em></th></tr>
<tr><th><em>true:</em></th><td> Load the External DTD . </td></tr>
<tr><th><em>false:</em></th><td> Ignore the external DTD completely. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>note</em></th><td> This feature is ignored and DTD is always loaded
if the validation scheme is set to Val_Always or Val_Auto. </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="validation-dynamic">setValidationScheme</link>
</td></tr>
</table>
<p/>
<anchor name="continue-after-fatal"/>
<table>
<tr><th colspan="2"><em>void setExitOnFirstFatalError(const bool)</em></th></tr>
<tr><th><em>true:</em></th><td> Stops parse on first fatal error. </td></tr>
<tr><th><em>false:</em></th><td> Attempt to continue parsing after a fatal error. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>note:</em></th><td> The behavior of the parser when this feature is set to
false is <em>undetermined</em>! Therefore use this feature with extreme caution because
the parser may get stuck in an infinite loop or worse.</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>void setValidationConstraintFatal(const bool)</em></th></tr>
<tr><th><em>true:</em></th><td> The parser will treat validation error as fatal and will
exit depends on the state of
<link anchor="continue-after-fatal">setExitOnFirstFatalError</link>
</td></tr>
<tr><th><em>false:</em></th><td> The parser will report the error and continue processing. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> Setting this true does not mean the validation error will
be printed with the word "Fatal Error". It is still printed as "Error", but the parser
will exit if
<link anchor="continue-after-fatal">setExitOnFirstFatalError</link>
is set to true.</td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="continue-after-fatal">setExitOnFirstFatalError</link>
</td></tr>
</table>
<p/>
<anchor name="use-cached"/>
<table>
<tr><th colspan="2"><em>void useCachedGrammarInParse(const bool)</em></th></tr>
<tr><th><em>true:</em></th><td>Use cached grammar if it exists in the pool.</td></tr>
<tr><th><em>false:</em></th><td>Parse the schema grammar.</td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td>The getter function for this method is called isUsingCachedGrammarInParse.</td></tr>
<tr><th><em>note:</em></th><td>If the grammar caching option is enabled, this option is set to true automatically.
Any setting to this option by the users is a no-op.</td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="cache-grammar">cacheGrammarFromParse</link>
</td></tr>
</table>
<p/>
<anchor name="cache-grammar"/>
<table>
<tr><th colspan="2"><em>void cacheGrammarFromParse(const bool)</em></th></tr>
<tr><th><em>true:</em></th><td>Cache the grammar in the pool for re-use in subsequent parses.</td></tr>
<tr><th><em>false:</em></th><td>Do not cache the grammar in the pool</td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td>The getter function for this method is called isCachingGrammarFromParse</td></tr>
<tr><th><em>note:</em></th><td> If set to true, the useCachedGrammarInParse
is also set to true automatically.</td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="use-cached">useCachedGrammarInParse</link>
</td></tr>
</table>
<p/>
</s3>
<anchor name="XercesDOMProperties"/>
<s3 title="XercesDOMParser Supported Properties">
<p>The behavior of the XercesDOMParser is dependant on the values of the following properties. All
of the properties below are set using the "setter" methods (e.g. <code>setExternalSchemaLocation</code>),
and are queried using the corresponding "getter" methods (e.g. <code>getExternalSchemaLocation</code>).
The following only gives you a quick summary of supported features. Please
refer to <jump href="api.html">API Documentataion</jump> for complete detail.
</p>
<table>
<tr><th colspan="2"><em>void setExternalSchemaLocation(const XMLCh*)</em></th></tr>
<tr><th><em>Description</em></th><td> 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).</td></tr>
<tr><th><em>Value</em></th><td> 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.</td></tr>
<tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
<tr><th colspan="2"><em>void setExternalNoNamespaceSchemaLocation(const XMLCh* const)</em></th></tr>
<tr><th><em>Description</em></th><td> 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.</td></tr>
<tr><th><em>Value</em></th><td> The syntax is the same as for the noNamespaceSchemaLocation
attribute that may occur in an instance document: e.g."file_name.xsd".</td></tr>
<tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
<anchor name="DOMBuilder"/>
<s2 title="DOMBuilder">
<anchor name="ConstructDOMBuilder"/>
<s3 title="Constructing a DOMBuilder">
<p>DOMBuilder is a new interface introduced by the
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
W3C DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>.
DOMBuilder provides the "Load" interface for parsing XML documents and building the
corresponding DOM document tree from various input sources.
</p>
<p>A DOMBuilder instance is obtained from the DOMImplementationLS interface by invoking
its createDOMBuilder method. For example:
</p>
<source>
#include <xercesc/dom/DOM.hpp>
#include <xercesc/util/XMLString.hpp>
int main (int argc, char* args[]) {
try {
XMLPlatformUtils::Initialize();
}
catch (const XMLException& toCatch) {
char* message = XMLString::transcode(toCatch.getMessage());
cout << "Error during initialization! :\n"
<< message << "\n";
delete [] message;
return 1;
}
XMLCh tempStr[100];
XMLString::transcode("LS", tempStr, 99);
DOMImplementation *impl = DOMImplementationRegistry::getDOMImplementation(tempStr);
DOMBuilder* parser = ((DOMImplementationLS*)impl)->createDOMBuilder(DOMImplementationLS::MODE_SYNCHRONOUS, 0);
// optionally you can set some features on this builder
if (parser->canSetFeature(XMLUni::fgDOMValidation, true)
parser->setFeature(XMLUni::fgDOMValidation, true);
if (parser->canSetFeature(XMLUni::fgDOMNamespaces, true)
parser->setFeature(XMLUni::fgDOMNamespaces, true);
if (parser->canSetFeature((XMLUni::fgDOMDatatypeNormalization, true)
parser->setFeature(XMLUni::fgDOMDatatypeNormalization, true);
// optionally you can implement your DOMErrorHandler (e.g. MyDOMErrorHandler)
// and set it to the builder
MyDOMErrorHandler* errHandler = new myDOMErrorHandler();
parser->setErrorHandler(errHandler);
char* xmlFile = "x1.xml";
}
catch (const XMLException& toCatch) {
char* message = XMLString::transcode(toCatch.getMessage());
cout << "Exception message is: \n"
<< message << "\n";
delete [] message;
return -1;
}
catch (const DOMException& toCatch) {
char* message = XMLString::transcode(toCatch.getMessage());
cout << "Exception message is: \n"
<< message << "\n";
delete [] message;
return -1;
}
catch (...) {
cout << "Unexpected Exception \n" ;
return -1;
}
parser->release();
</source>
<p>Please refer to the <jump href="api.html">API Documentataion</jump> and the sample
DOMCount for more detail.
</p>
</s3>
<anchor name="InputSourceWrapper"/>
<s3 title="How to interchange DOMInputSource and SAX InputSource?">
<p>DOM L3 has introduced a DOMInputSource which is similar to the SAX InputSource. The &XercesCName; internals
(XMLScanner, Reader, etc.) use the SAX InputSource to process the xml data. In order to support DOM L3, we need
to provide a mechanism to allow the &XercesCName; internals to talk to a DOMInputSource object. Similarly, &XercesCName;
provides some framework classes for specialized types of input source (i.e. LocalFileInputSource, etc.) that are
derived from the SAX InputSource. In DOM L3, to allow users implementing their own DOMEntityResolver(s), which return
a DOMInputSource, to utilize these framework classes, we need to provide a mechanism to map a SAX InputSource to a
DOMInputSource. We are introducing to wrapper classes to interchange DOMInputSource and SAXInputSource.
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
</p>
<s4 title="Wrapper4DOMInputSource">
<p>
Wraps a DOMInputSource object to a SAX InputSource.
</p>
<source>
#include <xercesc/dom/DOMInputSource.hpp>
#include <xercesc/framework/Wrapper4DOMInputSource.hpp>
class DBInputSource: public DOMInputSource
{
...
};
...
DOMInputSource *domIS = new DBInputSource;
Wrapper4DOMInputSource domISWrapper(domIS);
XercesDOMParser parser;
parser.parse(domISWrapper);
</source>
</s4>
<s4 title="Wrapper4InputSource">
<p>
Wraps a SAX InputSource object to a DOMInputSource.
</p>
<source>
#include <xercesc/framework/WrapperInputSource.hpp>
#include <xercesc/framework/LocalFileInputSource.hpp>
DOMInputSource* MyEntityResolver::resolveEntity(const XMLCh* const publicId,
const XMLCh* const systemId,
const XMLCh* const baseURI)
{
return new Wrapper4InputSource(new LocalFileInputSource(baseURI, systemId));
}
</source>
</s4>
<p>Please refer to the <jump href="api.html">API Documentataion</jump> for more detail.
</p>
</s3>
<anchor name="DOMBuilderFeatures"/>
<s3 title="DOMBuilder Supported Features">
<p>The behavior of the DOMBuilder is dependant on the values of the following features.
All of the features below can be set using the function <code>DOMBuilder::setFeature(cons XMLCh* const, const bool)</code>.
And can be queried using the function <code>bool DOMBuilder::getFeature(const XMLCh* const)</code>.
User can also call <code>DOMBuilder::canSetFeature(const XMLCh* const, const bool)</code>
to query whether setting a feature to a specific value is supported
</p>
<s4 title="DOM Features">
<table>
<tr><th colspan="2"><em>cdata-sections</em></th></tr>
<tr><th><em>true:</em></th><td> Keep CDATASection nodes in the document. </td></tr>
<tr><th><em>false:</em></th><td> Not Supported. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>note:</em></th><td> Setting this feature to false is not supported. </td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>comments</em></th></tr>
<tr><th><em>true:</em></th><td> Keep Comment nodes in the document. </td></tr>
<tr><th><em>false:</em></th><td> Discard Comment nodes in the document. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>charset-overrides-xml-encoding</em></th></tr>
<tr><th><em>true:</em></th><td> If a higher level protocol such as HTTP [IETF RFC 2616]
provides an indication of the character encoding of the input stream being processed,
that will override any encoding specified in the XML declaration or the Text declaration
(see also [XML 1.0] 4.3.3 "Character Encoding in Entities"). Explicitly setting an
encoding in the DOMInputSource overrides encodings from the protocol. </td></tr>
<tr><th><em>false:</em></th><td> Any character set encoding information from higher
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>datatype-normalization</em></th></tr>
<tr><th><em>true:</em></th><td> Let the validation process do its datatype normalization
that is defined in the used schema language. </td></tr>
<tr><th><em>false:</em></th><td> Disable datatype normalization.
The XML 1.0 attribute value normalization always occurs though. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> Note that setting this feature to true does not affect
the DTD normalization operation which always takes place, in accordance to
<jump href="http://www.w3.org/TR/2000/REC-xml-20001006">XML 1.0 (Second Edition)</jump>.
</td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2000/REC-xml-20001006">XML 1.0 (Second Edition)</jump>.
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>entities</em></th></tr>
<tr><th><em>true:</em></th><td> Create EntityReference nodes in the DOM tree. The
EntityReference nodes and their child nodes will be read-only. </td></tr>
<tr><th><em>false:</em></th><td> Do not create EntityReference nodes in the DOM tree. No
EntityReference nodes will be created, only the nodes corresponding to their fully
expanded sustitution text will be created. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>note:</em></th><td> This feature only affects the appearance of
EntityReference nodes in the DOM tree. The document will always contain the entity
reference child nodes. </td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>canonical-form</em></th></tr>
<tr><th><em>true:</em></th><td> Not Supported. </td></tr>
<tr><th><em>false:</em></th><td> Do not canonicalize the document. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> Setting this feature to true is not supported. </td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>infoset</em></th></tr>
<tr><th><em>true:</em></th><td> Not Supported. </td></tr>
<tr><th><em>false:</em></th><td> No effect. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> Setting this feature to true is not supported. </td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<anchor name="builder-namespaces"/>
<table>
<tr><th colspan="2"><em>namespaces</em></th></tr>
<tr><th><em>true:</em></th><td> Perform Namespace processing </td></tr>
<tr><th><em>false:</em></th><td> Do not perform Namespace processing</td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> If the validation is on, then the
document must contain a grammar that supports the use of namespaces </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-validation">validation</link>
</td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>namespace-declarations</em></th></tr>
<tr><th><em>true:</em></th><td> Include namespace declaration attributes,
specified or defaulted from the schema or the DTD, in the document. </td></tr>
<tr><th><em>false:</em></th><td> Not Supported. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>note:</em></th><td> Setting this feature to false is not supported. </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-namespaces">namespaces</link>
</td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>supported-mediatypes-only</em></th></tr>
<tr><th><em>true:</em></th><td> Not Supported. </td></tr>
<tr><th><em>false:</em></th><td> Don't check the media type, accept any type of data. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> Setting this feature to true is not supported. </td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<anchor name="builder-validate-if-schema"/>
<table>
<tr><th colspan="2"><em>validate-if-schema</em></th></tr>
<tr><th><em>true:</em></th><td> When validation is true, the parser will validate the document only if a grammar is specified.</td></tr>
<tr><th><em>false:</em></th><td> Validation is determined by the state of the
<link anchor="builder-validation">validation</link> feature. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-validation">validation</link>
</td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<anchor name="builder-validation"/>
<table>
<tr><th colspan="2"><em>validation</em></th></tr>
<tr><th><em>true:</em></th><td> Report all validation errors. </td></tr>
<tr><th><em>false:</em></th><td> Do not report validation errors. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> If this feature is set to true, the document must
specify a grammar. If this feature is set to false and document specifies a grammar,
that grammar might be parsed but no validation of the document contents will be
performed. </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-validate-if-schema">validate-if-schema</link>
</td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-load-external-dtd">http://apache.org/xml/features/nonvalidating/load-external-dtd</link>
</td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
<p/>
<anchor name="builder-whitespace"/>
<table>
<tr><th colspan="2"><em>whitespace-in-element-content</em></th></tr>
<tr><th><em>true:</em></th><td> Include text nodes that can be considered "ignorable
<tr><th><em>false:</em></th><td> Do not include ignorable whitespace in the DOM tree. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>note:</em></th><td> The only way that the parser can determine if text is
ignorable is by reading the associated grammar and having a content model for the
document. When ignorable whitespace text nodes are included in the DOM tree,
they will be flagged as ignorable; and the method DOMText::isIgnorableWhitespace()
will return true for those text nodes. </td></tr>
<tr><th><em>see:</em></th><td>
<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
DOM Level 3.0 Abstract Schemas and Load and Save Specification</jump>
</td></tr>
</table>
</s4>
<s4 title="Xerces Features">
<anchor name="builder-schema"/>
<table>
<tr><th colspan="2"><em>http://apache.org/xml/features/validation/schema</em></th></tr>
<tr><th><em>true:</em></th><td> Enable the parser's schema support. </td></tr>
<tr><th><em>false:</em></th><td> Disable the parser's schema support. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>note</em></th><td> If set to true, namespace processing must also be turned on. </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-namespaces">namespaces</link>
</td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>http://apache.org/xml/features/validation/schema-full-checking</em></th></tr>
<tr><th><em>true:</em></th><td> Enable full schema constraint checking, including checking
which may be time-consuming or memory intensive. Currently, particle unique
attribution constraint checking and particle derivation restriction checking
are controlled by this option. </td></tr>
<tr><th><em>false:</em></th><td> Disable full schema constraint checking. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> This feature checks the Schema grammar itself for
additional errors that are time-consuming or memory intensive. It does <em>not</em> affect the
level of checking performed on document instances that use Schema grammars. </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-schema">http://apache.org/xml/features/validation/schema</link>
</td></tr>
</table>
<p/>
<anchor name="builder-load-external-dtd"/>
<table>
<tr><th colspan="2"><em>http://apache.org/xml/features/nonvalidating/load-external-dtd</em></th></tr>
<tr><th><em>true:</em></th><td> Load the External DTD. </td></tr>
<tr><th><em>false:</em></th><td> Ignore the external DTD completely. </td></tr>
<tr><th><em>default:</em></th><td> true </td></tr>
<tr><th><em>note</em></th><td> This feature is ignored and DTD is always loaded when validation is on. </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-validation">validation</link>
</td></tr>
</table>
<p/>
<anchor name="builder-continue-after-fatal"/>
<table>
<tr><th colspan="2"><em>http://apache.org/xml/features/continue-after-fatal-error</em></th></tr>
<tr><th><em>true:</em></th><td> Attempt to continue parsing after a fatal error. </td></tr>
<tr><th><em>false:</em></th><td> Stops parse on first fatal error. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> The behavior of the parser when this feature is set to
true is <em>undetermined</em>! Therefore use this feature with extreme caution because
the parser may get stuck in an infinite loop or worse. </td></tr>
</table>
<p/>
<table>
<tr><th colspan="2"><em>http://apache.org/xml/features/validation-error-as-fatal</em></th></tr>
<tr><th><em>true:</em></th><td> The parser will treat validation error as fatal and will
exit depends on the state of
<link anchor="builder-continue-after-fatal">http://apache.org/xml/features/continue-after-fatal-error</link>.
</td></tr>
<tr><th><em>false:</em></th><td> The parser will report the error and continue processing. </td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> Setting this true does not mean the validation error will
be printed with the word "Fatal Error". It is still printed as "Error", but the parser
will exit if
<link anchor="builder-continue-after-fatal">http://apache.org/xml/features/continue-after-fatal-error</link>
is set to false. </td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-continue-after-fatal">http://apache.org/xml/features/continue-after-fatal-error</link>
</td></tr>
</table>
<p/>
<anchor name="builder-use-cached"/>
<tr><th colspan="2"><em>http://apache.org/xml/features/validation/use-cachedGrammarInParse</em></th></tr>
<tr><th><em>true:</em></th><td>Use cached grammar if it exists in the pool.</td></tr>
<tr><th><em>false:</em></th><td>Parse the schema grammar.</td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td>If http://apache.org/xml/features/validation/cache-grammarFromParse is enabled,
this feature is set to true automatically. Any setting to this feature by the users is a no-op.</td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-cache-grammar">http://apache.org/xml/features/validation/cache-grammarFromParse</link>
</td></tr>
</table>
<p/>
<anchor name="builder-cache-grammar"/>
<table>
<tr><th colspan="2"><em>http://apache.org/xml/features/validation/cache-grammarFromParse</em></th></tr>
<tr><th><em>true:</em></th><td>Cache the grammar in the pool for re-use in subsequent parses.</td></tr>
<tr><th><em>false:</em></th><td>Do not cache the grammar in the pool</td></tr>
<tr><th><em>default:</em></th><td> false </td></tr>
<tr><th><em>note:</em></th><td> If set to true, the http://apache.org/xml/features/validation/use-cachedGrammarInParse
is also set to true automatically.</td></tr>
<tr><th><em>see:</em></th><td>
<link anchor="builder-use-cached">http://apache.org/xml/features/validation/use-cachedGrammarInParse</link>
</td></tr>
<table>
<tr><th colspan="2"><em>http://apache.org/xml/features/dom/user-adopts-DOMDocument</em></th></tr>
<tr><th><em>true:</em></th><td> The caller will adopt the DOMDocument that is returned from