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

Home

Readme
Release Info

Installation
Download
Build

FAQs
Samples
API Docs

DOM C++ Binding
Programming
Migration Guide

Feedback
Bug-Reporting
PDF Document

CVS Repository
Mail Archive

API Docs for SAX and DOM
 

Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

DOMBuilder Class Reference

DOMBuilder provides an API for parsing XML documents and building the corresponding DOM document tree. More...

List of all members.

Public Types

Public Constants
enum  ActionType { ACTION_REPLACE = 1, ACTION_APPEND_AS_CHILDREN = 2, ACTION_INSERT_AFTER = 3, ACTION_INSERT_BEFORE = 4 }
 Action types for use in parseWithContext. More...


Public Methods

Destructor
virtual ~DOMBuilder ()
 Destructor. More...

Functions introduced in DOM Level 3
virtual DOMErrorHandlergetErrorHandler ()=0
 Get a pointer to the error handler. More...

virtual const DOMErrorHandlergetErrorHandler () const=0
 Get a const pointer to the error handler. More...

virtual DOMEntityResolvergetEntityResolver ()=0
 Get a pointer to the entity resolver. More...

virtual const DOMEntityResolvergetEntityResolver () const=0
 Get a const pointer to the entity resolver. More...

virtual DOMBuilderFilter * getFilter ()=0
 Get a pointer to the application filter. More...

virtual const DOMBuilderFilter * getFilter () const=0
 Get a const pointer to the application filter. More...

virtual void setErrorHandler (DOMErrorHandler *const handler)=0
 Set the error handler. More...

virtual void setEntityResolver (DOMEntityResolver *const handler)=0
 Set the entity resolver. More...

virtual void setFilter (DOMBuilderFilter *const filter)=0
 Set the application filter. More...

virtual void setFeature (const XMLCh *const name, const bool state)=0
 Set the state of a feature. More...

virtual bool getFeature (const XMLCh *const name) const=0
 Look up the value of a feature. More...

virtual bool canSetFeature (const XMLCh *const name, const bool state) const=0
 Query whether setting a feature to a specific value is supported. More...

virtual DOMDocumentparse (const DOMInputSource &source)=0
 Parse via an input source object. More...

virtual DOMDocumentparseURI (const XMLCh *const systemId)=0
 Parse via a file path or URL. More...

virtual DOMDocumentparseURI (const char *const systemId)=0
 Parse via a file path or URL (in the local code page). More...

virtual void parseWithContext (const DOMInputSource &source, DOMNode *const contextNode, const short action)=0
 Parse via an input source object. More...

Non-standard Extension
virtual void * getProperty (const XMLCh *const name) const=0
 Query the current value of a property in a DOMBuilder. More...

virtual void setProperty (const XMLCh *const name, void *value)=0
 Set the value of any property in a DOMBuilder. More...

virtual void release ()=0
 Called to indicate that this DOMBuilder is no longer in use and that the implementation may relinquish any resources associated with it. More...

virtual void resetDocumentPool ()=0
 Reset the documents vector pool and release all the associated memory back to the system. More...

virtual GrammarloadGrammar (const DOMInputSource &source, const short grammarType, const bool toCache=false)=0
 Preparse schema grammar (XML Schema, DTD, etc.) via an input source object. More...

virtual GrammarloadGrammar (const XMLCh *const systemId, const short grammarType, const bool toCache=false)=0
 Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL. More...

virtual GrammarloadGrammar (const char *const systemId, const short grammarType, const bool toCache=false)=0
 Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL. More...

virtual GrammargetGrammar (const XMLCh *const nameSpaceKey) const=0
 Retrieve the grammar that is associated with the specified namespace key. More...

virtual GrammargetRootGrammar () const=0
 Retrieve the grammar where the root element is declared. More...

virtual const XMLCh * getURIText (unsigned int uriId) const=0
 Returns the string corresponding to a URI id from the URI string pool. More...

virtual void resetCachedGrammarPool ()=0
 Clear the cached grammar pool. More...

virtual unsigned int getSrcOffset () const=0
 Returns the current src offset within the input source. More...


