secureswitools/swisistools/source/xmlparser/xerces/include/xercesc/dom/DOMBuilder.hpp
#ifndef DOMBuilder_HEADER_GUARD_
#define DOMBuilder_HEADER_GUARD_
/*
* 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: DOMBuilder.hpp 569031 2007-08-23 15:05:28Z amassari $
*
*/
#include <xercesc/util/XercesDefs.hpp>
XERCES_CPP_NAMESPACE_BEGIN
class DOMErrorHandler;
class DOMEntityResolver;
class DOMInputSource;
class DOMBuilderFilter;
class DOMNode;
class DOMDocument;
class Grammar;
/**
* 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
*
*/
class CDOM_EXPORT DOMBuilder
{
protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
/** @name Hidden constructors */
//@{
DOMBuilder() {};
//@}
private:
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
/** @name Unimplemented constructors and operators */
//@{
DOMBuilder(const DOMBuilder &);
DOMBuilder & operator = (const DOMBuilder &);
//@}
public:
// -----------------------------------------------------------------------
// All constructors are hidden, just the destructor is available
// -----------------------------------------------------------------------
/** @name Destructor */
//@{
/**
* Destructor
*
*/
virtual ~DOMBuilder() {};
//@}
// -----------------------------------------------------------------------
// Class types
// -----------------------------------------------------------------------
/** @name Public Constants */
//@{
/**
* Action types for use in parseWithContext.
*
* <p> <code>ACTION_REPLACE</code>:
* Replace the context node with the result of parsing the input source.
* For this action to work the context node must be an
* <code>DOMElement</code>, <code>DOMText</code>, <code>DOMCDATASection</code>,
* <code>DOMComment</code>, <code>DOMProcessingInstruction</code>, or
* <code>DOMEntityReference</code> node.</p>
*
* <p> <code>ACTION_APPEND</code>:
* Append the result of parsing the input source to the context node. For
* this action to work, the context node must be an <code>DOMElement</code>.</p>
*
* <p> <code>ACTION_INSERT_AFTER</code>:
* Insert the result of parsing the input source after the context node.
* For this action to work the context nodes parent must be an
* <code>DOMElement</code>.</p>
*
* <p> <code>ACTION_INSERT_BEFORE</code>:
* Insert the result of parsing the input source before the context node.
* For this action to work the context nodes parent must be an
* <code>DOMElement</code>.</p>
*
* @see parseWithContext(...)
* @since DOM Level 3
*/
enum ActionType
{
ACTION_REPLACE = 1,
ACTION_APPEND_AS_CHILDREN = 2,
ACTION_INSERT_AFTER = 3,
ACTION_INSERT_BEFORE = 4
};
//@}
// -----------------------------------------------------------------------
// Virtual DOMBuilder interface
// -----------------------------------------------------------------------
/** @name Functions introduced in DOM Level 3 */
//@{
// -----------------------------------------------------------------------
// 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @return The pointer to the installed error handler object.
* @since DOM Level 3
*/
virtual DOMErrorHandler* getErrorHandler() = 0;
/**
* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @return A const pointer to the installed error handler object.
* @since DOM Level 3
*/
virtual const DOMErrorHandler* getErrorHandler() const = 0;
/**
* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @return The pointer to the installed entity resolver object.
* @since DOM Level 3
*/
virtual DOMEntityResolver* getEntityResolver() = 0;
/**
* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @return A const pointer to the installed entity resolver object.
* @since DOM Level 3
*/
virtual const DOMEntityResolver* getEntityResolver() const = 0;
/**
* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @return The pointer to the installed application filter.
* @since DOM Level 3
*/
virtual DOMBuilderFilter* getFilter() = 0;
/**
* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @return A const pointer to the installed application filter
* @since DOM Level 3
*/
virtual const DOMBuilderFilter* getFilter() const = 0;
// -----------------------------------------------------------------------
// 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>
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param handler A const pointer to the user supplied error
* handler.
*
* @see #getErrorHandler
* @since DOM Level 3
*/
virtual void setErrorHandler(DOMErrorHandler* const handler) = 0;
/**
* 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 resolver is merely dropped, since the parser
* does not own them.</i>
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param handler A const pointer to the user supplied entity
* resolver.
*
* @see #getEntityResolver
* @since DOM Level 3
*/
virtual void setEntityResolver(DOMEntityResolver* const handler) = 0;
/**
* 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.
*
* <i>Any previously set filter is merely dropped, since the parser
* does not own them.</i>
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param filter A const pointer to the user supplied application
* filter.
*
* @see #getFilter
* @since DOM Level 3
*/
virtual void setFilter(DOMBuilderFilter* const filter) = 0;
// -----------------------------------------------------------------------
// Feature methods
// -----------------------------------------------------------------------
/**
* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* See http://xerces.apache.org/xerces-c/program-dom.html#DOMBuilderFeatures for
* the list of supported features.
*
* @param name The feature name.
* @param state The requested state of the feature (true or false).
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised when the DOMBuilder recognizes the
* feature name but cannot set the requested value.
* <br>NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
* the feature name.
*
* @see #setFeature
* @see #canSetFeature
* @since DOM Level 3
*/
virtual void setFeature(const XMLCh* const name, const bool state) = 0;
/**
* Look up the value of a feature.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param name The feature name.
* @return The current state of the feature (true or false)
* @exception DOMException
* NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
* the feature name.
*
* @see #getFeature
* @see #canSetFeature
* @since DOM Level 3
*/
virtual bool getFeature(const XMLCh* const name) const = 0;
/**
* Query whether setting a feature to a specific value is supported.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param name The feature name.
* @param state The requested state of the feature (true or false).
* @return <code>true</code> if the feature could be successfully set
* to the specified value, or <code>false</code> if the feature
* is not recognized or the requested value is not supported. The
* value of the feature itself is not changed.
*
* @see #getFeature
* @see #setFeature
* @since DOM Level 3
*/
virtual bool canSetFeature(const XMLCh* const name, const bool state) const = 0;
// -----------------------------------------------------------------------
// Parsing methods
// -----------------------------------------------------------------------
/**
* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param source A const reference to the DOMInputSource object which
* points to the XML file to be parsed.
* @return If the DOMBuilder is a synchronous DOMBuilder the newly created
* and populated DOMDocument is returned. If the DOMBuilder is
* asynchronous then <code>null</code> is returned since the
* document object is not yet parsed when this method returns.
* @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 DOMInputSource#DOMInputSource
* @see #setEntityResolver
* @see #setErrorHandler
* @see resetDocumentPool
* @since DOM Level 3
*/
virtual DOMDocument* parse(const DOMInputSource& source) = 0;
/**
* 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.
*
* <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 file to be parsed.
* @return If the DOMBuilder is a synchronous DOMBuilder the newly created
* and populated DOMDocument is returned. If the DOMBuilder is
* asynchronous then <code>null</code> is returned since the
* document object is not yet parsed when this method returns.
* @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 #parse(DOMInputSource,...)
* @see resetDocumentPool
* @since DOM Level 3
*/
virtual DOMDocument* parseURI(const XMLCh* const systemId) = 0;
/**
* 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.
*
* <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 file to be parsed.
* @return If the DOMBuilder is a synchronous DOMBuilder the newly created
* and populated DOMDocument is returned. If the DOMBuilder is
* asynchronous then <code>null</code> is returned since the
* document object is not yet parsed when this method returns.
* @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 #parse(DOMInputSource,...)
* @see resetDocumentPool
*/
virtual DOMDocument* parseURI(const char* const systemId) = 0;
/**
* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param source A const reference to the DOMInputSource object which
* points to the XML file to be parsed.
* @param 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.
* @param 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.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised when the DOMBuilder doesn't support
* this method.
* <br>NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is
* readonly.
* @since DOM Level 3
*/
virtual void parseWithContext
(
const DOMInputSource& source
, DOMNode* const contextNode
, const short action
) = 0;
//@}
// -----------------------------------------------------------------------
// Non-standard Extension
// -----------------------------------------------------------------------
/** @name Non-standard Extension */
//@{
/**
* 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://xerces.apache.org/xerces-c/program-dom.html#DOMBuilderProperties to learn
* exactly what type of property value each property returns for replication.
*
* @param name The unique identifier (URI) of the property being set.
* @return 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.
* @exception DOMException
* <br>NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
* the requested property.
*/
virtual void* getProperty(const XMLCh* const name) const = 0 ;
/**
* Set the value of any property in a DOMBuilder.
* See http://xerces.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://xerces.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.
*
* @param name The unique identifier (URI) of the property being set.
* @param value The requested value for the property.
* See http://xerces.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.
* @exception DOMException
* <br>NOT_FOUND_ERR: Raised when the DOMBuilder does not recognize
* the requested property.
*/
virtual void setProperty(const XMLCh* const name, void* value) = 0 ;
/**
* 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 release() = 0;
/** 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.
*
*/
virtual void resetDocumentPool() = 0;
/**
* 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.
*
* <p><b>"Experimental - subject to change"</b></p>
*
* @param source A const reference to the DOMInputSource 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 DOMInputSource#DOMInputSource
*/
virtual Grammar* loadGrammar(const DOMInputSource& source,
const short grammarType,
const bool toCache = false) = 0;
/**
* 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.
*/
virtual Grammar* loadGrammar(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
*
* 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.
*/
virtual Grammar* loadGrammar(const char* const systemId,
const short grammarType,
const bool toCache = false) = 0;
/**
* Retrieve the grammar that is associated with the specified namespace key
*
* @param nameSpaceKey Namespace key
* @return Grammar associated with the Namespace key.
*/
virtual Grammar* getGrammar(const XMLCh* const nameSpaceKey) const = 0;
/**
* Retrieve the grammar where the root element is declared.
*
* @return Grammar where root element declared
*/
virtual Grammar* getRootGrammar() const = 0;
/**
* 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.
*/
virtual const XMLCh* getURIText(unsigned int uriId) const = 0;
/**
* Clear the cached grammar pool
*/
virtual void resetCachedGrammarPool() = 0;
/**
* Returns the current src offset within the input source.
*
* @return offset within the input source
*/
virtual unsigned int getSrcOffset() const = 0;
//@}
};
XERCES_CPP_NAMESPACE_END
#endif