libs/xerces-static/xercesc/sax/Parser.hpp
/*
* 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 527149 2007-04-10 14:56:39Z amassari $
*/
#if !defined(XERCESC_INCLUDE_GUARD_PARSER_HPP)
#define XERCESC_INCLUDE_GUARD_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(const 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(const 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