Protected Methods

Hidden constructors
 DOMBuilder ()


Detailed Description

DOMBuilder provides an API for parsing XML documents and building the corresponding DOM document tree.

A DOMBuilder instance is obtained from the DOMImplementationLS interface by invoking its createDOMBuilder method. This implementation also allows the applications to install an error and an entity handler (useful extensions to the DOM specification).

Since:
DOM Level 3


Member Enumeration Documentation

enum DOMBuilder::ActionType
 

Action types for use in parseWithContext.

ACTION_REPLACE: Replace the context node with the result of parsing the input source. For this action to work the context node must be an DOMElement, DOMText, DOMCDATASection, DOMComment, DOMProcessingInstruction, or DOMEntityReference node.

ACTION_APPEND: Append the result of parsing the input source to the context node. For this action to work, the context node must be an DOMElement.

ACTION_INSERT_AFTER: Insert the result of parsing the input source after the context node. For this action to work the context nodes parent must be an DOMElement.

ACTION_INSERT_BEFORE: Insert the result of parsing the input source before the context node. For this action to work the context nodes parent must be an DOMElement.

See also:
parseWithContext(...)
Since:
DOM Level 3
Enumeration values:
ACTION_REPLACE 
ACTION_APPEND_AS_CHILDREN 
ACTION_INSERT_AFTER 
ACTION_INSERT_BEFORE 


Constructor & Destructor Documentation

DOMBuilder::DOMBuilder   [protected]
 

virtual DOMBuilder::~DOMBuilder   [virtual]
 

Destructor.


Member Function Documentation

virtual bool DOMBuilder::canSetFeature const XMLCh *const    name,
const bool    state
const [pure virtual]
 

Query whether setting a feature to a specific value is supported.

"Experimental - subject to change"

Parameters:
name  The feature name.
state  The requested state of the feature (true or false).
Returns:
true if the feature could be successfully set to the specified value, or false if the feature is not recognized or the requested value is not supported. The value of the feature itself is not changed.
See also:
getFeature , setFeature
Since:
DOM Level 3

virtual const DOMEntityResolver* DOMBuilder::getEntityResolver   const [pure virtual]
 

Get a const pointer to the entity resolver.

This method returns the installed entity resolver. If no resolver has been installed, then it will be a zero pointer.

"Experimental - subject to change"

Returns:
A const pointer to the installed entity resolver object.
Since:
DOM Level 3

virtual DOMEntityResolver* DOMBuilder::getEntityResolver   [pure virtual]
 

Get a pointer to the entity resolver.

This method returns the installed entity resolver. If no resolver has been installed, then it will be a zero pointer.

"Experimental - subject to change"

Returns:
The pointer to the installed entity resolver object.
Since:
DOM Level 3

virtual const DOMErrorHandler* DOMBuilder::getErrorHandler   const [pure virtual]
 

Get a const pointer to the error handler.

This method returns the installed error handler. If no handler has been installed, then it will be a zero pointer.

"Experimental - subject to change"

Returns:
A const pointer to the installed error handler object.
Since:
DOM Level 3

virtual DOMErrorHandler* DOMBuilder::getErrorHandler   [pure virtual]
 

Get a pointer to the error handler.

This method returns the installed error handler. If no handler has been installed, then it will be a zero pointer.

"Experimental - subject to change"

Returns:
The pointer to the installed error handler object.
Since:
DOM Level 3

virtual bool DOMBuilder::getFeature const XMLCh *const    name const [pure virtual]
 

Look up the value of a feature.

"Experimental - subject to change"

Parameters:
name  The feature name.
Returns:
The current state of the feature (true or false)
Exceptions:
DOMException  NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize the feature name.
See also:
getFeature , canSetFeature
Since:
DOM Level 3

virtual const DOMBuilderFilter* DOMBuilder::getFilter   const [pure virtual]
 

Get a const pointer to the application filter.

This method returns the installed application filter. If no filter has been installed, then it will be a zero pointer.

"Experimental - subject to change"

Returns:
A const pointer to the installed application filter
Since:
DOM Level 3

