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