/*

* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/*

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

 */

#if !defined(SAXPARSER_HPP)

#define SAXPARSER_HPP

#include <xercesc/sax/Parser.hpp>

#include <xercesc/internal/VecAttrListImpl.hpp>

#include <xercesc/framework/XMLDocumentHandler.hpp>

#include <xercesc/framework/XMLElementDecl.hpp>

#include <xercesc/framework/XMLEntityHandler.hpp>

#include <xercesc/framework/XMLErrorReporter.hpp>

#include <xercesc/framework/XMLBuffer.hpp>

#include <xercesc/util/SecurityManager.hpp>

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

XERCES_CPP_NAMESPACE_BEGIN

class DocumentHandler;

class EntityResolver;

class XMLPScanToken;

class XMLScanner;

class XMLValidator;

class Grammar;

class GrammarResolver;

class XMLGrammarPool;

class XMLEntityResolver;

class XMLResourceIdentifier;

class PSVIHandler;

/**

  * This class implements the SAX 'Parser' interface and should be

  * used by applications wishing to parse the XML files using SAX.

  * It allows the client program to install SAX handlers for event

  * callbacks.

  *

  * <p>It can be used to instantiate a validating or non-validating

  * parser, by setting a member flag.</p>

  *

  * @deprecated This interface has been replaced by the SAX2

  *             interface, which includes Namespace support.

  *             See SAX2XMLReader for more information.

  */

class PARSERS_EXPORT SAXParser :

    public XMemory

    , public Parser

    , public XMLDocumentHandler

    , public XMLErrorReporter

    , public XMLEntityHandler

    , public DocTypeHandler    

{

public :

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

    //  Class types

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

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

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

    /** @name Constructors and Destructor */

    //@{

    /** Constructor with an instance of validator class to use for

      * validation.

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

      * @param gramPool   The collection of cached grammers.

      */

    SAXParser

    (

          XMLValidator*   const valToAdopt = 0

        , MemoryManager*  const manager = XMLPlatformUtils::fgMemoryManager

        , XMLGrammarPool* const gramPool = 0 

    );

    /**

      * Destructor

      */

    ~SAXParser();

    //@}

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

    //  Getter Methods

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

    /** @name Getter methods */

    //@{

    /**

      * This method returns the installed document handler. Suitable

      * for 'lvalue' usages.

      *

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

      */

    DocumentHandler* getDocumentHandler();

    /**

      * This method returns the installed document handler. Suitable

      * only for 'rvalue' usages.

      *

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

      */

    const DocumentHandler* getDocumentHandler() const;

    /**

      * This method returns the installed entity resolver. Suitable

      * for 'lvalue' usages.

      *

      * @return The pointer to the installed entity resolver object.

      */

    EntityResolver* getEntityResolver();

    /**

      * This method returns the installed entity resolver. Suitable

      * for 'rvalue' usages.

      *

      * @return A const pointer to the installed entity resolver object.

      */

    const EntityResolver* getEntityResolver() const;

    /**

      * This method returns the installed entity resolver. Suitable

      * for 'lvalue' usages.

      *

      * @return The pointer to the installed entity resolver object.

      */

    XMLEntityResolver* getXMLEntityResolver();

    /**

      * This method returns the installed entity resolver. Suitable

      * for 'rvalue' usages.

      *

      * @return A const pointer to the installed entity resolver object.

      */

    const XMLEntityResolver* getXMLEntityResolver() const;

    /**

      * This method returns the installed error handler. Suitable

      * for 'lvalue' usages.

      *

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

      */

    ErrorHandler* getErrorHandler();

    /**

      * This method returns the installed error handler. Suitable

      * for 'rvalue' usages.

      *

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

      */

    const ErrorHandler* getErrorHandler() 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;

    /**

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

    /**

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

      * handling capability.

      *

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

      *         understand namespaces, false otherwise.

      *

      * @see #setDoNamespaces

      */

    bool getDoNamespaces() const;

    /**

      * This method returns the state of the parser's

      * exit-on-First-Fatal-Error flag.

      *

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

     * To be used only while parsing is in progress.

     *

     * @return offset within the input source

     */

    unsigned int getSrcOffset() 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 cached DTD grammar' flag

      *    

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

      *         ignore cached DTD, false otherwise.

      *

      * @see #setIgnoreCachedDTD

      */

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