virtual DOMBuilderFilter* DOMBuilder::getFilter   [pure virtual]
 

Get a pointer to the application filter.

This method returns the installed application filter. If no filter has been installed, then it will be a zero pointer.

"Experimental - subject to change"

Returns:
The pointer to the installed application filter.
Since:
DOM Level 3

virtual Grammar* DOMBuilder::getGrammar const XMLCh *const    nameSpaceKey const [pure virtual]
 

Retrieve the grammar that is associated with the specified namespace key.

Parameters:
nameSpaceKey  Namespace key
Returns:
Grammar associated with the Namespace key.

virtual void* DOMBuilder::getProperty const XMLCh *const    name const [pure virtual]
 

Query the current value of a property in a DOMBuilder.

The builder owns the returned pointer. The memory allocated for the returned pointer will be destroyed when the builder is deleted.

To ensure assessiblity of the returned information after the builder is deleted, callers need to copy and store the returned information somewhere else; otherwise you may get unexpected result. Since the returned pointer is a generic void pointer, see http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties to learn exactly what type of property value each property returns for replication.

Parameters:
name  The unique identifier (URI) of the property being set.
Returns:
The current value of the property. The pointer spans the same life-time as the parser. A null pointer is returned if nothing was specified externally.
Exceptions:
DOMException 
NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize the requested property.

virtual Grammar* DOMBuilder::getRootGrammar   const [pure virtual]
 

Retrieve the grammar where the root element is declared.

Returns:
Grammar where root element declared

virtual unsigned int DOMBuilder::getSrcOffset   const [pure virtual]
 

Returns the current src offset within the input source.

Returns:
offset within the input source

virtual const XMLCh* DOMBuilder::getURIText unsigned int    uriId const [pure virtual]
 

Returns the string corresponding to a URI id from the URI string pool.

Parameters:
uriId  id of the string in the URI string pool.
Returns:
URI string corresponding to the URI id.

virtual Grammar* DOMBuilder::loadGrammar const char *const    systemId,
const short    grammarType,
const bool    toCache = false
[pure virtual]
 

Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL.

This method invokes the preparsing process on a schema grammar XML file specified by the file path parameter. If the 'toCache' flag is enabled, the parser will cache the grammars for re-use. If a grammar key is found in the pool, no caching of any grammar will take place.

"Experimental - subject to change"

Parameters:
systemId  A const char pointer to a native string which contains the path to the XML grammar file to be preparsed.
grammarType  The grammar type (Schema or DTD).
toCache  If true, we cache the preparsed grammar, otherwise, no chaching. Default is false.
Returns:
The preparsed schema grammar object (SchemaGrammar or DTDGrammar). That grammar object is owned by the parser.
Exceptions:
SAXException  Any SAX exception, possibly wrapping another exception.
XMLException  An exception from the parser or client handler code.
DOMException  A DOM exception as per DOM spec.

virtual Grammar* DOMBuilder::loadGrammar const XMLCh *const    systemId,
const short    grammarType,
const bool    toCache = false
[pure virtual]
 

Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL.

This method invokes the preparsing process on a schema grammar XML file specified by the file path parameter. If the 'toCache' flag is enabled, the parser will cache the grammars for re-use. If a grammar key is found in the pool, no caching of any grammar will take place.

"Experimental - subject to change"

Parameters:
systemId  A const XMLCh pointer to the Unicode string which contains the path to the XML grammar file to be preparsed.
grammarType  The grammar type (Schema or DTD).
toCache  If true, we cache the preparsed grammar, otherwise, no chaching. Default is false.
Returns:
The preparsed schema grammar object (SchemaGrammar or DTDGrammar). That grammar object is owned by the parser.
Exceptions:
SAXException  Any SAX exception, possibly wrapping another exception.
XMLException  An exception from the parser or client handler code.
DOMException  A DOM exception as per DOM spec.

virtual Grammar* DOMBuilder::loadGrammar const DOMInputSource   source,
const short    grammarType,
const bool    toCache = false
[pure virtual]
 

Preparse schema grammar (XML Schema, DTD, etc.) via an input source object.

