/*

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

 *

 */

#if !defined(ABSTRACTDOMPARSER_HPP)

#define ABSTRACTDOMPARSER_HPP

#include <xercesc/dom/DOMDocument.hpp>

#include <xercesc/framework/XMLDocumentHandler.hpp>

#include <xercesc/framework/XMLErrorReporter.hpp>

#include <xercesc/framework/XMLEntityHandler.hpp>

#include <xercesc/util/SecurityManager.hpp>

#include <xercesc/util/ValueStackOf.hpp>

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

#include <xercesc/dom/DOMDocumentType.hpp>

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

#include <xercesc/framework/XMLBufferMgr.hpp>

#include <xercesc/framework/psvi/PSVIHandler.hpp>

XERCES_CPP_NAMESPACE_BEGIN

class XMLPScanToken;

class XMLScanner;

class XMLValidator;

class DOMDocumentImpl;

class DOMDocumentTypeImpl;

class DOMElement;

class GrammarResolver;

class XMLGrammarPool;

class PSVIHandler;

/**

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

  * It is used as a base for DOM parsers (i.e. XercesDOMParser, DOMBuilder).

  */

class PARSERS_EXPORT AbstractDOMParser :

    public XMemory

    , public XMLDocumentHandler

    , public XMLErrorReporter

    , public XMLEntityHandler

    , public DocTypeHandler

    , public PSVIHandler

