class DOMParser : public XMLDocumentHandler, public XMLErrorReporter, public XMLEntityHandler

This class implements the Document Object Model (DOM) interface

Inheritance:



Inherited from XMLDocumentHandler:

Public

Destructor

The document handler interface

virtual void docCharacters( const XMLCh* const chars, const unsigned int length, const bool cdataSection )
Receive notification of character data
virtual void docComment( const XMLCh* const comment )
Receive notification of comments in the XML content being parsed
virtual void docPI( const XMLCh* const target, const XMLCh* const data )
Receive notification of PI's parsed in the XML content
virtual void endDocument()
Receive notification after the scanner has parsed the end of the document
virtual void endElement( const XMLElementDecl& elemDecl, const unsigned int uriId, const bool isRoot )
Receive notification of the end of an element
virtual void endEntityReference( const XMLEntityDecl& entDecl )
Receive notification when a referenced entity's content ends This method is called when scanner encounters the end of an entity reference
virtual void ignorableWhitespace( const XMLCh* const chars, const unsigned int length, const bool cdataSection )
Receive notification of ignorable whitespace in element content
virtual void resetDocument()
Reset the document handler's state, if required This method is used to give the registered document handler a chance to reset itself
virtual void startDocument()
Receive notification of the start of a new document This method is the first callback called the scanner at the start of every parse
virtual void startElement( const XMLElementDecl& elemDecl, const unsigned int uriId, const XMLCh* const prefixName, const RefVectorOf<XMLAttr>& attrList, const unsigned int attrCount, const bool isEmpty, const bool isRoot )
Receive notification of a new start tag This method is called when scanner encounters the start of an element tag
virtual void startEntityReference(const XMLEntityDecl& entDecl)
Receive notification when the scanner hits an entity reference
virtual void XMLDecl( const XMLCh* const versionStr, const XMLCh* const encodingStr, const XMLCh* const standaloneStr, const XMLCh* const autoEncodingStr )
Receive notification of an XML declaration Currently neither DOM nor SAX provide API's to return back this information

Inherited from XMLErrorReporter:

Public Methods

virtual void error( const unsigned int errCode, const XMLCh* const errDomain, const ErrTypes type, const XMLCh* const errorText, const XMLCh* const systemId, const XMLCh* const publicId, const unsigned int lineNum, const unsigned int colNum )
virtual void resetErrors()

Public

protected Constructor

XMLErrorReporter()
Default constructor

Error Handler interface


Inherited from XMLEntityHandler:

Public

The pure virtual methods in this interface.

virtual void endInputSource(const InputSource& inputSource)
This method get called after the scanner has finished reading from the given input source while processing external entity references
virtual bool expandSystemId( const XMLCh* const systemId, XMLBuffer& toFill )
This method allows the passes the scanned systemId to the entity handler, thereby giving it a chance to provide any customized handling like resolving relative path names
virtual void resetEntities()
This method allows the entity handler to reset itself, so that it can be used again
virtual InputSource* resolveEntity( const XMLCh* const publicId, const XMLCh* const systemId )
This method allows the entity handler to provide customized application specific entity resolution
virtual void startInputSource(const InputSource& inputSource)
This method will be called before the scanner starts reading from an input source while processing external entity references

Documentation

This class implements the Document Object Model (DOM) interface. It should be used by applications which choose to parse and process the XML document using the DOM api's. This implementation also allows the applications to install an error and an entitty handler (useful extensions to the DOM specification).

It can be used to instantiate a validating or non-validating parser, by setting a member flag.

DOMParser(XMLValidator* const valToAdopt = 0)
Constructor with an instance of validator class to use for validation
Parameters:
valToAdopt - Pointer to the validator instance to use. The parser is responsible for freeing the memory.

~DOMParser()
Destructor

DOM_Document getDocument()
This method returns the DOM_Document object representing the root of the document tree. This object provides the primary access to the document's data.
Returns:
The DOM_Document object which represents the entire XML document.

ErrorHandler* getErrorHandler()
This method returns the installed error handler. Suitable for 'lvalue' usages.
Returns:
The pointer to the installed error handler object.

