XercesDOMParser Class Reference

This class implements the Document Object Model (DOM) interface. More...

Inheritance diagram for XercesDOMParser:

AbstractDOMParser XMemory XMLDocumentHandler XMLErrorReporter XMLEntityHandler PSVIHandler

List of all members.

Public Member Functions

Constructors and Destructor
 XercesDOMParser (XMLValidator *const valToAdopt=0, MemoryManager *const manager=XMLPlatformUtils::fgMemoryManager, XMLGrammarPool *const gramPool=0)
 Construct a XercesDOMParser, with an optional validator.
virtual ~XercesDOMParser ()
 Destructor.
Getter methods
ErrorHandlergetErrorHandler ()
 Get a pointer to the error handler.
const ErrorHandlergetErrorHandler () const
 Get a const pointer to the error handler.
EntityResolvergetEntityResolver ()
 Get a pointer to the entity resolver.
const EntityResolvergetEntityResolver () const
 Get a const pointer to the entity resolver.
XMLEntityResolvergetXMLEntityResolver ()
 Get a pointer to the entity resolver.
const XMLEntityResolvergetXMLEntityResolver () const
 Get a const pointer to the entity resolver.
bool isCachingGrammarFromParse () const
 Get the 'Grammar caching' flag.
bool isUsingCachedGrammarInParse () const
 Get the 'Use cached grammar' flag.
Grammar * getGrammar (const XMLCh *const nameSpaceKey)
 Retrieve the grammar that is associated with the specified namespace key.
Grammar * getRootGrammar ()
 Retrieve the grammar where the root element is declared.
const XMLCh * getURIText (unsigned int uriId) const
 Returns the string corresponding to a URI id from the URI string pool.
unsigned int getSrcOffset () const
 Returns the current src offset within the input source.
bool getIgnoreCachedDTD () const
 Get the 'ignore cached DTD grammar' flag.
Setter methods
void setErrorHandler (ErrorHandler *const handler)
 Set the error handler.
void setEntityResolver (EntityResolver *const handler)
 Set the entity resolver.
void setXMLEntityResolver (XMLEntityResolver *const handler)
 Set the entity resolver.
void cacheGrammarFromParse (const bool newState)
 Set the 'Grammar caching' flag.
void useCachedGrammarInParse (const bool newState)
 Set the 'Use cached grammar' flag.
void setIgnoreCachedDTD (const bool newValue)
 Set the 'ignore cached DTD grammar' flag.
Utility methods
void resetDocumentPool ()
 Reset the documents vector pool and release all the associated memory back to the system.
Implementation of the XMLErrorReporter interface.
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 XMLSSize_t lineNum, const XMLSSize_t colNum)
 Handle errors reported from the parser.
virtual void resetErrors ()
 Reset any error data before a new parse.
Implementation of the XMLEntityHandler interface.
virtual void endInputSource (const InputSource &inputSource)
 Handle an end of input source event.
virtual bool expandSystemId (const XMLCh *const systemId, XMLBuffer &toFill)
 Expand a system id.
virtual void resetEntities ()
 Reset any entity handler information.
virtual InputSourceresolveEntity (const XMLCh *const publicId, const XMLCh *const systemId, const XMLCh *const baseURI=0)
 Resolve a public/system id.
virtual InputSourceresolveEntity (XMLResourceIdentifier *resourceIdentifier)
 Resolve a public/system id.
virtual void startInputSource (const InputSource &inputSource)
 Handle a 'start input source' event.
