http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Home

Readme
Download
Installation
Build

API Docs
Samples
Schema

FAQs
Programming
Migration

Releases
Bug-Reporting
Feedback

Y2K Compliance
PDF Document

CVS Repository
Mail Archive

API Docs for SAX and DOM
 

Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

SAXParser.hpp

Go to the documentation of this file.
00001 /*
00002  * The Apache Software License, Version 1.1
00003  *
00004  * Copyright (c) 1999-2001 The Apache Software Foundation.  All rights
00005  * reserved.
00006  *
00007  * Redistribution and use in source and binary forms, with or without
00008  * modification, are permitted provided that the following conditions
00009  * are met:
00010  *
00011  * 1. Redistributions of source code must retain the above copyright
00012  *    notice, this list of conditions and the following disclaimer.
00013  *
00014  * 2. Redistributions in binary form must reproduce the above copyright
00015  *    notice, this list of conditions and the following disclaimer in
00016  *    the documentation and/or other materials provided with the
00017  *    distribution.
00018  *
00019  * 3. The end-user documentation included with the redistribution,
00020  *    if any, must include the following acknowledgment:
00021  *       "This product includes software developed by the
00022  *        Apache Software Foundation (http://www.apache.org/)."
00023  *    Alternately, this acknowledgment may appear in the software itself,
00024  *    if and wherever such third-party acknowledgments normally appear.
00025  *
00026  * 4. The names "Xerces" and "Apache Software Foundation" must
00027  *    not be used to endorse or promote products derived from this
00028  *    software without prior written permission. For written
00029  *    permission, please contact apache\@apache.org.
00030  *
00031  * 5. Products derived from this software may not be called "Apache",
00032  *    nor may "Apache" appear in their name, without prior written
00033  *    permission of the Apache Software Foundation.
00034  *
00035  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
00036  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
00037  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00038  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
00039  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00040  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00041  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
00042  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00043  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00044  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
00045  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00046  * SUCH DAMAGE.
00047  * ====================================================================
00048  *
00049  * This software consists of voluntary contributions made by many
00050  * individuals on behalf of the Apache Software Foundation, and was
00051  * originally based on software copyright (c) 1999, International
00052  * Business Machines, Inc., http://www.ibm.com .  For more information
00053  * on the Apache Software Foundation, please see
00054  * <http://www.apache.org/>.
00055  */
00056 
00057 /*
00058  * $Log: SAXParser.hpp,v $
00059  * Revision 1.2  2002/02/20 18:17:01  tng
00060  * [Bug 5977] Warnings on generating apiDocs.
00061  *
00062  * Revision 1.1.1.1  2002/02/01 22:22:07  peiyongz
00063  * sane_include
00064  *
00065  * Revision 1.22  2001/12/05 22:09:02  tng
00066  * Update documentation for setExternalSchemaLocation and setExternalNoNamespaceSchemaLocation.
00067  *
00068  * Revision 1.21  2001/11/20 18:51:44  tng
00069  * Schema: schemaLocation and noNamespaceSchemaLocation to be specified outside the instance document.  New methods setExternalSchemaLocation and setExternalNoNamespaceSchemaLocation are added (for SAX2, two new properties are added).
00070  *
00071  * Revision 1.20  2001/08/01 19:11:02  tng
00072  * Add full schema constraint checking flag to the samples and the parser.
00073  *
00074  * Revision 1.19  2001/07/27 20:24:21  tng
00075  * put getScanner() back as they were there before, not to break existing apps.
00076  *
00077  * Revision 1.18  2001/07/16 12:52:09  tng
00078  * APIDocs fix: default for schema processing in DOMParser, IDOMParser, and SAXParser should be false.
00079  *
00080  * Revision 1.17  2001/06/23 14:13:16  tng
00081  * Remove getScanner from the Parser headers as this is not needed and Scanner is not internal class.
00082  *
00083  * Revision 1.16  2001/06/03 19:26:20  jberry
00084  * Add support for querying error count following parse; enables simple parse without requiring error handler.
00085  *
00086  * Revision 1.15  2001/05/11 13:26:22  tng
00087  * Copyright update.
00088  *
00089  * Revision 1.14  2001/05/03 19:09:25  knoaman
00090  * Support Warning/Error/FatalError messaging.
00091  * Validity constraints errors are treated as errors, with the ability by user to set
00092  * validity constraints as fatal errors.
00093  *
00094  * Revision 1.13  2001/03/30 16:46:57  tng
00095  * Schema: Use setDoSchema instead of setSchemaValidation which makes more sense.
00096  *
00097  * Revision 1.12  2001/03/21 21:56:09  tng
00098  * Schema: Add Schema Grammar, Schema Validator, and split the DTDValidator into DTDValidator, DTDScanner, and DTDGrammar.
00099  *
00100  * Revision 1.11  2001/02/15 15:56:29  tng
00101  * Schema: Add setSchemaValidation and getSchemaValidation for DOMParser and SAXParser.
00102  * Add feature "http://apache.org/xml/features/validation/schema" for SAX2XMLReader.
00103  * New data field  fSchemaValidation in XMLScanner as the flag.
00104  *
00105  * Revision 1.10  2001/01/12 21:23:41  tng
00106  * Documentation Enhancement: explain values of Val_Scheme
00107  *
00108  * Revision 1.9  2000/08/02 18:05:15  jpolast
00109  * changes required for sax2
00110  * (changed private members to protected)
00111  *
00112  * Revision 1.8  2000/04/12 22:58:30  roddey
00113  * Added support for 'auto validate' mode.
00114  *
00115  * Revision 1.7  2000/03/03 01:29:34  roddey
00116  * Added a scanReset()/parseReset() method to the scanner and
00117  * parsers, to allow for reset after early exit from a progressive parse.
00118  * Added calls to new Terminate() call to all of the samples. Improved
00119  * documentation in SAX and DOM parsers.
00120  *
00121  * Revision 1.6  2000/02/17 03:54:27  rahulj
00122  * Added some new getters to query the parser state and
00123  * clarified the documentation.
00124  *
00125  * Revision 1.5  2000/02/16 03:42:58  rahulj
00126  * Finished documenting the SAX Driver implementation.
00127  *
00128  * Revision 1.4  2000/02/15 04:47:37  rahulj
00129  * Documenting the SAXParser framework. Not done yet.
00130  *
00131  * Revision 1.3  2000/02/06 07:47:56  rahulj
00132  * Year 2K copyright swat.
00133  *
00134  * Revision 1.2  1999/12/15 19:57:48  roddey
00135  * Got rid of redundant 'const' on boolean return value. Some compilers choke
00136  * on this and its useless.
00137  *
00138  * Revision 1.1.1.1  1999/11/09 01:07:51  twl
00139  * Initial checkin
00140  *
00141  * Revision 1.6  1999/11/08 20:44:54  rahul
00142  * Swat for adding in Product name and CVS comment log variable.
00143  *
00144  */
00145 
00146 #if !defined(SAXPARSER_HPP)
00147 #define SAXPARSER_HPP
00148 
00149 #include <xercesc/sax/Parser.hpp>
00150 #include <xercesc/internal/VecAttrListImpl.hpp>
00151 #include <xercesc/framework/XMLDocumentHandler.hpp>
00152 #include <xercesc/framework/XMLElementDecl.hpp>
00153 #include <xercesc/framework/XMLEntityHandler.hpp>
00154 #include <xercesc/framework/XMLErrorReporter.hpp>
00155 #include <xercesc/validators/DTD/DocTypeHandler.hpp>
00156 
00157 class DocumentHandler;
00158 class EntityResolver;
00159 class XMLPScanToken;
00160 class XMLScanner;
00161 class XMLValidator;
00162 
00163 
00173 
00174 class  SAXParser :
00175 
00176     public Parser
00177     , public XMLDocumentHandler
00178     , public XMLErrorReporter
00179     , public XMLEntityHandler
00180     , public DocTypeHandler
00181 {
00182 public :
00183     // -----------------------------------------------------------------------
00184     //  Class types
00185     // -----------------------------------------------------------------------
00186     enum ValSchemes
00187     {
00188         Val_Never
00189         , Val_Always
00190         , Val_Auto
00191     };
00192 
00193 
00194     // -----------------------------------------------------------------------
00195     //  Constructors and Destructor
00196     // -----------------------------------------------------------------------
00197 
00200 
00205     SAXParser(XMLValidator* const valToAdopt = 0);
00206 
00210     ~SAXParser();
00212 
00213 
00216 
00222     DocumentHandler* getDocumentHandler();
00223 
00230     const DocumentHandler* getDocumentHandler() const;
00231 
00238     EntityResolver* getEntityResolver();
00239 
00246     const EntityResolver* getEntityResolver() const;
00247 
00254     ErrorHandler* getErrorHandler();
00255 
00262     const ErrorHandler* getErrorHandler() const;
00263 
00270     const XMLScanner& getScanner() const;
00271 
00278     const XMLValidator& getValidator() const;
00279 
00287     ValSchemes getValidationScheme() const;
00288 
00299     bool getDoSchema() const;
00300 
00311     bool getValidationSchemaFullChecking() const;
00312 
00323     int getErrorCount() const;
00324 
00334     bool getDoNamespaces() const;
00335 
00345     bool getExitOnFirstFatalError() const;
00346 
00357     bool getValidationConstraintFatal() const;
00358 
00378     XMLCh* getExternalSchemaLocation() const;
00379 
00399     XMLCh* getExternalNoNamespaceSchemaLocation() const;
00400 
00402 
00403 
00404     // -----------------------------------------------------------------------
00405     //  Setter methods
00406     // -----------------------------------------------------------------------
00407 
00410 
00427     void setDoNamespaces(const bool newState);
00428 
00445     void setValidationScheme(const ValSchemes newScheme);
00446 
00460     void setDoSchema(const bool newState);
00461 
00478     void setValidationSchemaFullChecking(const bool schemaFullChecking);
00479 
00495     void setExitOnFirstFatalError(const bool newState);
00496 
00512     void setValidationConstraintFatal(const bool newState);
00513 
00533 
00534     void setExternalSchemaLocation(const XMLCh* const schemaLocation);
00535 
00544     void setExternalSchemaLocation(const char* const schemaLocation);
00545 
00560     void setExternalNoNamespaceSchemaLocation(const XMLCh* const noNamespaceSchemaLocation);
00561 
00570     void setExternalNoNamespaceSchemaLocation(const char* const noNamespaceSchemaLocation);
00571 
00573 
00574 
00575     // -----------------------------------------------------------------------
00576     //  Advanced document handler list maintenance methods
00577     // -----------------------------------------------------------------------
00578 
00581 
00594     void installAdvDocHandler(XMLDocumentHandler* const toInstall);
00595 
00605     bool removeAdvDocHandler(XMLDocumentHandler* const toRemove);
00607 
00608 
00609     // -----------------------------------------------------------------------
00610     //  Implementation of the SAXParser interface
00611     // -----------------------------------------------------------------------
00612 
00615 
00627     virtual void parse(const InputSource& source, const bool reuseGrammar = false);
00628 
00641     virtual void parse(const XMLCh* const systemId, const bool reuseGrammar = false);
00642 
00653     virtual void parse(const char* const systemId, const bool reuseGrammar = false);
00654 
00665     virtual void setDocumentHandler(DocumentHandler* const handler);
00666 
00676     virtual void setDTDHandler(DTDHandler* const handler);
00677 
00688     virtual void setErrorHandler(ErrorHandler* const handler);
00689 
00701     virtual void setEntityResolver(EntityResolver* const resolver);
00703 
00704 
00705     // -----------------------------------------------------------------------
00706     //  Progressive scan methods
00707     // -----------------------------------------------------------------------
00708 
00711 
00742     bool parseFirst
00743     (
00744         const   XMLCh* const    systemId
00745         ,       XMLPScanToken&  toFill
00746         , const bool            reuseGrammar = false
00747     );
00748 
00779     bool parseFirst
00780     (
00781         const   char* const     systemId
00782         ,       XMLPScanToken&  toFill
00783         , const bool            reuseGrammar = false
00784     );
00785 
00816     bool parseFirst
00817     (
00818         const   InputSource&    source
00819         ,       XMLPScanToken&  toFill
00820         , const bool            reuseGrammar = false
00821     );
00822 
00847     bool parseNext(XMLPScanToken& token);
00848 
00870     void parseReset(XMLPScanToken& token);
00871 
00873 
00874 
00875 
00876     // -----------------------------------------------------------------------
00877     //  Implementation of the DocTypeHandler Interface
00878     // -----------------------------------------------------------------------
00879 
00882 
00896     virtual void attDef
00897     (
00898         const   DTDElementDecl& elemDecl
00899         , const DTDAttDef&      attDef
00900         , const bool            ignore
00901     );
00902 
00912     virtual void doctypeComment
00913     (
00914         const   XMLCh* const    comment
00915     );
00916 
00933     virtual void doctypeDecl
00934     (
00935         const   DTDElementDecl& elemDecl
00936         , const XMLCh* const    publicId
00937         , const XMLCh* const    systemId
00938         , const bool            hasIntSubset
00939     );
00940 
00954     virtual void doctypePI
00955     (
00956         const   XMLCh* const    target
00957         , const XMLCh* const    data
00958     );
00959 
00971     virtual void doctypeWhitespace
00972     (
00973         const   XMLCh* const    chars
00974         , const unsigned int    length
00975     );
00976 
00989     virtual void elementDecl
00990     (
00991         const   DTDElementDecl& decl
00992         , const bool            isIgnored
00993     );
00994 
01005     virtual void endAttList
01006     (
01007         const   DTDElementDecl& elemDecl
01008     );
01009 
01016     virtual void endIntSubset();
01017 
01024     virtual void endExtSubset();
01025 
01040     virtual void entityDecl
01041     (
01042         const   DTDEntityDecl&  entityDecl
01043         , const bool            isPEDecl
01044         , const bool            isIgnored
01045     );
01046 
01051     virtual void resetDocType();
01052 
01065     virtual void notationDecl
01066     (
01067         const   XMLNotationDecl&    notDecl
01068         , const bool                isIgnored
01069     );
01070 
01081     virtual void startAttList
01082     (
01083         const   DTDElementDecl& elemDecl
01084     );
01085 
01092     virtual void startIntSubset();
01093 
01100     virtual void startExtSubset();
01101 
01114     virtual void TextDecl
01115     (
01116         const   XMLCh* const    versionStr
01117         , const XMLCh* const    encodingStr
01118     );
01120 
01121 
01122     // -----------------------------------------------------------------------
01123     //  Implementation of the XMLDocumentHandler interface
01124     // -----------------------------------------------------------------------
01125 
01128 
01143     virtual void docCharacters
01144     (
01145         const   XMLCh* const    chars
01146         , const unsigned int    length
01147         , const bool            cdataSection
01148     );
01149 
01159     virtual void docComment
01160     (
01161         const   XMLCh* const    comment
01162     );
01163 
01183     virtual void docPI
01184     (
01185         const   XMLCh* const    target
01186         , const XMLCh* const    data
01187     );
01188 
01200     virtual void endDocument();
01201 
01218     virtual void endElement
01219     (
01220         const   XMLElementDecl& elemDecl
01221         , const unsigned int    urlId
01222         , const bool            isRoot
01223     );
01224 
01235     virtual void endEntityReference
01236     (
01237         const   XMLEntityDecl&  entDecl
01238     );
01239 
01259     virtual void ignorableWhitespace
01260     (
01261         const   XMLCh* const    chars
01262         , const unsigned int    length
01263         , const bool            cdataSection
01264     );
01265 
01270     virtual void resetDocument();
01271 
01282     virtual void startDocument();
01283 
01310     virtual void startElement
01311     (
01312         const   XMLElementDecl&         elemDecl
01313         , const unsigned int            urlId
01314         , const XMLCh* const            elemPrefix
01315         , const RefVectorOf<XMLAttr>&   attrList
01316         , const unsigned int            attrCount
01317         , const bool                    isEmpty
01318         , const bool                    isRoot
01319     );
01320 
01330     virtual void startEntityReference
01331     (
01332         const   XMLEntityDecl&  entDecl
01333     );
01334 
01352     virtual void XMLDecl
01353     (
01354         const   XMLCh* const    versionStr
01355         , const XMLCh* const    encodingStr
01356         , const XMLCh* const    standaloneStr
01357         , const XMLCh* const    actualEncodingStr
01358     );
01360 
01361 
01362     // -----------------------------------------------------------------------
01363     //  Implementation of the XMLErrorReporter interface
01364     // -----------------------------------------------------------------------
01365 
01368 
01391     virtual void error
01392     (
01393         const   unsigned int                errCode
01394         , const XMLCh* const                msgDomain
01395         , const XMLErrorReporter::ErrTypes  errType
01396         , const XMLCh* const                errorText
01397         , const XMLCh* const                systemId
01398         , const XMLCh* const                publicId
01399         , const unsigned int                lineNum
01400         , const unsigned int                colNum
01401     );
01402 
01411     virtual void resetErrors();
01413 
01414 
01415     // -----------------------------------------------------------------------
01416     //  Implementation of the XMLEntityHandler interface
01417     // -----------------------------------------------------------------------
01418 
01421 
01432     virtual void endInputSource(const InputSource& inputSource);
01433 
01448     virtual bool expandSystemId
01449     (
01450         const   XMLCh* const    systemId
01451         ,       XMLBuffer&      toFill
01452     );
01453 
01461     virtual void resetEntities();
01462 
01477     virtual InputSource* resolveEntity
01478     (
01479         const   XMLCh* const    publicId
01480         , const XMLCh* const    systemId
01481     );
01482 
01494     virtual void startInputSource(const InputSource& inputSource);
01496 
01497 
01500 
01510     bool getDoValidation() const;
01511 
01525     void setDoValidation(const bool newState);
01527 
01528 
01529 protected :
01530     // -----------------------------------------------------------------------
01531     //  Unimplemented constructors and operators
01532     // -----------------------------------------------------------------------
01533     SAXParser(const SAXParser&);
01534     void operator=(const SAXParser&);
01535 
01536 
01537     // -----------------------------------------------------------------------
01538     //  Private data members
01539     //
01540     //  fAttrList
01541     //      A temporary implementation of the basic SAX attribute list
01542     //      interface. We use this one over and over on each startElement
01543     //      event to allow SAX-like access to the element attributes.
01544     //
01545     //  fDocHandler
01546     //      The installed SAX doc handler, if any. Null if none.
01547     //
01548     //  fDTDHandler
01549     //      The installed SAX DTD handler, if any. Null if none.
01550     //
01551     //  fElemDepth
01552     //      This is used to track the element nesting depth, so that we can
01553     //      know when we are inside content. This is so we can ignore char
01554     //      data outside of content.
01555     //
01556     //  fEntityResolver
01557     //      The installed SAX entity handler, if any. Null if none.
01558     //
01559     //  fErrorHandler
01560     //      The installed SAX error handler, if any. Null if none.
01561     //
01562     //  fAdvDHCount
01563     //  fAdvDHList
01564     //  fAdvDHListSize
01565     //      This is an array of pointers to XMLDocumentHandlers, which is
01566     //      how we see installed advanced document handlers. There will
01567     //      usually not be very many at all, so a simple array is used
01568     //      instead of a collection, for performance. It will grow if needed,
01569     //      but that is unlikely.
01570     //
01571     //      The count is how many handlers are currently installed. The size
01572     //      is how big the array itself is (for expansion purposes.) When
01573     //      count == size, is time to expand.
01574     //
01575     //  fParseInProgress
01576     //      This flag is set once a parse starts. It is used to prevent
01577     //      multiple entrance or reentrance of the parser.
01578     //
01579     //  fScanner
01580     //      The scanner being used by this parser. It is created internally
01581     //      during construction.
01582     //
01583     // -----------------------------------------------------------------------
01584     VecAttrListImpl         fAttrList;
01585     DocumentHandler*        fDocHandler;
01586     DTDHandler*             fDTDHandler;
01587     unsigned int            fElemDepth;
01588     EntityResolver*         fEntityResolver;
01589     ErrorHandler*           fErrorHandler;
01590     unsigned int            fAdvDHCount;
01591     XMLDocumentHandler**    fAdvDHList;
01592     unsigned int            fAdvDHListSize;
01593     bool                    fParseInProgress;
01594     XMLScanner*             fScanner;
01595 };
01596 
01597 
01598 // ---------------------------------------------------------------------------
01599 //  SAXParser: Getter methods
01600 // ---------------------------------------------------------------------------
01601 inline DocumentHandler* SAXParser::getDocumentHandler()
01602 {
01603     return fDocHandler;
01604 }
01605 
01606 inline const DocumentHandler* SAXParser::getDocumentHandler() const
01607 {
01608     return fDocHandler;
01609 }
01610 
01611 inline EntityResolver* SAXParser::getEntityResolver()
01612 {
01613     return fEntityResolver;
01614 }
01615 
01616 inline const EntityResolver* SAXParser::getEntityResolver() const
01617 {
01618     return fEntityResolver;
01619 }
01620 
01621 inline ErrorHandler* SAXParser::getErrorHandler()
01622 {
01623     return fErrorHandler;
01624 }
01625 
01626 inline const ErrorHandler* SAXParser::getErrorHandler() const
01627 {
01628     return fErrorHandler;
01629 }
01630 
01631 inline const XMLScanner& SAXParser::getScanner() const
01632 {
01633     return *fScanner;
01634 }
01635 
01636 #endif


Copyright © 2000 The Apache Software Foundation. All Rights Reserved.