const ErrorHandler* getErrorHandler() const
This method returns the installed error handler. Suitable for 'rvalue' usages.
Returns:
A const pointer to the installed error handler object.

EntityResolver* getEntityResolver()
This method returns the installed entity resolver. Suitable for 'lvalue' usages.
Returns:
The pointer to the installed entity resolver object.

const EntityResolver* getEntityResolver() const
This method returns the installed entity resolver. Suitable for 'rvalue' usages.
Returns:
A const pointer to the installed entity resolver object.

const XMLScanner& getScanner() const
This method returns a reference to the underlying scanner object. It allows read only access to data maintained in the scanner.
Returns:
A const reference to the underlying scanner object.

const XMLValidator& getValidator() const
This method returns a reference to the parser's installed validator.
Returns:
A const reference to the installed validator object.

bool getDoNamespaces() const
This method returns the state of the parser's namespace handling capability.
Returns:
true, if the parser is currently configured to understand namespaces, false otherwise.
See Also:
setDoNamespaces

bool getDoValidation() const
This method returns the state of the parser's validation handling flag which controls whether validation checks are enforced or not.
Returns:
true, if the parser is currently configured to do validation, false otherwise.
See Also:
setDoValidation

bool getExitOnFirstFatalError() const
This method returns the state of the parser's exit-on-First-Fatal-Error flag.
Returns:
true, if the parser is currently configured to exit on the first fatal error, false otherwise.
See Also:
setExitOnFirstFatalError

bool getExpandEntityReferences() const
This method returns the state of the parser's expand entity references flag.
Returns:
'true' if the expand entity reference flag is set on the parser, 'false' otherwise.
See Also:
setExpandEntityReferences

void setErrorHandler(ErrorHandler* const handler)
This method allows applications to install their own error handler to trap error and warning messages.
Parameters:
handler - A const pointer to the user supplied error handler.
See Also:
getErrorHandler

void setEntityResolver(EntityResolver* const handler)
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.
Parameters:
handler - A const pointer to the user supplied entity resolver.
See Also:
getEntityResolver

void setDoNamespaces(const bool newState)
This method allows users to enable or disable the parser's namespace processing. When set to true, parser starts enforcing all the constraints / rules specified by the NameSpace specification.

The parser's default state is: false.

This flag is ignored by the underlying scanner if the installed validator indicates that namespace constraints should be enforced.

Parameters:
newState - The value specifying whether NameSpace rules should be enforced or not.
See Also:
getDoNamespaces

void setDoValidation(const bool newState)
This method allows users to enable or disable the parser's validation checks.

By default, the parser does not to any validation. The default value is false.

Parameters:
newState - The value specifying whether the parser should do validity checks or not against the DTD in the input XML document.
See Also:
getDoValidation

void setExitOnFirstFatalError(const bool newState)
This method allows users to set the parser's behaviour when it encounters the first fatal error. If set to true, the parser will exit at the first fatal error. If false, then it will report the error and continue processing.

The default value is 'true' and the parser exits on the first fatal error.

Parameters:
newState - The value specifying whether the parser should continue or exit when it encounters the first fatal error.
See Also:
getExitOnFirstFatalError

void setExpandEntityReferences(const bool expand)
This method allows the user to specify whether the parser should expand all entity reference nodes. When the 'do expansion' flag is true, the DOM tree does not have any entity reference nodes. Is is replaced by the sub-tree representing the replacement text of the entity. When the 'do expansion' flag is false, the DOM tree contains an extra entity reference node, whose children is the sub tree of the replacement text.
Parameters:
expand - The new state of the expand entity reference flag.

void parse(const InputSource& source, const bool reuseValidator = false)
This method invokes the parsing process on the XML file specified by the InputSource parameter. This API is borrowed from the SAX Parser interface.
Parameters:
source - A const reference to the InputSource object which points to the XML file to be parsed.
reuseValidator - The flag indicating whether the existing validator should be reused or not for this parsing run.
See Also:
parse(InputSource)