This method invokes the preparsing process on a schema grammar XML file specified by the DOMInputSource parameter. If the 'toCache' flag is enabled, the parser will cache the grammars for re-use. If a grammar key is found in the pool, no caching of any grammar will take place.

"Experimental - subject to change"

Parameters:
source  A const reference to the DOMInputSource object which points to the schema grammar file to be preparsed.
grammarType  The grammar type (Schema or DTD).
toCache  If true, we cache the preparsed grammar, otherwise, no chaching. Default is false.
Returns:
The preparsed schema grammar object (SchemaGrammar or DTDGrammar). That grammar object is owned by the parser.
Exceptions:
SAXException  Any SAX exception, possibly wrapping another exception.
XMLException  An exception from the parser or client handler code.
DOMException  A DOM exception as per DOM spec.
See also:
DOMInputSource::DOMInputSource

virtual DOMDocument* DOMBuilder::parse const DOMInputSource   source [pure virtual]
 

Parse via an input source object.

This method invokes the parsing process on the XML file specified by the DOMInputSource parameter. This API is borrowed from the SAX Parser interface.

The parser owns the returned DOMDocument. It will be deleted when the parser is released.

"Experimental - subject to change"

Parameters:
source  A const reference to the DOMInputSource object which points to the XML file to be parsed.
Returns:
If the DOMBuilder is a synchronous DOMBuilder the newly created and populated DOMDocument is returned. If the DOMBuilder is asynchronous then null is returned since the document object is not yet parsed when this method returns.
Exceptions:
SAXException  Any SAX exception, possibly wrapping another exception.
XMLException  An exception from the parser or client handler code.
DOMException  A DOM exception as per DOM spec.
See also:
DOMInputSource::DOMInputSource , setEntityResolver , setErrorHandler , resetDocumentPool
Since:
DOM Level 3

virtual DOMDocument* DOMBuilder::parseURI const char *const    systemId [pure virtual]
 

Parse via a file path or URL (in the local code page).

This method invokes the parsing process on the XML file specified by the native char* string parameter 'systemId'.

The parser owns the returned DOMDocument. It will be deleted when the parser is released.

"Experimental - subject to change"

Parameters:
systemId  A const char pointer to a native string which contains the path to the XML file to be parsed.
Returns:
If the DOMBuilder is a synchronous DOMBuilder the newly created and populated DOMDocument is returned. If the DOMBuilder is asynchronous then null is returned since the document object is not yet parsed when this method returns.
Exceptions:
SAXException  Any SAX exception, possibly wrapping another exception.
XMLException  An exception from the parser or client handler code.
DOMException  A DOM exception as per DOM spec.
See also:
parse(DOMInputSource,...) , resetDocumentPool

virtual DOMDocument* DOMBuilder::parseURI const XMLCh *const    systemId [pure virtual]
 

Parse via a file path or URL.

This method invokes the parsing process on the XML file specified by the Unicode string parameter 'systemId'.

The parser owns the returned DOMDocument. It will be deleted when the parser is released.

"Experimental - subject to change"

Parameters:
systemId  A const XMLCh pointer to the Unicode string which contains the path to the XML file to be parsed.
Returns:
If the DOMBuilder is a synchronous DOMBuilder the newly created and populated DOMDocument is returned. If the DOMBuilder is asynchronous then null is returned since the document object is not yet parsed when this method returns.
Exceptions:
SAXException  Any SAX exception, possibly wrapping another exception.
XMLException  An exception from the parser or client handler code.
DOMException  A DOM exception as per DOM spec.
See also:
parse(DOMInputSource,...) , resetDocumentPool
Since:
DOM Level 3

virtual void DOMBuilder::parseWithContext const DOMInputSource   source,
DOMNode *const    contextNode,
const short    action
[pure virtual]
 

Parse via an input source object.

This method invokes the parsing process on the XML file specified by the DOMInputSource parameter, and inserts the content into an existing document at the position specified with the contextNode and action arguments. When parsing the input stream the context node is used for resolving unbound namespace prefixes.

"Experimental - subject to change"