Implementation of Grammar preparsing interface's.
Grammar * loadGrammar (const InputSource &source, const short grammarType, const bool toCache=false)
 Preparse schema grammar (XML Schema, DTD, etc.
Grammar * loadGrammar (const XMLCh *const systemId, const short grammarType, const bool toCache=false)
 Preparse schema grammar (XML Schema, DTD, etc.
Grammar * loadGrammar (const char *const systemId, const short grammarType, const bool toCache=false)
 Preparse schema grammar (XML Schema, DTD, etc.
void resetCachedGrammarPool ()
 This method allows the user to reset the pool of cached grammars.


Detailed Description

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.


Constructor & Destructor Documentation

XercesDOMParser::XercesDOMParser ( XMLValidator *const   valToAdopt = 0,
MemoryManager *const   manager = XMLPlatformUtils::fgMemoryManager,
XMLGrammarPool *const   gramPool = 0 
)

Construct a XercesDOMParser, with an optional validator.

Constructor with an instance of validator class to use for validation. If you don't provide a validator, a default one will be created for you in the scanner.

Parameters:
gramPool Pointer to the grammar pool instance from external application. The parser does NOT own it.
valToAdopt Pointer to the validator instance to use. The parser is responsible for freeing the memory.
manager Pointer to the memory manager to be used to allocate objects.

virtual XercesDOMParser::~XercesDOMParser (  )  [virtual]

Destructor.


Member Function Documentation

ErrorHandler * XercesDOMParser::getErrorHandler (  ) 

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.

Returns:
The pointer to the installed error handler object.

const ErrorHandler * XercesDOMParser::getErrorHandler (  )  const

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.

Returns:
A const pointer to the installed error handler object.

EntityResolver * XercesDOMParser::getEntityResolver (  ) 

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.

Returns:
The pointer to the installed entity resolver object.

const EntityResolver * XercesDOMParser::getEntityResolver (  )  const

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.

Returns:
A const pointer to the installed entity resolver object.

XMLEntityResolver * XercesDOMParser::getXMLEntityResolver (  ) 

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.

Returns:
The pointer to the installed entity resolver object.

const XMLEntityResolver * XercesDOMParser::getXMLEntityResolver (  )  const

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.

Returns:
A const pointer to the installed entity resolver object.

bool XercesDOMParser::isCachingGrammarFromParse (  )  const

Get the 'Grammar caching' flag.

This method returns the state of the parser's grammar caching when parsing an XML document.

Returns:
true, if the parser is currently configured to cache grammars, false otherwise.
See also:
cacheGrammarFromParse

bool XercesDOMParser::isUsingCachedGrammarInParse (  )  const

Get the 'Use cached grammar' flag.

This method returns the state of the parser's use of cached grammar when parsing an XML document.

Returns:
true, if the parser is currently configured to use cached grammars, false otherwise.
See also:
useCachedGrammarInParse

Grammar* XercesDOMParser::getGrammar ( const XMLCh *const   nameSpaceKey  ) 

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

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

Grammar* XercesDOMParser::getRootGrammar (  ) 

Retrieve the grammar where the root element is declared.

Returns:
Grammar where root element declared

const XMLCh* XercesDOMParser::getURIText ( unsigned int  uriId  )  const

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.

unsigned int XercesDOMParser::getSrcOffset (  )  const

Returns the current src offset within the input source.

To be used only while parsing is in progress.

Returns:
offset within the input source

bool XercesDOMParser::getIgnoreCachedDTD (  )  const

Get the 'ignore cached DTD grammar' flag.

Returns:
true, if the parser is currently configured to ignore cached DTD, false otherwise.
See also:
setIgnoreCachedDTD

void XercesDOMParser::setErrorHandler ( ErrorHandler *const   handler  ) 

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.

Parameters:
handler A const pointer to the user supplied error handler.
See also:
getErrorHandler

void XercesDOMParser::setEntityResolver ( EntityResolver *const   handler  ) 

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 entity resolver is merely dropped, since the parser does not own them. If both setEntityResolver and setXMLEntityResolver are called, then the last one is used.

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

void XercesDOMParser::setXMLEntityResolver ( XMLEntityResolver *const   handler  ) 

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 entity resolver is merely dropped, since the parser does not own them. If both setEntityResolver and setXMLEntityResolver are called, then the last one set is used.

Parameters:
handler A const pointer to the user supplied entity resolver.
See also:
getXMLEntityResolver

void XercesDOMParser::cacheGrammarFromParse ( const bool  newState  ) 

Set the 'Grammar caching' flag.

This method allows users to enable or disable caching of grammar when parsing XML documents. When set to true, the parser will cache the resulting grammar for use in subsequent parses.

If the flag is set to true, the 'Use cached grammar' flag will also be set to true.

The parser's default state is: false.

Parameters:
newState The value specifying whether we should cache grammars or not.
See also:
isCachingGrammarFromParse

useCachedGrammarInParse

void XercesDOMParser::useCachedGrammarInParse ( const bool  newState  ) 

Set the 'Use cached grammar' flag.

This method allows users to enable or disable the use of cached grammars. When set to true, the parser will use the cached grammar, instead of building the grammar from scratch, to validate XML documents.

If the 'Grammar caching' flag is set to true, this mehod ignore the value passed in.

The parser's default state is: false.

Parameters:
newState The value specifying whether we should use the cached grammar or not.
See also:
isUsingCachedGrammarInParse

cacheGrammarFromParse

void XercesDOMParser::setIgnoreCachedDTD ( const bool  newValue  ) 

Set the 'ignore cached DTD grammar' flag.

This method gives users the option to ignore a cached DTD grammar, when an XML document contains both an internal and external DTD, and the use cached grammar from parse option is enabled. Currently, we do not allow using cached DTD grammar when an internal subset is present in the document. This option will only affect the behavior of the parser when an internal and external DTD both exist in a document (i.e. no effect if document has no internal subset).

The parser's default state is false

Parameters:
newValue The state to set

void XercesDOMParser::resetDocumentPool (  ) 

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 XercesDOMParser::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 XMLSSize_t  lineNum,
const XMLSSize_t  colNum 
) [virtual]

Handle errors reported from the parser.

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

Implements XMLErrorReporter.

virtual void XercesDOMParser::resetErrors (  )  [virtual]

Reset any error data before a new parse.

This method allows the user installed Error Handler callback to 'reset' itself.

This method is a no-op for this DOM implementation.

Implements XMLErrorReporter.

void XercesDOMParser::endInputSource ( const InputSource inputSource  )  [virtual]

Handle an end of input source event.

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

Implements XMLEntityHandler.

bool XercesDOMParser::expandSystemId ( const XMLCh *const   systemId,
XMLBuffer &  toFill 
) [virtual]

Expand a system id.

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.

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.
Returns:
'true', if any processing is done, 'false' otherwise.

Implements XMLEntityHandler.

void XercesDOMParser::resetEntities (  )  [virtual]

Reset any entity handler information.

This method allows the installed XMLEntityHandler to reset itself.

This method is a no-op for this DOM implementation.

Implements XMLEntityHandler.

virtual InputSource* XercesDOMParser::resolveEntity ( const XMLCh *const   publicId,
const XMLCh *const   systemId,
const XMLCh *const   baseURI = 0 
) [virtual]

Resolve a public/system id.

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.

Deprecated:
This method is no longer called (the other resolveEntity one is).
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.
baseURI A const pointer to a Unicode string representing the base URI of the entity just parsed, or null if there is no base URI.
Returns:
The value returned by the user installed resolveEntity method or NULL otherwise to indicate no processing was done. The returned InputSource is owned by the parser which is responsible to clean up the memory.
See also:
DOMEntityResolver

XMLEntityHandler

Implements XMLEntityHandler.

virtual InputSource* XercesDOMParser::resolveEntity ( XMLResourceIdentifier resourceIdentifier  )  [virtual]

Resolve a public/system id.

This method allows a user installed entity handler to further process any pointers to external entities. The applications can implement 'redirection' via this callback.

Parameters:
resourceIdentifier An object containing the type of resource to be resolved and the associated data members corresponding to this type.
Returns:
The value returned by the user installed resolveEntity method or NULL otherwise to indicate no processing was done. The returned InputSource is owned by the parser which is responsible to clean up the memory.
See also:
XMLEntityHandler

XMLEntityResolver

Implements XMLEntityHandler.

void XercesDOMParser::startInputSource ( const InputSource inputSource  )  [virtual]

Handle a 'start input source' event.

This method is used to indicate the start of parsing an external entity file.

This method is a no-op for this DOM parse implementation.

Parameters:
inputSource A const reference to the InputSource object which points to the external entity being parsed.

Implements XMLEntityHandler.

Grammar* XercesDOMParser::loadGrammar ( const InputSource source,
const short  grammarType,
const bool  toCache = false 
)

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 SAX InputSource 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 SAX InputSource 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:
InputSource::InputSource

Grammar* XercesDOMParser::loadGrammar ( const XMLCh *const   systemId,
const short  grammarType,
const bool  toCache = false 
)

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.

Grammar* XercesDOMParser::loadGrammar ( const char *const   systemId,
const short  grammarType,
const bool  toCache = false 
)

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.

void XercesDOMParser::resetCachedGrammarPool (  ) 

This method allows the user to reset the pool of cached grammars.


The documentation for this class was generated from the following file:
Generated on Thu Feb 19 11:35:45 2009 for Xerces-C++ by  doxygen 1.5.4