void parse(const XMLCh* const systemId, const bool reuseValidator = false)
This method invokes the parsing process on the XML file specified by the Unicode string parameter 'systemId'. This method is borrowed from the SAX Parser interface.
Parameters:
systemId - A const XMLCh pointer to the Unicode string which contains the path to the XML file to be parsed.
reuseValidator - The flag indicating whether the existing validator should be reused or not for this parsing run.
See Also:
parse(XMLCh*)

void parse(const char* const systemId, const bool reuseValidator = false)
This method invokes the parsing process on the XML file specified by the native char* string parameter 'systemId'.
Parameters:
systemId - A const char pointer to a native string which contains the path to the XML file to be parsed.
reuseValidator - The flag indicating whether the existing validator should be reused or not for this parsing run.

bool parseFirst( const XMLCh* const systemId, XMLPScanToken& toFill, const bool reuseValidator = false )

This method is used to start a progressive parse on a XML file. To continue parsing, subsequent calls must be to the parseNext method.

It scans through the prolog and returns a token to be used on subsequent scanNext() calls. If the return value is true, then the token is legal and ready for further use. If it returns false, then the scan of the prolog failed and the token is not going to work on subsequent scanNext() calls.

Returns:
'true', if successful in parsing the prolog. It indicates the user can go ahead with parsing the rest of the file. It returns 'false' to indicate that the parser could not find a proper prolog definition.
Parameters:
systemId - A pointer to a Unicode string represting the path to the XML file to be parsed.
toFill - A token maintaing state information to maintain internal consistency between invocation of 'parseNext' calls.
reuseValidator - The flag indicating whether the existing validator should be reused or not for this parsing process.
See Also:
parseNext
parseFirst(char*,...)
parseFirst(InputSource&,...)

bool parseFirst( const char* const systemId, XMLPScanToken& toFill, const bool reuseValidator = false )

This method is used to start a progressive parse on a XML file. To continue parsing, subsequent calls must be to the parseNext method.

It scans through the prolog and returns a token to be used on subsequent scanNext() calls. If the return value is true, then the token is legal and ready for further use. If it returns false, then the scan of the prolog failed and the token is not going to work on subsequent scanNext() calls.

Returns:
'true', if successful in parsing the prolog. It indicates the user can go ahead with parsing the rest of the file. It returns 'false' to indicate that the parser could not find a proper prolog definition.
Parameters:
systemId - A pointer to a regular native string represting the path to the XML file to be parsed.
toFill - A token maintaing state information to maintain internal consistency between invocation of 'parseNext' calls.
reuseValidator - The flag indicating whether the existing validator should be reused or not for this parsing run.
See Also:
parseNext
parseFirst(XMLCh*,...)
parseFirst(InputSource&,...)

bool parseFirst( const InputSource& source, XMLPScanToken& toFill, const bool reuseValidator = false )

This method is used to start a progressive parse on a XML file. To continue parsing, subsequent calls must be to the parseNext method.

It scans through the prolog and returns a token to be used on subsequent scanNext() calls. If the return value is true, then the token is legal and ready for further use. If it returns false, then the scan of the prolog failed and the token is not going to work on subsequent scanNext() calls.

Returns:
'true', if successful in parsing the prolog. It indicates the user can go ahead with parsing the rest of the file. It returns 'false' to indicate that the parser could not find a proper prolog definition.
Parameters:
source - A const reference to the InputSource object which points to the XML file to be parsed.
toFill - A token maintaing state information to maintain internal consistency between invocation of 'parseNext' calls.
reuseValidator - The flag indicating whether the existing validator should be reused or not for this parsing process.
See Also:
parseNext
parseFirst(XMLCh*,...)
parseFirst(char*,...)

bool parseNext(XMLPScanToken& token)

This method is used to continue with progressive parsing of XML files started by a call to 'parseFirst' method.

It parses the XML file and stops as soon as it comes across a XML token (as defined in the XML specification).

