secureswitools/swisistools/source/xmlparser/xerces/include/xercesc/parsers/XercesDOMParser.hpp
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* $Id: XercesDOMParser.hpp 568078 2007-08-21 11:43:25Z amassari $
*
*/
#if !defined(XercesDOMParser_HPP)
#define XercesDOMParser_HPP
#include <xercesc/parsers/AbstractDOMParser.hpp>
XERCES_CPP_NAMESPACE_BEGIN
class EntityResolver;
class ErrorHandler;
class Grammar;
class XMLEntityResolver;
class XMLResourceIdentifier;
/**
* 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).
*
* <p>It can be used to instantiate a validating or non-validating
* parser, by setting a member flag.</p>
*/
class PARSERS_EXPORT XercesDOMParser : public AbstractDOMParser
{
public :
// -----------------------------------------------------------------------
// Constructors and Detructor
// -----------------------------------------------------------------------
/** @name Constructors and Destructor */
//@{
/** 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.
*
* @param gramPool Pointer to the grammar pool instance from
* external application.
* The parser does NOT own it.
*
* @param valToAdopt Pointer to the validator instance to use. The
* parser is responsible for freeing the memory.
* @param manager Pointer to the memory manager to be used to
* allocate objects.
*/
XercesDOMParser
(
XMLValidator* const valToAdopt = 0
, MemoryManager* const manager = XMLPlatformUtils::fgMemoryManager
, XMLGrammarPool* const gramPool = 0
);
/**
* Destructor
*/
virtual ~XercesDOMParser();
//@}
// -----------------------------------------------------------------------
// Getter methods
// -----------------------------------------------------------------------
/** @name Getter methods */
//@{
/** 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.
*
* @return The pointer to the installed error handler object.
*/
ErrorHandler* getErrorHandler();
/** 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.
*
* @return A const pointer to the installed error handler object.
*/
const ErrorHandler* getErrorHandler() const;
/** 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.
*
* @return The pointer to the installed entity resolver object.
*/
EntityResolver* getEntityResolver();
/** 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.
*
* @return A const pointer to the installed entity resolver object.
*/
const EntityResolver* getEntityResolver() const;
/**
* 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.
*
* @return The pointer to the installed entity resolver object.
*/
XMLEntityResolver* getXMLEntityResolver();
/**
* 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.
*
* @return A const pointer to the installed entity resolver object.
*/
const XMLEntityResolver* getXMLEntityResolver() const;
/** Get the 'Grammar caching' flag
*
* This method returns the state of the parser's grammar caching when
* parsing an XML document.
*
* @return true, if the parser is currently configured to
* cache grammars, false otherwise.
*
* @see #cacheGrammarFromParse
*/
bool isCachingGrammarFromParse() 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.
*
* @return true, if the parser is currently configured to
* use cached grammars, false otherwise.
*
* @see #useCachedGrammarInParse
*/
bool isUsingCachedGrammarInParse() const;
/**
* Retrieve the grammar that is associated with the specified namespace key
*
* @param nameSpaceKey Namespace key
* @return Grammar associated with the Namespace key.
*/
Grammar* getGrammar(const XMLCh* const nameSpaceKey);
/**
* Retrieve the grammar where the root element is declared.
*
* @return Grammar where root element declared
*/
Grammar* getRootGrammar();
/**
* Returns the string corresponding to a URI id from the URI string pool.
*
* @param uriId id of the string in the URI string pool.
* @return URI string corresponding to the URI id.
*/
const XMLCh* getURIText(unsigned int uriId) const;
/**
* Returns the current src offset within the input source.
* To be used only while parsing is in progress.
*
* @return offset within the input source
*/
unsigned int getSrcOffset() const;
/** Get the 'ignore cached DTD grammar' flag
*
* @return true, if the parser is currently configured to
* ignore cached DTD, false otherwise.
*
* @see #setIgnoreCachedDTD
*/
bool getIgnoreCachedDTD() const;
//@}
// -----------------------------------------------------------------------
// Setter methods
// -----------------------------------------------------------------------
/** @name Setter methods */
//@{
/** Set the error handler
*
* This method allows applications to install their own error handler
* to trap error and warning messages.
*
* <i>Any previously set handler is merely dropped, since the parser
* does not own them.</i>
*
* @param handler A const pointer to the user supplied error
* handler.
*
* @see #getErrorHandler
*/
void setErrorHandler(ErrorHandler* 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.
*
* <i>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.</i>
*
* @param handler A const pointer to the user supplied entity
* resolver.
*
* @see #getEntityResolver
*/
void 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.
*
* <i>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.</i>
*
* @param handler A const pointer to the user supplied entity
* resolver.
*
* @see #getXMLEntityResolver
*/
void setXMLEntityResolver(XMLEntityResolver* const handler);
/** 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.
*
* @param newState The value specifying whether we should cache grammars
* or not.
*
* @see #isCachingGrammarFromParse
* @see #useCachedGrammarInParse
*/
void cacheGrammarFromParse(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.
*
* @param newState The value specifying whether we should use the cached
* grammar or not.
*
* @see #isUsingCachedGrammarInParse
* @see #cacheGrammarFromParse
*/
void useCachedGrammarInParse(const bool newState);
/** 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
*
* @param newValue The state to set
*/
void setIgnoreCachedDTD(const bool newValue);
//@}
// -----------------------------------------------------------------------
// Utility methods
// -----------------------------------------------------------------------
/** @name Utility methods */
//@{
/** 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).
*
* @exception IOException An exception from the parser if this function
* is called when a parse is in progress.
*
*/
void resetDocumentPool();
//@}
// -----------------------------------------------------------------------
// Implementation of the XMLErrorReporter interface.
// -----------------------------------------------------------------------
/** @name Implementation of the XMLErrorReporter interface. */
//@{
/** 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.
*
* @param errCode An integer code for the error.
* @param msgDomain A const pointer to an Unicode string representing
* the message domain to use.
* @param errType An enumeration classifying the severity of the error.
* @param errorText A const pointer to an Unicode string representing
* the text of the error message.
* @param systemId A const pointer to an Unicode string representing
* the system id of the XML file where this error
* was discovered.
* @param publicId A const pointer to an Unicode string representing
* the public id of the XML file where this error
* was discovered.
* @param lineNum The line number where the error occurred.
* @param colNum The column number where the error occurred.
* @see ErrorHandler
*/
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
);
/** Reset any error data before a new parse
*
* This method allows the user installed Error Handler callback to
* 'reset' itself.
*
* <b>This method is a no-op for this DOM
* implementation.</b>
*/
virtual void resetErrors();
//@}
// -----------------------------------------------------------------------
// Implementation of the XMLEntityHandler interface.
// -----------------------------------------------------------------------
/** @name Implementation of the XMLEntityHandler interface. */
//@{
/** Handle an end of input source event
*
* This method is used to indicate the end of parsing of an external
* entity file.
*
* <b>This method is a no-op for this DOM
* implementation.</b>
*
* @param inputSource A const reference to the InputSource object
* which points to the XML file being parsed.
* @see InputSource
*/
virtual void endInputSource(const InputSource& inputSource);
/** 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.
*
* <b>This method always returns 'false'
* for this DOM implementation.</b>
*
* @param systemId A const pointer to an Unicode string representing
* the system id scanned by the parser.
* @param toFill A pointer to a buffer in which the application
* processed system id is stored.
* @return 'true', if any processing is done, 'false' otherwise.
*/
virtual bool expandSystemId
(
const XMLCh* const systemId
, XMLBuffer& toFill
);
/** Reset any entity handler information
*
* This method allows the installed XMLEntityHandler to reset
* itself.
*
* <b>This method is a no-op for this DOM
* implementation.</b>
*/
virtual void resetEntities();
/** 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).
*
* @param publicId A const pointer to a Unicode string representing the
* public id of the entity just parsed.
* @param systemId A const pointer to a Unicode string representing the
* system id of the entity just parsed.
* @param baseURI A const pointer to a Unicode string representing the
* base URI of the entity just parsed,
* or <code>null</code> if there is no base URI.
* @return 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 DOMEntityResolver
* @see XMLEntityHandler
*/
virtual InputSource* resolveEntity
(
const XMLCh* const publicId
, const XMLCh* const systemId
, const XMLCh* const baseURI = 0
);
/** 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.
*
* @param resourceIdentifier An object containing the type of
* resource to be resolved and the associated data members
* corresponding to this type.
* @return 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 XMLEntityHandler
* @see XMLEntityResolver
*/
virtual InputSource* resolveEntity
(
XMLResourceIdentifier* resourceIdentifier
);
/** Handle a 'start input source' event
*
* This method is used to indicate the start of parsing an external
* entity file.
*
* <b>This method is a no-op for this DOM parse
* implementation.</b>
*
* @param inputSource A const reference to the InputSource object
* which points to the external entity
* being parsed.
*/
virtual void startInputSource(const InputSource& inputSource);
//@}
// -----------------------------------------------------------------------
// Grammar preparsing interface
// -----------------------------------------------------------------------
/** @name Implementation of Grammar preparsing interface's. */
//@{
/**
* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param source A const reference to the SAX InputSource object which
* points to the schema grammar file to be preparsed.
* @param grammarType The grammar type (Schema or DTD).
* @param toCache If <code>true</code>, we cache the preparsed grammar,
* otherwise, no chaching. Default is <code>false</code>.
* @return The preparsed schema grammar object (SchemaGrammar or
* DTDGrammar). That grammar object is owned by the parser.
*
* @exception SAXException Any SAX exception, possibly
* wrapping another exception.
* @exception XMLException An exception from the parser or client
* handler code.
* @exception DOMException A DOM exception as per DOM spec.
*
* @see InputSource#InputSource
*/
Grammar* loadGrammar(const InputSource& source,
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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param systemId A const XMLCh pointer to the Unicode string which
* contains the path to the XML grammar file to be
* preparsed.
* @param grammarType The grammar type (Schema or DTD).
* @param toCache If <code>true</code>, we cache the preparsed grammar,
* otherwise, no chaching. Default is <code>false</code>.
* @return The preparsed schema grammar object (SchemaGrammar or
* DTDGrammar). That grammar object is owned by the parser.
*
* @exception SAXException Any SAX exception, possibly
* wrapping another exception.
* @exception XMLException An exception from the parser or client
* handler code.
* @exception DOMException A DOM exception as per DOM spec.
*/
Grammar* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param systemId A const char pointer to a native string which contains
* the path to the XML grammar file to be preparsed.
* @param grammarType The grammar type (Schema or DTD).
* @param toCache If <code>true</code>, we cache the preparsed grammar,
* otherwise, no chaching. Default is <code>false</code>.
* @return The preparsed schema grammar object (SchemaGrammar or
* DTDGrammar). That grammar object is owned by the parser.
*
* @exception SAXException Any SAX exception, possibly
* wrapping another exception.
* @exception XMLException An exception from the parser or client
* handler code.
* @exception DOMException A DOM exception as per DOM spec.
*/
Grammar* loadGrammar(const char* const systemId,
const short grammarType,
const bool toCache = false);
/**
* This method allows the user to reset the pool of cached grammars.
*/
void resetCachedGrammarPool();
//@}
private :
// -----------------------------------------------------------------------
// Initialize/Cleanup methods
// -----------------------------------------------------------------------
void resetParse();
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
XercesDOMParser(const XercesDOMParser&);
XercesDOMParser& operator=(const XercesDOMParser&);
// -----------------------------------------------------------------------
// Private data members
//
// fEntityResolver
// The installed SAX entity resolver, if any. Null if none.
//
// fErrorHandler
// The installed SAX error handler, if any. Null if none.
//-----------------------------------------------------------------------
EntityResolver* fEntityResolver;
XMLEntityResolver* fXMLEntityResolver;
ErrorHandler* fErrorHandler;
};
// ---------------------------------------------------------------------------
// XercesDOMParser: Handlers for the XMLEntityHandler interface
// ---------------------------------------------------------------------------
inline void XercesDOMParser::endInputSource(const InputSource&)
{
// The DOM entity resolver doesn't handle this
}
inline bool XercesDOMParser::expandSystemId(const XMLCh* const, XMLBuffer&)
{
// The DOM entity resolver doesn't handle this
return false;
}
inline void XercesDOMParser::resetEntities()
{
// Nothing to do on this one
}
inline void XercesDOMParser::startInputSource(const InputSource&)
{
// The DOM entity resolver doesn't handle this
}
// ---------------------------------------------------------------------------
// XercesDOMParser: Getter methods
// ---------------------------------------------------------------------------
inline ErrorHandler* XercesDOMParser::getErrorHandler()
{
return fErrorHandler;
}
inline const ErrorHandler* XercesDOMParser::getErrorHandler() const
{
return fErrorHandler;
}
inline EntityResolver* XercesDOMParser::getEntityResolver()
{
return fEntityResolver;
}
inline const EntityResolver* XercesDOMParser::getEntityResolver() const
{
return fEntityResolver;
}
inline XMLEntityResolver* XercesDOMParser::getXMLEntityResolver()
{
return fXMLEntityResolver;
}
inline const XMLEntityResolver* XercesDOMParser::getXMLEntityResolver() const
{
return fXMLEntityResolver;
}
XERCES_CPP_NAMESPACE_END
#endif