/*

* 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: SAX2XMLReaderImpl.hpp 569031 2007-08-23 15:05:28Z amassari $

 */

#if !defined(SAX2XMLReaderImpl_HPP)

#define SAX2XMLReaderImpl_HPP

#include <xercesc/parsers/SAXParser.hpp>

#include <xercesc/sax/Parser.hpp>

#include <xercesc/framework/XMLBuffer.hpp>

#include <xercesc/internal/VecAttributesImpl.hpp>

#include <xercesc/sax2/SAX2XMLReader.hpp>

#include <xercesc/util/RefStackOf.hpp>

#include <xercesc/util/SecurityManager.hpp>

#include <xercesc/util/ValueStackOf.hpp>

XERCES_CPP_NAMESPACE_BEGIN

class ContentHandler;

class LexicalHandler;

class DeclHandler;

class GrammarResolver;

class XMLGrammarPool;

class XMLResourceIdentifier;

class PSVIHandler;

/**

  * This class implements the SAX2 'XMLReader' interface and should be

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

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

  * callbacks.

  *

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

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

  *

  * we basically re-use the existing SAX1 parser code, but provide a

  * new implementation of XMLContentHandler that raises the new

  * SAX2 style events

  *

  */

class PARSERS_EXPORT SAX2XMLReaderImpl :

	public XMemory

    , public SAX2XMLReader

    , public XMLDocumentHandler

    , public XMLErrorReporter

    , public XMLEntityHandler

    , public DocTypeHandler