Returns:
'true', if successful in parsing the next XML token. It indicates the user can go ahead with parsing the rest of the file. It returns 'false' to indicate that the parser could not find next token as per the XML specification production rule.
Parameters:
token - A token maintaing state information to maintain internal consistency between invocation of 'parseNext' calls.
See Also:
parseFirst(XMLCh*,...)
parseFirst(char*,...)
parseFirst(InputSource&,...)

virtual void error( const unsigned int errCode, const XMLCh* const msgDomain, const XMLErrorReporter::ErrTypes errType, const XMLCh* const errorText, const XMLCh* const systemId, const XMLCh* const publicId, const unsigned int lineNum, const unsigned int colNum )
This method is used to report back errors found while parsing the XML file. This method is also borrowed from the SAX specification. It calls the corresponding user installed Error Handler method: 'fatal', 'error', 'warning' depending on the severity of the error. This classification is defined by the XML specification.
Parameters:
errCode - An integer code for the error.
msgDomain - A const pointer to an Unicode string representing the message domain to use.
errType - An enumeration classifying the severity of the error.
errorText - A const pointer to an Unicode string representing the text of the error message.
systemId - A const pointer to an Unicode string representing the system id of the XML file where this error was discovered.
publicId - A const pointer to an Unicode string representing the public id of the XML file where this error was discovered.
lineNum - The line number where the error occurred.
colNum - The column number where the error occurred.
See Also:
ErrorHandler

virtual void resetErrors()
This method allows the user installed Error Handler callback to 'reset' itself. This method is a no-op for this DOM implementation.

virtual void endInputSource(const InputSource& inputSource)
This method is used to indicate the end of parsing of an external entity file. This method is a no-op for this DOM implementation.
Parameters:
inputSource - A const reference to the InputSource object which points to the XML file being parsed.
See Also:
InputSource

virtual bool expandSystemId( const XMLCh* const systemId, XMLBuffer& toFill )
This method allows an installed XMLEntityHandler to further process any system id's of enternal entities encountered in the XML file being parsed, such as redirection etc. This method always returns 'false' for this DOM implementation.
Returns:
'true', if any processing is done, 'false' otherwise.
Parameters:
systemId - A const pointer to an Unicode string representing the system id scanned by the parser.
toFill - A pointer to a buffer in which the application processed system id is stored.

virtual void resetEntities()
This method allows the installed XMLEntityHandler to reset itself. This method is a no-op for this DOM implementation.

virtual InputSource* resolveEntity( const XMLCh* const publicId, const XMLCh* const systemId )
This method allows a user installed entity handler to further process any pointers to external entities. The applications can implement 'redirection' via this callback. This method is also borrowed from the SAX specification.
Returns:
The value returned by the user installed resolveEntity method or NULL otherwise to indicate no processing was done.
Parameters:
publicId - A const pointer to a Unicode string representing the public id of the entity just parsed.
systemId - A const pointer to a Unicode string representing the system id of the entity just parsed.
See Also:
EntityResolver

virtual void startInputSource(const InputSource& inputSource)
This method is used to indicate the start of parsing an external entity file. This method is a no-op for this SAX driver implementation.
Parameters:
inputSource - A const reference to the InputSource object which points to the external entity being parsed.

virtual void docCharacters( const XMLCh* const chars, const unsigned int length, const bool cdataSection )
This method is used to report all the characters scanned by the parser. This DOM implementation stores this data in the appropriate DOM node, creating one if necessary.
Parameters:
chars - A const pointer to a Unicode string representing the character data.
length - The length of the Unicode string returned in 'chars'.
cdataSection - A flag indicating if the characters represent content from the CDATA section.

virtual void docComment( const XMLCh* const comment )
This method is used to report any comments scanned by the parser. A new comment node is created which stores this data.
Parameters:
comment - A const pointer to a null terminated Unicode string representing the comment text.

virtual void docPI( const XMLCh* const target, const XMLCh* const data )
This method is used to report any PI scanned by the parser. A new PI node is created and appended as a child of the current node in the tree.
Parameters:
target - A const pointer to a Unicode string representing the target of the PI declaration.
data - A const pointer to a Unicode string representing the data of the PI declaration. See the PI production rule in the XML specification for details.

