/*

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

 *

 */

#if !defined(XercesDOMParser_HPP)

#define XercesDOMParser_HPP

#include <xercesc/parsers/AbstractDOMParser.hpp>

XERCES_CPP_NAMESPACE_BEGIN

class EntityResolver;

class ErrorHandler;

class Grammar;

class XMLEntityResolver;

class XMLResourceIdentifier;

 /**

  * 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 PARSERS_EXPORT XercesDOMParser : public AbstractDOMParser

{

public :

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

    //  Constructors and Detructor

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

    /** @name Constructors and Destructor */

    //@{

    /** Construct a XercesDOMParser, 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 gramPool   Pointer to the grammar pool instance from 

      *                   external application.

      *                   The parser does NOT own it.

      *

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

      */

    XercesDOMParser

    (

          XMLValidator* const   valToAdopt = 0

        , MemoryManager* const  manager = XMLPlatformUtils::fgMemoryManager

        , XMLGrammarPool* const gramPool = 0        

    );

    /**

      * Destructor

      */

    virtual ~XercesDOMParser();

    //@}

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

    //  Getter methods

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

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

      *

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

    /**

     * 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 'ignore cached DTD grammar' flag

      *    

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

      *         ignore cached DTD, false otherwise.

      *

      * @see #setIgnoreCachedDTD

      */

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

      *

      * <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 set is used.</i>

      *

      * @param handler  A const pointer to the user supplied entity

      *                 resolver.

      *

      * @see #getXMLEntityResolver

      */

    void setXMLEntityResolver(XMLEntityResolver* const handler);

    /** Set the 'Grammar caching' flag

      *

      * This method allows users to enable or disable caching of grammar when

      * parsing XML documents. When set to true, the parser will cache the

      * resulting grammar for use in subsequent parses.

      *

      * If the flag is set to true, the 'Use cached grammar' flag will also be

      * set to true.

      *

      * The parser's default state is: false.

      *

      * @param newState The value specifying whether we should cache grammars

      *                 or not.

      *

      * @see #isCachingGrammarFromParse

      * @see #useCachedGrammarInParse

      */

    void cacheGrammarFromParse(const bool newState);

    /** Set the 'Use cached grammar' flag

      *

      * This method allows users to enable or disable the use of cached

      * grammars.  When set to true, the parser will use the cached grammar,

      * instead of building the grammar from scratch, to validate XML

      * documents.

      *

      * If the 'Grammar caching' flag is set to true, this mehod ignore the

      * value passed in.

      *

      * The parser's default state is: false.

      *

      * @param newState The value specifying whether we should use the cached

      *                 grammar or not.

      *

      * @see #isUsingCachedGrammarInParse

      * @see #cacheGrammarFromParse

      */

    void useCachedGrammarInParse(const bool newState);

    /** Set the 'ignore cached DTD grammar' flag

      *

      * This method gives users the option to ignore a cached DTD grammar, when

      * an XML document contains both an internal and external DTD, and the use

      * cached grammar from parse option is enabled. Currently, we do not allow

      * using cached DTD grammar when an internal subset is present in the

      * document. This option will only affect the behavior of the parser when

      * an internal and external DTD both exist in a document (i.e. no effect

      * if document has no internal subset).

      *

      * The parser's default state is false

      *

      * @param newValue The state to set

      */

    void setIgnoreCachedDTD(const bool newValue);

    //@}

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

    //  Utility methods

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

    /** @name Utility methods */

    //@{

    /** Reset the documents vector pool and release all the associated memory

      * back to the system.

      *

      * When parsing a document using a DOM parser, all memory allocated

      * for a DOM tree is associated to the DOM document.

      *

      * If you do multiple parse using the same DOM parser instance, then

      * multiple DOM documents will be generated and saved in a vector pool.

      * All these documents (and thus all the allocated memory)

      * won't be deleted until the parser instance is destroyed.

      *

      * If you don't need these DOM documents anymore and don't want to

      * destroy the DOM parser instance at this moment, then you can call this method

      * to reset the document vector pool and release all the allocated memory

      * back to the system.

      *

      * It is an error to call this method if you are in the middle of a

      * parse (e.g. in the mid of a progressive parse).

      *

      * @exception IOException An exception from the parser if this function

      *            is called when a parse is in progress.

      *

      */

    void resetDocumentPool();

    //@}

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

    //  Implementation of the XMLErrorReporter interface.

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

    /** @name Implementation of the XMLErrorReporter interface. */

    //@{

    /** Handle errors reported from the parser

      *

      * This method is used to report back errors found while parsing the

      * XML file. This method is also borrowed from the SAX specification.

      * It calls the corresponding user installed Error Handler method:

      * 'fatal', 'error', 'warning' depending on the severity of the error.

      * This classification is defined by the XML specification.

      *

      * @param errCode An integer code for the error.

      * @param msgDomain A const pointer to an Unicode string representing

      *                  the message domain to use.

      * @param errType An enumeration classifying the severity of the error.

      * @param errorText A const pointer to an Unicode string representing

      *                  the text of the error message.

      * @param systemId  A const pointer to an Unicode string representing

      *                  the system id of the XML file where this error

      *                  was discovered.

      * @param publicId  A const pointer to an Unicode string representing

      *                  the public id of the XML file where this error

      *                  was discovered.

      * @param lineNum   The line number where the error occurred.

      * @param colNum    The column number where the error occurred.

      * @see ErrorHandler

      */

    virtual void error

    (

        const   unsigned int                errCode

        , const XMLCh* const                msgDomain

        , const XMLErrorReporter::ErrTypes  errType

        , const XMLCh* const                errorText

        , const XMLCh* const                systemId

        , const XMLCh* const                publicId

        , const XMLSSize_t                  lineNum

        , const XMLSSize_t                  colNum

    );

    /** Reset any error data before a new parse

     *

      * This method allows the user installed Error Handler callback to

      * 'reset' itself.

      *

      * <b>This method is a no-op for this DOM

      * implementation.</b>

      */

    virtual void resetErrors();

    //@}

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

    //  Implementation of the XMLEntityHandler interface.

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

    /** @name Implementation of the XMLEntityHandler interface. */

    //@{

    /** Handle an end of input source event

      *

      * This method is used to indicate the end of parsing of an external

      * entity file.

      *

      * <b>This method is a no-op for this DOM

      * implementation.</b>

      *

      * @param inputSource A const reference to the InputSource object

      *                    which points to the XML file being parsed.

      * @see InputSource

      */

    virtual void endInputSource(const InputSource& inputSource);

    /** Expand a system id

      *

      * This method allows an installed XMLEntityHandler to further

      * process any system id's of enternal entities encountered in

      * the XML file being parsed, such as redirection etc.

      *

      * <b>This method always returns 'false'

      * for this DOM implementation.</b>

      *

      * @param systemId  A const pointer to an Unicode string representing

      *                  the system id scanned by the parser.

      * @param toFill    A pointer to a buffer in which the application

      *                  processed system id is stored.

      * @return 'true', if any processing is done, 'false' otherwise.

      */

    virtual bool expandSystemId

    (

        const   XMLCh* const    systemId

        ,       XMLBuffer&      toFill

    );

    /** Reset any entity handler information

      *

      * This method allows the installed XMLEntityHandler to reset

      * itself.

      *

      * <b>This method is a no-op for this DOM

      * implementation.</b>

      */

    virtual void resetEntities();

    /** Resolve a public/system id

      *

      * This method allows a user installed entity handler to further

      * process any pointers to external entities. The applications can

      * implement 'redirection' via this callback. This method is also

      * borrowed from the SAX specification.

      *

      * @deprecated This method is no longer called (the other resolveEntity one is).

      *

      * @param publicId A const pointer to a Unicode string representing the

      *                 public id of the entity just parsed.

      * @param systemId A const pointer to a Unicode string representing the

      *                 system id of the entity just parsed.

      * @param baseURI  A const pointer to a Unicode string representing the

      *                 base URI of the entity just parsed,

      *                 or <code>null</code> if there is no base URI.

      * @return The value returned by the user installed resolveEntity

      *         method or NULL otherwise to indicate no processing was done.

      *         The returned InputSource is owned by the parser which is

      *         responsible to clean up the memory.

      * @see DOMEntityResolver

      * @see XMLEntityHandler

      */

    virtual InputSource* resolveEntity

    (

        const   XMLCh* const    publicId

        , const XMLCh* const    systemId

        , const XMLCh* const    baseURI = 0

    );

    /** Resolve a public/system id

      *

      * This method allows a user installed entity handler to further

      * process any pointers to external entities. The applications can

      * implement 'redirection' via this callback.  

      *

      * @param resourceIdentifier An object containing the type of

      *        resource to be resolved and the associated data members

      *        corresponding to this type.

      * @return The value returned by the user installed resolveEntity