/*

 * 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: DOMParser.hpp 568078 2007-08-21 11:43:25Z amassari $

 *

 */

#if !defined(DOMPARSER_HPP)

#define DOMPARSER_HPP

#include <xercesc/framework/XMLDocumentHandler.hpp>

#include <xercesc/framework/XMLErrorReporter.hpp>

#include <xercesc/framework/XMLEntityHandler.hpp>

#include <xercesc/util/ValueStackOf.hpp>

#include <xercesc/validators/DTD/DocTypeHandler.hpp>

#include <xercesc/validators/DTD/DTDElementDecl.hpp>

#include "DOM_Document.hpp"

#include "DOM_DocumentType.hpp"

XERCES_CPP_NAMESPACE_BEGIN

class EntityResolver;

class ErrorHandler;

class XMLPScanToken;

class XMLScanner;

class XMLValidator;

class Grammar;

class GrammarResolver;

class XMLGrammarPool;

class XMLEntityResolver;

class PSVIHandler;

/**

  * 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 DEPRECATED_DOM_EXPORT DOMParser :

    public XMLDocumentHandler

    , public XMLErrorReporter

    , public XMLEntityHandler

    , public DocTypeHandler

    , public XMemory

{

public :

    // -----------------------------------------------------------------------

    //  Class types

    // -----------------------------------------------------------------------

    enum ValSchemes

    {

        Val_Never

        , Val_Always

        , Val_Auto

    };

    // -----------------------------------------------------------------------

    //  Constructors and Detructor

    // -----------------------------------------------------------------------

    /** @name Constructors and Destructor */

    //@{

    /** Construct a DOMParser, 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 valToAdopt Pointer to the validator instance to use. The

      *                   parser is responsible for freeing the memory.

      */

    DOMParser

    (

          XMLValidator* const   valToAdopt = 0

        , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

        , XMLGrammarPool* const gramPool = 0

    );

    /**

      * Destructor

      */

    ~DOMParser();

    //@}

    /** Reset the parser

      *

      * This method resets the state of the DOM driver and makes

      * it ready for a fresh parse run.

      */

    void reset();

    // -----------------------------------------------------------------------

    //  Getter methods

    // -----------------------------------------------------------------------

    /** @name Getter methods */

    //@{

    /** Get the DOM document

      *

      * 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.

      *

      * @return The DOM_Document object which represents the entire

      *         XML document.

      */

    DOM_Document getDocument();

    /** 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 PSVI handler

      *

      * This method returns the installed PSVI handler. If no handler

      * has been installed, then it will be a zero pointer.

      *

      * @return The pointer to the installed PSVI handler object.

      */

    PSVIHandler* getPSVIHandler();

    /** 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 PSVIHandler* getPSVIHandler() 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 a const reference to the underlying scanner

      *

      * This method returns a reference to the underlying scanner object.

      * It allows read only access to data maintained in the scanner.

      *

      * @return A const reference to the underlying scanner object.

      */

    const XMLScanner& getScanner() const;

    /** Get a const reference to the validator

      *

      * This method returns a reference to the parser's installed

      * validator.

      *

      * @return A const reference to the installed validator object.

      */

    const XMLValidator& getValidator() const;

    /**

      * This method returns an enumerated value that indicates the current

      * validation scheme set on this parser.

      *

      * @return The ValSchemes value current set on this parser.

      * @see #setValidationScheme

      */

    ValSchemes getValidationScheme() const;

    /** Get the 'do schema' flag

      *

      * This method returns the state of the parser's schema processing

      * flag.

      *

      * @return true, if the parser is currently configured to

      *         understand schema, false otherwise.

      *

      * @see #setDoSchema

      */

    bool getDoSchema() const;

    /** Get the 'full schema constraint checking' flag

      *

      * This method returns the state of the parser's full schema constraint

      * checking flag.

      *

      * @return true, if the parser is currently configured to

      *         have full schema constraint checking, false otherwise.

      *

      * @see #setValidationSchemaFullChecking

      */

    bool getValidationSchemaFullChecking() const;

    bool getIdentityConstraintChecking() const;

    /** Get error count from the last parse operation.

      *

      * This method returns the error count from the last parse

      * operation. Note that this count is actually stored in the

      * scanner, so this method simply returns what the

      * scanner reports.

      *

      * @return number of errors encountered during the latest

      *			parse operation.

      *

      */

    int getErrorCount() const;

    /** Get the 'do namespaces' flag

      *

      * This method returns the state of the parser's namespace processing

      * flag.

      *

      * @return true, if the parser is currently configured to

      *         understand namespaces, false otherwise.

      *

      * @see #setDoNamespaces

      */

    bool getDoNamespaces() const;

    /** Get the 'exit on first error' flag

      *

      * This method returns the state of the parser's

      * exit-on-First-Fatal-Error flag. If this flag is true, then the

      * parse will exit the first time it sees any non-wellformed XML or

      * any validity error. The default state is true.

      *

      * @return true, if the parser is currently configured to

      *         exit on the first fatal error, false otherwise.

      *

      * @see #setExitOnFirstFatalError

      */

    bool getExitOnFirstFatalError() const;

    /**

      * This method returns the state of the parser's

      * validation-constraint-fatal flag.

      *

      * @return true, if the parser is currently configured to

      *         set validation constraint errors as fatal, false

      *         otherwise.

      *

      * @see #setValidationContraintFatal

      */

    bool getValidationConstraintFatal() const;

    /** Get the 'include entity references' flag

      *

      * This method returns the flag that specifies whether the parser is

      * creating entity reference nodes in the DOM tree being produced.

      *

      * @return  The state of the create entity reference node

      *               flag.

      * @see #setCreateEntityReferenceNodes

      */

    bool  getCreateEntityReferenceNodes()const;

   /** Get the 'include ignorable whitespace' flag.

      *

      * This method returns the state of the parser's include ignorable

      * whitespace flag.

      *

      * @return 'true' if the include ignorable whitespace flag is set on

      *         the parser, 'false' otherwise.

      *

      * @see #setIncludeIgnorableWhitespace

      */

    bool getIncludeIgnorableWhitespace() const;

    /** Get the 'to create MXLDecl node' flag.

      *

      * This method returns the state of the parser's to create XMLDecl

      * DOM Node flag.

      *

      * @return 'true' if the toCreateXMLDeclTypeNode flag is set on

      *         the parser, 'false' otherwise.

      *

      */

    bool getToCreateXMLDeclTypeNode() const;

   /** Get the set of Namespace/SchemaLocation that is specified externaly.

      *

      * This method returns the list of Namespace/SchemaLocation that was

      * specified using setExternalSchemaLocation.

      *

      * The parser owns the returned string, and the memory allocated for

      * the returned string will be destroyed when the parser is deleted.

      *

      * To ensure assessiblity of the returned information after the parser

      * is deleted, callers need to copy and store the returned information

      * somewhere else.

      *

      * @return a pointer to the list of Namespace/SchemaLocation that was

      *         specified externally.  The pointer spans the same life-time as

      *         the parser.  A null pointer is returned if nothing

      *         was specified externally.

      *

      * @see #setExternalSchemaLocation(const XMLCh* const)

      */

    XMLCh* getExternalSchemaLocation() const;

   /** Get the noNamespace SchemaLocation that is specified externaly.

      *

      * This method returns the no target namespace XML Schema Location

      * that was specified using setExternalNoNamespaceSchemaLocation.

      *

      * The parser owns the returned string, and the memory allocated for

      * the returned string will be destroyed when the parser is deleted.

      *

      * To ensure assessiblity of the returned information after the parser

      * is deleted, callers need to copy and store the returned information

      * somewhere else.

      *

      * @return a pointer to the no target namespace Schema Location that was

      *         specified externally.  The pointer spans the same life-time as

      *         the parser.  A null pointer is returned if nothing

      *         was specified externally.

      *

      * @see #setExternalNoNamespaceSchemaLocation(const XMLCh* const)

      */

    XMLCh* getExternalNoNamespaceSchemaLocation() 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;

    /**

      * Get the 'calculate src offset flag'

      *

      * This method returns the state of the parser's src offset calculation

      * when parsing an XML document.

      *

      * @return true, if the parser is currently configured to

      *         calculate src offsets, false otherwise.

      *

      * @see #setCalculateSrcOfs

      */

    bool getCalculateSrcOfs() const;

    /**

      * Get the 'force standard uri flag'

      *

      * This method returns the state if the parser forces standard uri

      *

      * @return true, if the parser is currently configured to

      *         force standard uri, i.e. malformed uri will be rejected.

      *

      * @see #setStandardUriConformant

      */

    bool getStandardUriConformant() 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.

      *

      * @return offset within the input source

      */

    unsigned int getSrcOffset() 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 PSVI handler

      *

      * This method allows applications to install their own PSVI handler.

      *

      * <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 PSVI

      *                 handler.

      *

      * @see #getPSVIHandler

      */

    void setPSVIHandler(PSVIHandler* 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.