{

public :

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

    //  Class types

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

    /** @name Public constants */

    //@{

    /** ValScheme enum used in setValidationScheme

      *    Val_Never:  Do not report validation errors.

      *    Val_Always: The parser will always report validation errors.

      *    Val_Auto:   The parser will report validation errors only if a grammar is specified.

      *

      * @see #setValidationScheme

      */

    enum ValSchemes

    {

        Val_Never

        , Val_Always

        , Val_Auto

    };

    //@}

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

    //  Constructors and Detructor

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

    /** @name Destructor */

    //@{

    /**

      * Destructor

      */

    virtual ~AbstractDOMParser();

    //@}

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

    //  Utility methods

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

    /** @name Utility methods */

    //@{

    /** Reset the parser

      *

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

      * it ready for a fresh parse run.

      */

    void reset();

    /** Adopt the DOM document

      *

      * This method returns the DOMDocument object representing the

      * root of the document tree.

      *

      * The caller will adopt the DOMDocument and thus is responsible to

      * call DOMDocument::release() to release the associated memory.

      * The parser will not delete it.   The ownership is transferred

      * from the parser to the caller.

      *

      * @return The adopted DOMDocument object which represents the entire

      *         XML document.

      */

    DOMDocument* adoptDocument();

    //@}

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

    //  Getter methods

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

    /** @name Getter methods */

    //@{

    /** Get the DOM document

      *

      * This method returns the DOMDocument object representing the

      * root of the document tree. This object provides the primary

      * access to the document's data.

      *

      * The returned DOMDocument object is owned by the parser.

      *

      * @return The DOMDocument object which represents the entire

      *         XML document.

      */

    DOMDocument* getDocument();

    /** 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;

    /** Get the identity constraint checking' flag

      *

      * This method returns the state of the parser's identity constraint

      * checking flag.

      *

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

      *         have identity constraint checking, false otherwise.

      *

      * @see setIdentityConstraintChecking

      */

    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 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 SecurityManager instance attached to this parser.

      *

      * This method returns the security manager 

      * that was specified using setSecurityManager.

      *

      * The SecurityManager instance must have been specified by the application; 

      * this should not be deleted until after the parser has been deleted (or

      * a new SecurityManager instance has been supplied to the parser).

      * 

      * @return a pointer to the SecurityManager instance 

      *         specified externally.  A null pointer is returned if nothing

      *         was specified externally.

      *

      * @see #setSecurityManager(const SecurityManager* const)

      */

    SecurityManager* getSecurityManager() const;

    /** Get the 'Loading External DTD' flag

      *

      * This method returns the state of the parser's loading external DTD

      * flag.

      *

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

      *         ignore external DTD completely, true otherwise.

      *

      * @see #setLoadExternalDTD

      * @see #getValidationScheme

      */

    bool getLoadExternalDTD() const;

    /** Get the 'create comment node' flag

      *

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

      * creating comment nodes in the DOM tree being produced.

      *

      * @return  The state of the create comment node flag.

      * @see #setCreateCommentNodes

      */

    bool  getCreateCommentNodes()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;

    /**

      * This method returns the installed PSVI handler. Suitable

      * for 'lvalue' usages.

      *

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

      */

    PSVIHandler* getPSVIHandler();

    /**

      * This method returns the installed PSVI handler. Suitable

      * for 'rvalue' usages.

      *

      * @return A const pointer to the installed PSVI handler object.

      */

    const PSVIHandler* getPSVIHandler() const;

    /** Get the 'associate schema info' flag

      *

      * This method returns the flag that specifies whether

      * the parser is storing schema informations in the element 

      * and attribute nodes in the DOM tree being produced.

      *

      * @return  The state of the associate schema info flag.

      * @see #setCreateSchemaInfo

      */

    bool  getCreateSchemaInfo() const;

    /** Get the 'generate synthetic annotations' flag

      *    

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

      *         generate synthetic annotations, false otherwise.

      *         A synthetic XSAnnotation is created when a schema

      *         component has non-schema attributes but has no

      *         child annotations so that the non-schema attributes

      *         can be recovered under PSVI.

      *

      * @see #setGenerateSyntheticAnnotations

      */

    bool getGenerateSyntheticAnnotations() const;

    /** Get the 'validate annotations' flag

      *    

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

      *         validate annotations, false otherwise.

      *

      * @see #setValidateAnnotations

      */

    bool getValidateAnnotations() const;

    /** Get the 'ignore annotations' flag

      *    

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

      *         ignore annotations, false otherwise.

      *

      * @see #setIgnoreAnnotations

      */

    bool getIgnoreAnnotations() const;

    /** Get the 'disable default entity resolution' flag

      *    

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

      *         not perform default entity resolution, false otherwise.

      *

      * @see #setDisableDefaultEntityResolution

      */

    bool getDisableDefaultEntityResolution() const;

    /** Get the 'skip DTD validation' flag

      *    

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

      *         skip DTD validation, false otherwise.

      *

      * @see #setSkipDTDValidation

      */

    bool getSkipDTDValidation() const;

    //@}

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

    //  Setter methods

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

    /** @name Setter methods */

    //@{

    /** set the 'generate synthetic annotations' flag

      *    

      * @param newValue The value for specifying whether Synthetic Annotations

      *        should be generated or not.

      *         A synthetic XSAnnotation is created when a schema

      *         component has non-schema attributes but has no

      *         child annotations so that the non-schema attributes

      *         can be recovered under PSVI.

      *

      * @see #getGenerateSyntheticAnnotations

      */

    void setGenerateSyntheticAnnotations(const bool newValue);

    /** set the 'validlate annotations' flag

      *    

      * @param newValue The value for specifying whether Annotations

      *        should be validated or not.

      *

      * @see #getValidateAnnotations

      */

    void setValidateAnnotations(const bool newValue);

    /** Set the 'do namespaces' flag

      *

      * This method allows users to enable or disable the parser's

      * namespace processing. When set to true, parser starts enforcing

      * all the constraints and rules specified by the NameSpace

      * specification.

      *

      * The parser's default state is: false.

      *

      * @param newState The value specifying whether NameSpace rules should

      *                 be enforced or not.

      *

      * @see #getDoNamespaces

      */

    void setDoNamespaces(const bool newState);

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

      *

      * This method allows users to set the parser's behaviour when it

      * encounters the first fatal error. If set to true, the parser

      * will exit at the first fatal error. If false, then it will

      * report the error and continue processing.

      *

      * The default value is 'true' and the parser exits on the

      * first fatal error.

      *

      * @param newState The value specifying whether the parser should

      *                 continue or exit when it encounters the first

      *                 fatal error.

      *

      * @see #getExitOnFirstFatalError

      */

    void setExitOnFirstFatalError(const bool newState);

    /**

      * This method allows users to set the parser's behaviour when it

      * encounters a validtion constraint error. If set to true, and the