/* * Copyright 1999-2001,2004 The Apache Software Foundation. * * Licensed 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. */ /* * $Log: Parser.hpp,v $ * Revision 1.5 2004/09/08 13:56:19 peiyongz * Apache License Version 2.0 * * Revision 1.4 2003/03/07 18:10:06 tng * Return a reference instead of void for operator= * * Revision 1.3 2002/11/04 14:56:26 tng * C++ Namespace Support. * * Revision 1.2 2002/07/11 18:29:09 knoaman * Grammar caching/preparsing - initial implementation. * * Revision 1.1.1.1 2002/02/01 22:22:08 peiyongz * sane_include * * Revision 1.8 2001/05/11 13:26:24 tng * Copyright update. * * Revision 1.7 2001/03/21 21:56:10 tng * Schema: Add Schema Grammar, Schema Validator, and split the DTDValidator into DTDValidator, DTDScanner, and DTDGrammar. * * Revision 1.6 2000/03/02 19:54:35 roddey * This checkin includes many changes done while waiting for the * 1.1.0 code to be finished. I can't list them all here, but a list is * available elsewhere. * * Revision 1.5 2000/02/24 20:12:55 abagchi * Swat for removing Log from API docs * * Revision 1.4 2000/02/12 03:31:55 rahulj * Removed duplicate CVS Log entries. * * Revision 1.3 2000/02/09 01:59:12 abagchi * Removed private function docs, added parse docs * * Revision 1.2 2000/02/06 07:47:58 rahulj * Year 2K copyright swat. * * Revision 1.1.1.1 1999/11/09 01:07:46 twl * Initial checkin * * Revision 1.3 1999/11/08 20:45:02 rahul * Swat for adding in Product name and CVS comment log variable. * */ #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