/*

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

 */

#ifndef PARSER_HPP

#define PARSER_HPP

#include <xercesc/util/XercesDefs.hpp>

XERCES_CPP_NAMESPACE_BEGIN

class DTDHandler;

class EntityResolver;

class DocumentHandler;

class ErrorHandler;

class InputSource;

/**

  * Basic interface for SAX (Simple API for XML) parsers.

  *

  * All SAX parsers must implement this basic interface: it allows

  * applications to register handlers for different types of events

  * and to initiate a parse from a URI, or a character stream.

  *

  * All SAX parsers must also implement a zero-argument constructor

  * (though other constructors are also allowed).

  *

  * SAX parsers are reusable but not re-entrant: the application

  * may reuse a parser object (possibly with a different input source)

  * once the first parse has completed successfully, but it may not

  * invoke the parse() methods recursively within a parse.

  *

  * @see EntityResolver#EntityResolver

  * @see DTDHandler#DTDHandler

  * @see DocumentHandler#DocumentHandler

  * @see ErrorHandler#ErrorHandler

  * @see HandlerBase#HandlerBase

  * @see InputSource#InputSource

  */

#include <xercesc/util/XercesDefs.hpp>

class SAX_EXPORT Parser

{

public:

    /** @name Constructors and Destructor */

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

    //  Constructors and Destructor

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

    //@{

    /** The default constructor */

    Parser()

    {

    }

    /** The destructor */

    virtual ~Parser()

    {

    }

    //@}

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

    // The parser interface

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

    /** @name The parser interfaces */

    //@{

  /**

    * 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

    * HandlerBase).

    *

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

    *

    * @param resolver The object for resolving entities.

    * @see EntityResolver#EntityResolver

    * @see HandlerBase#HandlerBase

    */

    virtual void setEntityResolver(EntityResolver* const resolver) = 0;

  /**

    * 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) = 0;

  /**

    * 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 setDocumentHandler(DocumentHandler* const handler) = 0;

  /**

    * 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) = 0;

  /**

    * 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

    ) = 0;

  /**

    * 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

    ) = 0;

  /**

    * 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

    ) = 0;

    //@}

private :

    /* The copy constructor, you cannot call this directly */

    Parser(const Parser&);

    /* The assignment operator, you cannot call this directly */

    Parser& operator=(const Parser&);

};

XERCES_CPP_NAMESPACE_END

#endif