Parameters:
source  A const reference to the DOMInputSource object which points to the XML file to be parsed.
contextNode  The node that is used as the context for the data that is being parsed. This node must be a Document node, a DocumentFragment node, or a node of a type that is allowed as a child of an element, e.g. it can not be an attribute node.
action  This parameter describes which action should be taken between the new set of node being inserted and the existing children of the context node.
Exceptions:
DOMException  NOT_SUPPORTED_ERR: Raised when the DOMBuilder doesn't support this method.
NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is readonly.
Since:
DOM Level 3

virtual void DOMBuilder::release   [pure virtual]
 

Called to indicate that this DOMBuilder is no longer in use and that the implementation may relinquish any resources associated with it.

Access to a released object will lead to unexpected result.

virtual void DOMBuilder::resetCachedGrammarPool   [pure virtual]
 

Clear the cached grammar pool.

virtual void DOMBuilder::resetDocumentPool   [pure virtual]
 

Reset the documents vector pool and release all the associated memory back to the system.

When parsing a document using a DOM parser, all memory allocated for a DOM tree is associated to the DOM document.

If you do multiple parse using the same DOM parser 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 don't need these DOM documents anymore and don't want to destroy the DOM parser instance at this moment, then you can call this method to reset the document vector pool and release all the allocated memory back to the system.

It is an error to call this method if you are in the middle of a parse (e.g. in the mid of a progressive parse).

Exceptions:
IOException  An exception from the parser if this function is called when a parse is in progress.

virtual void DOMBuilder::setEntityResolver DOMEntityResolver *const    handler [pure virtual]
 

Set the entity resolver.

This method allows applications to install their own entity resolver. By installing an entity resolver, the applications can trap and potentially redirect references to external entities.

Any previously set resolver is merely dropped, since the parser does not own them.

"Experimental - subject to change"

Parameters:
handler  A const pointer to the user supplied entity resolver.
See also:
getEntityResolver
Since:
DOM Level 3

virtual void DOMBuilder::setErrorHandler DOMErrorHandler *const    handler [pure virtual]
 

Set the error handler.

This method allows applications to install their own error handler to trap error and warning messages.

Any previously set handler is merely dropped, since the parser does not own them.

"Experimental - subject to change"

Parameters:
handler  A const pointer to the user supplied error handler.
See also:
getErrorHandler
Since:
DOM Level 3

virtual void DOMBuilder::setFeature const XMLCh *const    name,
const bool    state
[pure virtual]
 

Set the state of a feature.

It is possible for a DOMBuilder to recognize a feature name but to be unable to set its value.

"Experimental - subject to change"

See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderFeatures for the list of supported features.

Parameters:
name  The feature name.
state  The requested state of the feature (true or false).
Exceptions:
DOMException  NOT_SUPPORTED_ERR: Raised when the DOMBuilder recognizes the feature name but cannot set the requested value.
NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize the feature name.
See also:
setFeature , canSetFeature
Since:
DOM Level 3

virtual void DOMBuilder::setFilter DOMBuilderFilter *const    filter [pure virtual]
 

Set the application filter.

When the application provides a filter, the parser will call out to the filter at the completion of the construction of each Element node. The filter implementation can choose to remove the element from the document being constructed (unless the element is the document element) or to terminate the parse early. If the document is being validated when it's loaded the validation happens before the filter is called.

Any previously set filter is merely dropped, since the parser does not own them.

"Experimental - subject to change"

Parameters:
filter  A const pointer to the user supplied application filter.
See also:
getFilter
Since:
DOM Level 3

virtual void DOMBuilder::setProperty const XMLCh *const    name,
void *    value
[pure virtual]
 

Set the value of any property in a DOMBuilder.

See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties for the list of supported properties.

It takes a void pointer as the property value. Application is required to initialize this void pointer to a correct type. See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties 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.

Parameters:
name  The unique identifier (URI) of the property being set.
value  The requested value for the property. See http://xml.apache.org/xerces-c/program-dom.html#DOMBuilderProperties 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.
Exceptions:
DOMException 
NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize the requested property.


The documentation for this class was generated from the following file:


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