#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;