virtual void endDocument()
This method is used to indicate the end of root element was just scanned by the parser

virtual void endElement( const XMLElementDecl& elemDecl, const unsigned int urlId, const bool isRoot )
This method is used to indicate the end tag of an element.
Parameters:
elemDecl - A const reference to the object containing element declaration information.
urlId - An id referring to the namespace prefix, if namespaces setting is switched on.
isRoot - A flag indicating whether this element was the root element.

virtual void endEntityReference( const XMLEntityDecl& entDecl )
This method is used to indicate that an end of an entity reference was just scanned.
Parameters:
entDecl - A const reference to the object containing the entity declaration information.

virtual void ignorableWhitespace( const XMLCh* const chars, const unsigned int length, const bool cdataSection )
This method is used to report all the whitespace characters, which are determined to be 'ignorable'. This distinction between characters is only made, if validation is enabled.

Any whitespace before content is ignored. If the current node is already of type DOM_Node::TEXT_NODE, then these whitespaces are appended, otherwise a new Text node is created which stores this data. Essentially all ignoreable characters are collected in one node.

Parameters:
chars - A const pointer to a Unicode string representing the ignorable whitespace character data.
length - The length of the Unicode string 'chars'.
cdataSection - A flag indicating if the characters represent content from the CDATA section.

virtual void resetDocument()
This method allows the user installed Document Handler to 'reset' itself, freeing all the memory resources. The scanner calls this method before starting a new parse event.

virtual void startDocument()
This method is used to report the start of the parsing process

virtual void startElement( const XMLElementDecl& elemDecl, const unsigned int urlId, const XMLCh* const elemPrefix, const RefVectorOf<XMLAttr>& attrList, const unsigned int attrCount, const bool isEmpty, const bool isRoot )
This method is used to report the start of an element. It is called at the end of the element, by which time all attributes specified are also parsed. A new DOM Element node is created along with as many attribute nodes as required. This new element is added appended as a child of the current node in the tree.
Parameters:
elemDecl - A const reference to the object containing element declaration information.
urlId - An id referring to the namespace prefix, if namespaces setting is switched on.
elemPrefix - A const pointer to a Unicode string containing the namespace prefix for this element. Applicable only when namespace processing is enabled.
attrList - A const reference to the object containing the list of attributes just scanned for this element.
attrCount - A count of number of attributes in the list specified by the parameter 'attrList'.
isEmpty - A flag indicating whether this is an empty element or not.
isRoot - A flag indicating whether this element was the root element.
See Also:
startElement

virtual void startEntityReference( const XMLEntityDecl& entDecl )
This method is used to indicate the start of an entity reference. If the expand entity reference flag is true, then a new DOM Entity reference node is created.
Parameters:
entDecl - A const reference to the object containing the entity declaration information.

virtual void XMLDecl( const XMLCh* const versionStr, const XMLCh* const encodingStr, const XMLCh* const standaloneStr, const XMLCh* const actualEncStr )
This method is used to report the XML decl scanned by the parser. Refer to the XML specification to see the meaning of parameters. This method is a no-op for this DOM implementation.
Parameters:
versionStr - A const pointer to a Unicode string representing version string value.
encodingStr - A const pointer to a Unicode string representing the encoding string value.
standaloneStr - A const pointer to a Unicode string representing the standalone string value.
actualEncodingStr - A const pointer to a Unicode string representing the actual encoding string value.

DOM_Node getCurrentNode()

void setCurrentNode(DOM_Node toSet)
This method sets the current node maintained inside the parser to the one specified.
Parameters:
toSet - The DOM node which will be the current node.

void setDocument(DOM_Document toSet)
This method sets the DOM Document node to the one specified.
Parameters:
toSet - The new DOM Document node for this XML document.


This class has no child classes.

alphabetic index hierarchy of classes


Xerces-C XML Parser for C++ Version 1.1
Copyright © 2000 The Apache Software Foundation. All Rights Reserved.

generated by doc++