{

public :

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

    //  Constructors and Destructor

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

    /** @name Constructors and Destructor */

    //@{

    /** The default constructor */

	SAX2XMLReaderImpl(

                            MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

                          , XMLGrammarPool* const gramPool = 0 

                          );

    /** The destructor */	

	~SAX2XMLReaderImpl() ;

   //@}

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

    // Implementation of SAX2XMLReader Interface

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

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

    // The XMLReader interface

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

    /** @name Implementation of SAX 2.0 XMLReader interface's. */

    //@{

    /**

      * This method returns the installed content handler.

      *

      * @return A pointer to the installed content handler object.

      */

    virtual ContentHandler* getContentHandler() const ;

    /**

      * This method returns the installed DTD handler.

      *

      * @return A pointer to the installed DTD handler object.

      */

    virtual DTDHandler* getDTDHandler() const ;

    /**

      * This method returns the installed entity resolver.

      *

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

      */

    virtual EntityResolver* getEntityResolver() const ;

    /**

      * This method returns the installed entity resolver.

      *

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

      */

    virtual XMLEntityResolver* getXMLEntityResolver() const ;

    /**

      * This method returns the installed error handler.

      *

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

      */

    virtual ErrorHandler* getErrorHandler() const ;

    /**

      * This method returns the installed PSVI handler.

      *

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

      */

    virtual PSVIHandler* getPSVIHandler() const ;

	/**

     * Query the current state of any feature in a SAX2 XMLReader.

	  *

	  * @param name The unique identifier (URI) of the feature being set.

	  * @return The current state of the feature.

     * @exception SAXNotRecognizedException If the requested feature is not known.

	  */

	virtual bool getFeature(const XMLCh* const name) const ;

	/**

     * Query the current value of a property in a SAX2 XMLReader.

     *

     * The parser owns the returned pointer.  The memory allocated for

     * the returned pointer 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; otherwise you may get unexpected result.  Since the returned

     * pointer is a generic void pointer, see

     * http://xerces.apache.org/xerces-c/program-sax2.html#SAX2Properties 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  SAXNotRecognizedException If the requested property is not known.

     */

	virtual void* getProperty(const XMLCh* const name) const ;

  /**

    * Allow an application to register a document event handler.

    *

    * If the application does not register a document handler, all

    * document events reported by the SAX parser will be silently

    * ignored (this is the default behaviour implemented by

    * HandlerBase).

    *

    * Applications may register a new or different handler in the

    * middle of a parse, and the SAX parser must begin using the new

    * handler immediately.

    *

    * @param handler The document handler.

    * @see DocumentHandler#DocumentHandler

    * @see HandlerBase#HandlerBase

    */

    virtual void setContentHandler(ContentHandler* const handler) ;

  /**

    * Allow an application to register a DTD event handler.

    *

    * If the application does not register a DTD handler, all DTD

    * events reported by the SAX parser will be silently ignored (this

    * is the default behaviour implemented by HandlerBase).

    *

    * Applications may register a new or different handler in the middle

    * of a parse, and the SAX parser must begin using the new handler

    * immediately.

    *

    * @param handler The DTD handler.

    * @see DTDHandler#DTDHandler

    * @see HandlerBase#HandlerBase

    */

    virtual void setDTDHandler(DTDHandler* const handler) ;

  /**

    * Allow an application to register a custom entity resolver.

    *

    * If the application does not register an entity resolver, the

    * SAX parser will resolve system identifiers and open connections

    * to entities itself (this is the default behaviour implemented in

    * DefaultHandler).

    *

    * Applications may register a new or different entity resolver

    * in the middle of a parse, and the SAX parser must begin using

    * the new resolver immediately.

    *

    * <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 resolver The object for resolving entities.

    * @see EntityResolver#EntityResolver

    * @see DefaultHandler#DefaultHandler

    */

    virtual void setEntityResolver(EntityResolver* const resolver) ;

  /** 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 resolver  A const pointer to the user supplied entity

    *                  resolver.

    *

    * @see #getXMLEntityResolver

    */

    virtual void setXMLEntityResolver(XMLEntityResolver* const resolver) ;

  /**

    * Allow an application to register an error event handler.

    *

    * If the application does not register an error event handler,

    * all error events reported by the SAX parser will be silently

    * ignored, except for fatalError, which will throw a SAXException

    * (this is the default behaviour implemented by HandlerBase).

    *

    * Applications may register a new or different handler in the

    * middle of a parse, and the SAX parser must begin using the new

    * handler immediately.

    *

    * @param handler The error handler.

    * @see ErrorHandler#ErrorHandler

    * @see SAXException#SAXException

    * @see HandlerBase#HandlerBase

    */

    virtual void setErrorHandler(ErrorHandler* const handler) ;

  /**

    * This method installs the user specified PSVI handler on

    * the parser.

    *

    * @param handler A pointer to the PSVI handler to be called

    *                when the parser comes across 'PSVI' events

    *                as per the schema specification.

    */

    virtual void setPSVIHandler(PSVIHandler* const handler);

  /**

    * Set the state of any feature in a SAX2 XMLReader.

    * Supported features in SAX2 for xerces-c are:

    * <br>(See http://xerces.apache.org/xerces-c/program-sax2.html#SAX2Features for detail description).

    *

    * <br>http://xml.org/sax/features/validation (default: false)

    * <br>http://xml.org/sax/features/namespaces (default: true)

    * <br>http://xml.org/sax/features/namespace-prefixes (default: false)

    * <br>http://apache.org/xml/features/validation/dynamic (default: false)

    * <br>http://apache.org/xml/features/validation/reuse-grammar (default: false)

    * <br>http://apache.org/xml/features/validation/schema (default: true)

    * <br>http://apache.org/xml/features/validation/schema-full-checking (default: false)

    * <br>http://apache.org/xml/features/nonvalidating/load-external-dtd (default: true)

    * <br>http://apache.org/xml/features/continue-after-fatal-error (default: false)

    * <br>http://apache.org/xml/features/validation-error-as-fatal (default: false)

    * <br>http://apache.org/xml/features/validation/reuse-validator (Deprecated) (default: false)

    *

    * @param name The unique identifier (URI) of the feature.

    * @param value The requested state of the feature (true or false).

    * @exception SAXNotRecognizedException If the requested feature is not known.

    * @exception SAXNotSupportedException Feature modification is not supported during parse

    *

    */

	virtual void setFeature(const XMLCh* const name, const bool value) ;

  /**

    * Set the value of any property in a SAX2 XMLReader.

    * Supported properties in SAX2 for xerces-c are:

    * <br>(See http://xerces.apache.org/xerces-c/program-sax2.html#SAX2Properties for detail description).

    *

    * <br>http://apache.org/xml/properties/schema/external-schemaLocation

    * <br>http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation.

    *

    * 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-sax2.html#SAX2Properties

    * 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-sax2.html#SAX2Properties 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 SAXNotRecognizedException If the requested property is not known.

    * @exception SAXNotSupportedException Property modification is not supported during parse

    */

	virtual void setProperty(const XMLCh* const name, void* value) ;

  /**

    * Parse an XML document.

    *

    * The application can use this method to instruct the SAX parser

    * to begin parsing an XML document from any valid input

    * source (a character stream, a byte stream, or a URI).

    *

    * Applications may not invoke this method while a parse is in

    * progress (they should create a new Parser instead for each

    * additional XML document).  Once a parse is complete, an

    * application may reuse the same Parser object, possibly with a

    * different input source.

    *

    * @param source The input source for the top-level of the

    *               XML document.

    * @exception SAXException Any SAX exception, possibly

    *            wrapping another exception.

    * @exception XMLException An exception from the parser or client

    *            handler code.

    * @see InputSource#InputSource

    * @see #setEntityResolver

    * @see #setDTDHandler

    * @see #setDocumentHandler

    * @see #setErrorHandler

    */

    virtual void parse

    (

        const   InputSource&    source

    ) ;

  /**

    * Parse an XML document from a system identifier (URI).

    *

    * This method is a shortcut for the common case of reading a

    * document from a system identifier.  It is the exact equivalent

    * of the following:

    *

    * parse(new URLInputSource(systemId));

    *

    * If the system identifier is a URL, it must be fully resolved

    * by the application before it is passed to the parser.

    *

    * @param systemId The system identifier (URI).

    * @exception SAXException Any SAX exception, possibly

    *            wrapping another exception.

    * @exception XMLException An exception from the parser or client

    *            handler code.

    * @see #parse(InputSource)

    */

    virtual void parse

    (

        const   XMLCh* const    systemId

    ) ;

  /**

    * Parse an XML document from a system identifier (URI).

    *

    * This method is a shortcut for the common case of reading a

    * document from a system identifier.  It is the exact equivalent

    * of the following:

    *

    * parse(new URLInputSource(systemId));

    *

    * If the system identifier is a URL, it must be fully resolved

    * by the application before it is passed to the parser.

    *

    * @param systemId The system identifier (URI).

    * @exception SAXException Any SAX exception, possibly

    *            wrapping another exception.

    * @exception XMLException An exception from the parser or client

    *            handler code.

    * @see #parse(InputSource)

    */

    virtual void parse

    (

        const   char* const     systemId

    ) ;

    //@}

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

    //  SAX 2.0-ext

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

    /** @name SAX 2.0-ext */

    //@{

    /**

      * This method returns the installed declaration handler.

      *

      * @return A pointer to the installed declaration handler object.

      */

    virtual DeclHandler* getDeclarationHandler() const ;

	/**

      * This method returns the installed lexical handler.

      *

      * @return A pointer to the installed lexical handler object.

      */

    virtual LexicalHandler* getLexicalHandler() const ;

   /**

    * Allow an application to register a declaration event handler.

    *

    * If the application does not register a declaration handler,

    * all events reported by the SAX parser will be silently

    * ignored. (this is the default behaviour implemented by DefaultHandler).

    *

    * Applications may register a new or different handler in the

    * middle of a parse, and the SAX parser must begin using the new

    * handler immediately.

    *

    * @param handler The DTD declaration handler.

    * @see DeclHandler#DeclHandler

    * @see SAXException#SAXException

    * @see DefaultHandler#DefaultHandler

    */

    virtual void setDeclarationHandler(DeclHandler* const handler) ;

   /**

    * Allow an application to register a lexical event handler.

    *

    * If the application does not register a lexical handler,

    * all events reported by the SAX parser will be silently

    * ignored. (this is the default behaviour implemented by HandlerBase).

    *

    * Applications may register a new or different handler in the

    * middle of a parse, and the SAX parser must begin using the new

    * handler immediately.

    *

    * @param handler The error handler.

    * @see LexicalHandler#LexicalHandler

    * @see SAXException#SAXException

    * @see HandlerBase#HandlerBase

    */

    virtual void setLexicalHandler(LexicalHandler* const handler) ;

    //@}

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

    //  Getter Methods

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

    /** @name Getter Methods (Xerces-C specific) */

    //@{

    /**

	  * This method is used to get the current validator.

	  *

	  * <b>SAX2XMLReader assumes responsibility for the validator.  It will be

	  * deleted when the XMLReader is destroyed.</b>

	  *

	  * @return A pointer to the validator.  An application should not deleted

	  * the object returned.

	  *

	  */

	virtual XMLValidator* getValidator() 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.

      */

    virtual int getErrorCount() const ;

    /**

      * This method returns the state of the parser's

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

      *

      * <p>Or you can query the feature "http://apache.org/xml/features/continue-after-fatal-error"

      * which indicates the opposite state.</p>

      *

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

      *         exit on the first fatal error, false otherwise.

      *

      * @see #setExitOnFirstFatalError

      * @see #getFeature

      */

    virtual bool getExitOnFirstFatalError() const ;

    /**

      * This method returns the state of the parser's

      * validation-constraint-fatal flag.

      *

      * <p>Or you can query the feature "http://apache.org/xml/features/validation-error-as-fatal"

      * which means the same thing.

      *

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

      *         set validation constraint errors as fatal, false

      *         otherwise.

      *

      * @see #setValidationContraintFatal