source: icXML/icXML-devel/src/icxercesc/parsers/SAXParser.hpp @ 3104

Last change on this file since 3104 was 3104, checked in by cameron, 6 years ago

Additional files for icXML 0.9

File size: 73.9 KB
Line 
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/*
19 * $Id: SAXParser.hpp 932887 2010-04-11 13:04:59Z borisk $
20 */
21
22#if !defined(XERCESC_INCLUDE_GUARD_SAXPARSER_HPP)
23#define XERCESC_INCLUDE_GUARD_SAXPARSER_HPP
24
25#include <xercesc/sax/Parser.hpp>
26#include <xercesc/internal/VecAttrListImpl.hpp>
27#include <icxercesc/framework/XMLDocumentHandler.hpp>
28#include <icxercesc/framework/XMLElementDecl.hpp>
29#include <xercesc/framework/XMLEntityHandler.hpp>
30#include <xercesc/framework/XMLErrorReporter.hpp>
31#include <icxercesc/framework/XMLBuffer.hpp>
32#include <xercesc/util/SecurityManager.hpp>
33#include <icxercesc/validators/common/Grammar.hpp>
34#include <xercesc/validators/DTD/DocTypeHandler.hpp>
35#include <icxmlc/XMLConfig.hpp>
36#ifdef TEST_NAMESPACE_RESOLVER
37#include <icxmlc/XMLNamespaceResolver.hpp>
38#endif
39
40XERCES_CPP_NAMESPACE_BEGIN
41
42
43class DocumentHandler;
44class EntityResolver;
45class XMLPScanToken;
46class XMLScanner;
47class XMLValidator;
48class GrammarResolver;
49class XMLGrammarPool;
50class XMLEntityResolver;
51class XMLResourceIdentifier;
52class PSVIHandler;
53
54/**
55  * This class implements the SAX 'Parser' interface and should be
56  * used by applications wishing to parse the XML files using SAX.
57  * It allows the client program to install SAX handlers for event
58  * callbacks.
59  *
60  * <p>It can be used to instantiate a validating or non-validating
61  * parser, by setting a member flag.</p>
62  *
63  * @deprecated This interface has been replaced by the SAX2
64  *             interface, which includes Namespace support.
65  *             See SAX2XMLReader for more information.
66  *
67  * Note - XMLDocumentHandler calls, when used with SAXParser, will not provide correct namespace information. This is becaue the SAX parser does not support namespace aware processing.
68  *
69  *
70  */
71
72class PARSERS_EXPORT SAXParser :
73
74        public XMemory
75        , public Parser
76        , public XMLDocumentHandler
77        , public XMLErrorReporter
78        , public XMLEntityHandler
79        , public DocTypeHandler
80{
81public :
82        // -----------------------------------------------------------------------
83        //  Class types
84        // -----------------------------------------------------------------------
85        /** ValScheme enum used in setValidationScheme
86          *    Val_Never:  Do not report validation errors.
87          *    Val_Always: The parser will always report validation errors.
88          *    Val_Auto:   The parser will report validation errors only if a grammar is specified.
89          *
90          * @see #setValidationScheme
91          */
92
93        enum ValSchemes
94        {
95                Val_Never
96                , Val_Always
97                , Val_Auto
98        };
99
100
101        // -----------------------------------------------------------------------
102        //  Constructors and Destructor
103        // -----------------------------------------------------------------------
104        /** @name Constructors and Destructor */
105        //@{
106        /** Constructor with an instance of validator class to use for
107          * validation.
108          * @param valToAdopt Pointer to the validator instance to use. The
109          *                   parser is responsible for freeing the memory.
110          * @param manager    Pointer to the memory manager to be used to
111          *                   allocate objects.
112          * @param gramPool   The collection of cached grammars.
113          */
114        SAXParser
115        (
116                  XMLValidator*   const valToAdopt = 0
117                , MemoryManager*  const manager = XMLPlatformUtils::fgMemoryManager
118                , XMLGrammarPool* const gramPool = 0
119        );
120
121        /**
122          * Destructor
123          */
124        ~SAXParser();
125        //@}
126
127
128        // -----------------------------------------------------------------------
129        //  Getter Methods
130        // -----------------------------------------------------------------------
131        /** @name Getter methods */
132        //@{
133        /**
134          * This method returns the installed document handler. Suitable
135          * for 'lvalue' usages.
136          *
137          * @return The pointer to the installed document handler object.
138          */
139        DocumentHandler* getDocumentHandler();
140
141        /**
142          * This method returns the installed document handler. Suitable
143          * only for 'rvalue' usages.
144          *
145          * @return A const pointer to the installed document handler object.
146          */
147        const DocumentHandler* getDocumentHandler() const;
148
149        /**
150          * This method returns the installed entity resolver. Suitable
151          * for 'lvalue' usages.
152          *
153          * @return The pointer to the installed entity resolver object.
154          */
155        EntityResolver* getEntityResolver();
156
157        /**
158          * This method returns the installed entity resolver. Suitable
159          * for 'rvalue' usages.
160          *
161          * @return A const pointer to the installed entity resolver object.
162          */
163        const EntityResolver* getEntityResolver() const;
164
165        /**
166          * This method returns the installed entity resolver. Suitable
167          * for 'lvalue' usages.
168          *
169          * @return The pointer to the installed entity resolver object.
170          */
171        XMLEntityResolver* getXMLEntityResolver();
172
173        /**
174          * This method returns the installed entity resolver. Suitable
175          * for 'rvalue' usages.
176          *
177          * @return A const pointer to the installed entity resolver object.
178          */
179        const XMLEntityResolver* getXMLEntityResolver() const;
180
181        /**
182          * This method returns the installed error handler. Suitable
183          * for 'lvalue' usages.
184          *
185          * @return The pointer to the installed error handler object.
186          */
187        ErrorHandler* getErrorHandler();
188
189        /**
190          * This method returns the installed error handler. Suitable
191          * for 'rvalue' usages.
192          *
193          * @return A const pointer to the installed error handler object.
194          */
195        const ErrorHandler* getErrorHandler() const;
196
197        /**
198          * This method returns the installed PSVI handler. Suitable
199          * for 'lvalue' usages.
200          *
201          * @return The pointer to the installed PSVI handler object.
202          */
203        PSVIHandler* getPSVIHandler();
204
205        /**
206          * This method returns the installed PSVI handler. Suitable
207          * for 'rvalue' usages.
208          *
209          * @return A const pointer to the installed PSVI handler object.
210          */
211        const PSVIHandler* getPSVIHandler() const;
212
213        /**
214          * This method returns a reference to the parser's installed
215          * validator.
216          *
217          * @return A const reference to the installed validator object.
218          */
219        const XMLValidator& getValidator() const;
220
221        /**
222          * This method returns an enumerated value that indicates the current
223          * validation scheme set on this parser.
224          *
225          * @return The ValSchemes value current set on this parser.
226          * @see #setValidationScheme
227          */
228        ValSchemes getValidationScheme() const;
229
230        /** Get the 'do schema' flag
231          *
232          * This method returns the state of the parser's schema processing
233          * flag.
234          *
235          * @return true, if the parser is currently configured to
236          *         understand schema, false otherwise.
237          *
238          * @see #setDoSchema
239          */
240        bool getDoSchema() const;
241
242        /** Get the 'full schema constraint checking' flag
243          *
244          * This method returns the state of the parser's full schema constraint
245          * checking flag.
246          *
247          * @return true, if the parser is currently configured to
248          *         have full schema constraint checking, false otherwise.
249          *
250          * @see #setValidationSchemaFullChecking
251          */
252        bool getValidationSchemaFullChecking() const;
253
254        /** Get the 'identity constraint checking' flag
255          *
256          * This method returns the state of the parser's identity constraint
257          * checking flag.
258          *
259          * @return true, if the parser is currently configured to
260          *         have identity constraint checking, false otherwise.
261          *
262          * @see #setIdentityConstraintChecking
263          */
264        bool getIdentityConstraintChecking() const;
265
266        /** Get error count from the last parse operation.
267          *
268          * This method returns the error count from the last parse
269          * operation. Note that this count is actually stored in the
270          * scanner, so this method simply returns what the
271          * scanner reports.
272          *
273          * @return number of errors encountered during the latest
274          *                     parse operation.
275          */
276        int getErrorCount() const;
277
278        /**
279          * This method returns the state of the parser's namespace
280          * handling capability.
281          *
282          * @return true, if the parser is currently configured to
283          *         understand namespaces, false otherwise.
284          *
285          * @see #setDoNamespaces
286          */
287        bool getDoNamespaces() const;
288
289        /**
290          * This method returns the state of the parser's
291          * exit-on-First-Fatal-Error flag.
292          *
293          * @return true, if the parser is currently configured to
294          *         exit on the first fatal error, false otherwise.
295          *
296          * @see #setExitOnFirstFatalError
297          */
298        bool getExitOnFirstFatalError() const;
299
300        /**
301          * This method returns the state of the parser's
302          * validation-constraint-fatal flag.
303          *
304          * @return true, if the parser is currently configured to
305          *         set validation constraint errors as fatal, false
306          *         otherwise.
307          *
308          * @see #setValidationConstraintFatal
309          */
310        bool getValidationConstraintFatal() const;
311
312   /** Get the set of Namespace/SchemaLocation that is specified externally.
313          *
314          * This method returns the list of Namespace/SchemaLocation that was
315          * specified using setExternalSchemaLocation.
316          *
317          * The parser owns the returned string, and the memory allocated for
318          * the returned string will be destroyed when the parser is deleted.
319          *
320          * To ensure accessibility of the returned information after the parser
321          * is deleted, callers need to copy and store the returned information
322          * somewhere else.
323          *
324          * @return a pointer to the list of Namespace/SchemaLocation that was
325          *         specified externally.  The pointer spans the same life-time as
326          *         the parser.  A null pointer is returned if nothing
327          *         was specified externally.
328          *
329          * @see #setExternalSchemaLocation(const XMLCh* const)
330          */
331        XMLCh* getExternalSchemaLocation() const;
332
333   /** Get the noNamespace SchemaLocation that is specified externally.
334          *
335          * This method returns the no target namespace XML Schema Location
336          * that was specified using setExternalNoNamespaceSchemaLocation.
337          *
338          * The parser owns the returned string, and the memory allocated for
339          * the returned string will be destroyed when the parser is deleted.
340          *
341          * To ensure accessibility of the returned information after the parser
342          * is deleted, callers need to copy and store the returned information
343          * somewhere else.
344          *
345          * @return a pointer to the no target namespace Schema Location that was
346          *         specified externally.  The pointer spans the same life-time as
347          *         the parser.  A null pointer is returned if nothing
348          *         was specified externally.
349          *
350          * @see #setExternalNoNamespaceSchemaLocation(const XMLCh* const)
351          */
352        XMLCh* getExternalNoNamespaceSchemaLocation() const;
353
354   /** Get the SecurityManager instance attached to this parser.
355          *
356          * This method returns the security manager
357          * that was specified using setSecurityManager.
358          *
359          * The SecurityManager instance must have been specified by the application;
360          * this should not be deleted until after the parser has been deleted (or
361          * a new SecurityManager instance has been supplied to the parser).
362          *
363          * @return a pointer to the SecurityManager instance
364          *         specified externally.  A null pointer is returned if nothing
365          *         was specified externally.
366          *
367          * @see #setSecurityManager(SecurityManager* const)
368          */
369        SecurityManager* getSecurityManager() const;
370
371        /** Get the raw buffer low water mark for this parser.
372          *
373          * If the number of available bytes in the raw buffer is less than
374          * the low water mark the parser will attempt to read more data before
375          * continuing parsing. By default the value for this parameter is 100
376          * bytes. You may want to set this parameter to 0 if you would like
377          * the parser to parse the available data immediately without
378          * potentially blocking while waiting for more date.
379          *
380          * @return current low water mark
381          *
382          * @see #setSecurityManager
383          */
384        XMLSize_t getLowWaterMark() const;
385
386        /** Get the 'Loading External DTD' flag
387          *
388          * This method returns the state of the parser's loading external DTD
389          * flag.
390          *
391          * @return false, if the parser is currently configured to
392          *         ignore external DTD completely, true otherwise.
393          *
394          * @see #setLoadExternalDTD
395          * @see #getValidationScheme
396          */
397        bool getLoadExternalDTD() const;
398
399        /** Get the 'Loading Schema' flag
400          *
401          * This method returns the state of the parser's loading schema
402          * flag.
403          *
404          * @return true, if the parser is currently configured to
405          *         automatically load schemas that are not in the
406          *         grammar pool, false otherwise.
407          *
408          * @see #setLoadSchema
409          */
410        bool getLoadSchema() const;
411
412        /** Get the 'Grammar caching' flag
413          *
414          * This method returns the state of the parser's grammar caching when
415          * parsing an XML document.
416          *
417          * @return true, if the parser is currently configured to
418          *         cache grammars, false otherwise.
419          *
420          * @see #cacheGrammarFromParse
421          */
422        bool isCachingGrammarFromParse() const;
423
424        /** Get the 'Use cached grammar' flag
425          *
426          * This method returns the state of the parser's use of cached grammar
427          * when parsing an XML document.
428          *
429          * @return true, if the parser is currently configured to
430          *         use cached grammars, false otherwise.
431          *
432          * @see #useCachedGrammarInParse
433          */
434        bool isUsingCachedGrammarInParse() const;
435
436        /**
437          * Get the 'calculate src offset flag'
438          *
439          * This method returns the state of the parser's src offset calculation
440          * when parsing an XML document.
441          *
442          * @return true, if the parser is currently configured to
443          *         calculate src offsets, false otherwise.
444          *
445          * @see #setCalculateSrcOfs
446          */
447        bool getCalculateSrcOfs() const;
448
449        /**
450          * Get the 'force standard uri flag'
451          *
452          * This method returns the state if the parser forces standard uri
453          *
454          * @return true, if the parser is currently configured to
455          *         force standard uri, i.e. malformed uri will be rejected.
456          *
457          * @see #setStandardUriConformant
458          */
459        bool getStandardUriConformant() const;
460
461        /**
462         * Retrieve the grammar that is associated with the specified namespace key
463         *
464         * @param  nameSpaceKey Namespace key
465         * @return Grammar associated with the Namespace key.
466         */
467        Grammar* getGrammar(const XMLCh* const nameSpaceKey);
468
469        /**
470         * Retrieve the grammar where the root element is declared.
471         *
472         * @return Grammar where root element declared
473         */
474        Grammar* getRootGrammar();
475
476        /**
477         * Returns the string corresponding to a URI id from the URI string pool.
478         *
479         * @param uriId id of the string in the URI string pool.
480         * @return URI string corresponding to the URI id.
481         */
482        const XMLCh* getURIText(unsigned int uriId) const;
483
484        /**
485         * Returns the current src offset within the input source.
486         * To be used only while parsing is in progress.
487         *
488         * @return offset within the input source
489         */
490        XMLFilePos getSrcOffset() const;
491
492        /** Get the 'generate synthetic annotations' flag
493          *
494          * @return true, if the parser is currently configured to
495          *         generate synthetic annotations, false otherwise.
496          *         A synthetic XSAnnotation is created when a schema
497          *         component has non-schema attributes but has no
498          *         child annotations so that the non-schema attributes
499          *         can be recovered under PSVI.
500          *
501          * @see #setGenerateSyntheticAnnotations
502          */
503        bool getGenerateSyntheticAnnotations() const;
504
505        /** Get the 'validate annotations' flag
506          *
507          * @return true, if the parser is currently configured to
508          *         validate annotations, false otherwise.
509          *
510          * @see #setValidateAnnotations
511          */
512        bool getValidateAnnotations() const;
513
514        /** Get the 'ignore cached DTD grammar' flag
515          *
516          * @return true, if the parser is currently configured to
517          *         ignore cached DTD, false otherwise.
518          *
519          * @see #setIgnoreCachedDTD
520          */
521        bool getIgnoreCachedDTD() const;
522
523        /** Get the 'ignore annotations' flag
524          *
525          * @return true, if the parser is currently configured to
526          *         ignore annotations, false otherwise.
527          *
528          * @see #setIgnoreAnnotations
529          */
530        bool getIgnoreAnnotations() const;
531
532        /** Get the 'disable default entity resolution' flag
533          *
534          * @return true, if the parser is currently configured to
535          *         not perform default entity resolution, false otherwise.
536          *
537          * @see #setDisableDefaultEntityResolution
538          */
539        bool getDisableDefaultEntityResolution() const;
540
541        /** Get the 'skip DTD validation' flag
542          *
543          * @return true, if the parser is currently configured to
544          *         skip DTD validation, false otherwise.
545          *
546          * @see #setSkipDTDValidation
547          */
548        bool getSkipDTDValidation() const;
549
550        /** Get the 'handle multiple schema imports' flag
551          *
552          * @return true, if the parser is currently configured to
553          *         import multiple schemas with the same namespace, false otherwise.
554          *
555          * @see #setHandleMultipleImports
556          */
557        bool getHandleMultipleImports() const;
558        //@}
559
560
561        // -----------------------------------------------------------------------
562        //  Setter methods
563        // -----------------------------------------------------------------------
564
565        /** @name Setter methods */
566        //@{
567        /** set the 'generate synthetic annotations' flag
568          *
569          * @param newValue The value for specifying whether Synthetic Annotations
570          *        should be generated or not.
571          *        A synthetic XSAnnotation is created when a schema
572          *        component has non-schema attributes but has no
573          *        child annotations.
574          *
575          * @see #getGenerateSyntheticAnnotations
576          */
577        void setGenerateSyntheticAnnotations(const bool newValue);
578
579        /** set the 'validate annotations' flag
580          *
581          * @param newValue The value for specifying whether annotations
582          *        should be validate or not.
583          *
584          * @see #getValidateAnnotations
585          */
586        void setValidateAnnotations(const bool newValue);
587
588        /**
589          * This method allows users to enable or disable the parser's
590          * namespace processing. When set to true, parser starts enforcing
591          * all the constraints / rules specified by the NameSpace
592          * specification.
593          *
594          * <p>The parser's default state is: false.</p>
595          *
596          * @param newState The value specifying whether NameSpace rules should
597          *                 be enforced or not.
598          *
599          * @see #getDoNamespaces
600          */
601        void setDoNamespaces(const bool newState);
602
603        /**
604          * This method allows users to set the validation scheme to be used
605          * by this parser. The value is one of the ValSchemes enumerated values
606          * defined by this class:
607          *
608          * <br>  Val_Never  - turn off validation
609          * <br>  Val_Always - turn on validation
610          * <br>  Val_Auto   - turn on validation if any internal/external
611          *                  DTD subset have been seen
612          *
613          * <p>The parser's default state is: Val_Never.</p>
614          *
615          * @param newScheme The new validation scheme to use.
616          *
617          * @see #getValidationScheme
618          */
619        void setValidationScheme(const ValSchemes newScheme);
620
621        /** Set the 'schema support' flag
622          *
623          * This method allows users to enable or disable the parser's
624          * schema processing. When set to false, parser will not process
625          * any schema found.
626          *
627          * The parser's default state is: false.
628          *
629          * Note: If set to true, namespace processing must also be turned on.
630          *
631          * @param newState The value specifying whether schema support should
632          *                 be enforced or not.
633          *
634          * @see #getDoSchema
635          */
636        void setDoSchema(const bool newState);
637
638        /**
639          * This method allows the user to turn full Schema constraint checking on/off.
640          * Only takes effect if Schema validation is enabled.
641          * If turned off, partial constraint checking is done.
642          *
643          * Full schema constraint checking includes those checking that may
644          * be time-consuming or memory intensive. Currently, particle unique
645          * attribution constraint checking and particle derivation restriction checking
646          * are controlled by this option.
647          *
648          * The parser's default state is: false.
649          *
650          * @param schemaFullChecking True to turn on full schema constraint checking.
651          *
652          * @see #getValidationSchemaFullChecking
653          */
654        void setValidationSchemaFullChecking(const bool schemaFullChecking);
655
656        /**
657          * This method allows the user to turn identity constraint checking on/off.
658          * Only takes effect if Schema validation is enabled.
659          * If turned off, identity constraint checking is not done.
660          *
661          * The parser's default state is: true.
662          *
663          * @param identityConstraintChecking True to turn on identity constraint checking.
664          *
665          * @see #getIdentityConstraintChecking
666          */
667        void setIdentityConstraintChecking(const bool identityConstraintChecking);
668
669        /**
670          * This method allows users to set the parser's behaviour when it
671          * encounters the first fatal error. If set to true, the parser
672          * will exit at the first fatal error. If false, then it will
673          * report the error and continue processing.
674          *
675          * <p>The default value is 'true' and the parser exits on the
676          * first fatal error.</p>
677          *
678          * @param newState The value specifying whether the parser should
679          *                 continue or exit when it encounters the first
680          *                 fatal error.
681          *
682          * @see #getExitOnFirstFatalError
683          */
684        void setExitOnFirstFatalError(const bool newState);
685
686        /**
687          * This method allows users to set the parser's behaviour when it
688          * encounters a validation constraint error. If set to true, and the
689          * the parser will treat validation error as fatal and will exit depends on the
690          * state of "getExitOnFirstFatalError". If false, then it will
691          * report the error and continue processing.
692          *
693          * Note: setting this true does not mean the validation error will be printed with
694          * the word "Fatal Error".   It is still printed as "Error", but the parser
695          * will exit if "setExitOnFirstFatalError" is set to true.
696          *
697          * <p>The default value is 'false'.</p>
698          *
699          * @param newState If true, the parser will exit if "setExitOnFirstFatalError"
700          *                 is set to true.
701          *
702          * @see #getValidationConstraintFatal
703          * @see #setExitOnFirstFatalError
704          */
705        void setValidationConstraintFatal(const bool newState);
706
707        /**
708          * This method allows the user to specify a list of schemas to use.
709          * If the targetNamespace of a schema specified using this method matches
710          * the targetNamespace of a schema occurring in the instance document in
711          * the schemaLocation attribute, or if the targetNamespace matches the
712          * namespace attribute of the "import" element, the schema specified by the
713          * user using this method will be used (i.e., the schemaLocation attribute
714          * in the instance document or on the "import" element will be effectively ignored).
715          *
716          * If this method is called more than once, only the last one takes effect.
717          *
718          * The syntax is the same as for schemaLocation attributes in instance
719          * documents: e.g, "http://www.example.com file_name.xsd". The user can
720          * specify more than one XML Schema in the list.
721          *
722          * @param schemaLocation the list of schemas to use
723          *
724          * @see #getExternalSchemaLocation
725          */
726
727        void setExternalSchemaLocation(const XMLCh* const schemaLocation);
728
729        /**
730          * This method is same as setExternalSchemaLocation(const XMLCh* const).
731          * It takes native char string as parameter
732          *
733          * @param schemaLocation the list of schemas to use
734          *
735          * @see #setExternalSchemaLocation(const XMLCh* const)
736          */
737        void setExternalSchemaLocation(const char* const schemaLocation);
738
739        /**
740          * This method allows the user to specify the no target namespace XML
741          * Schema Location externally.  If specified, the instance document's
742          * noNamespaceSchemaLocation attribute will be effectively ignored.
743          *
744          * If this method is called more than once, only the last one takes effect.
745          *
746          * The syntax is the same as for the noNamespaceSchemaLocation attribute
747          * that may occur in an instance document: e.g."file_name.xsd".
748          *
749          * @param noNamespaceSchemaLocation the XML Schema Location with no target namespace
750          *
751          * @see #getExternalNoNamespaceSchemaLocation
752          */
753        void setExternalNoNamespaceSchemaLocation(const XMLCh* const noNamespaceSchemaLocation);
754
755        /**
756          * This method is same as setExternalNoNamespaceSchemaLocation(const XMLCh* const).
757          * It takes native char string as parameter
758          *
759          * @param noNamespaceSchemaLocation the XML Schema Location with no target namespace
760          *
761          * @see #setExternalNoNamespaceSchemaLocation(const XMLCh* const)
762          */
763        void setExternalNoNamespaceSchemaLocation(const char* const noNamespaceSchemaLocation);
764
765        /**
766          * This allows an application to set a SecurityManager on
767          * the parser; this object stores information that various
768          * components use to limit their consumption of system
769          * resources while processing documents.
770          *
771          * If this method is called more than once, only the last one takes effect.
772          * It may not be reset during a parse.
773          *
774          *
775          * @param securityManager  the SecurityManager instance to
776          * be used by this parser
777          *
778          * @see #getSecurityManager
779          */
780        void setSecurityManager(SecurityManager* const securityManager);
781
782        /** Set the raw buffer low water mark for this parser.
783          *
784          * If the number of available bytes in the raw buffer is less than
785          * the low water mark the parser will attempt to read more data before
786          * continuing parsing. By default the value for this parameter is 100
787          * bytes. You may want to set this parameter to 0 if you would like
788          * the parser to parse the available data immediately without
789          * potentially blocking while waiting for more date.
790          *
791          * @param lwm new low water mark
792          *
793          * @see #getSecurityManager
794          */
795        void setLowWaterMark(XMLSize_t lwm);
796
797        /** Set the 'Loading External DTD' flag
798          *
799          * This method allows users to enable or disable the loading of external DTD.
800          * When set to false, the parser will ignore any external DTD completely
801          * if the validationScheme is set to Val_Never.
802          *
803          * The parser's default state is: true.
804          *
805          * This flag is ignored if the validationScheme is set to Val_Always or Val_Auto.
806          *
807          * @param newState The value specifying whether external DTD should
808          *                 be loaded or not.
809          *
810          * @see #getLoadExternalDTD
811          * @see #setValidationScheme
812          */
813        void setLoadExternalDTD(const bool newState);
814
815        /** Set the 'Loading Schema' flag
816          *
817          * This method allows users to enable or disable the loading of schemas.
818          * When set to false, the parser not attempt to load schemas beyond
819          * querying the grammar pool for them.
820          *
821          * The parser's default state is: true.
822          *
823          * @param newState The value specifying whether schemas should
824          *                 be loaded if they're not found in the grammar
825          *                 pool.
826          *
827          * @see #getLoadSchema
828          * @see #setDoSchema
829          */
830        void setLoadSchema(const bool newState);
831
832        /** Set the 'Grammar caching' flag
833          *
834          * This method allows users to enable or disable caching of grammar when
835          * parsing XML documents. When set to true, the parser will cache the
836          * resulting grammar for use in subsequent parses.
837          *
838          * If the flag is set to true, the 'Use cached grammar' flag will also be
839          * set to true.
840          *
841          * The parser's default state is: false.
842          *
843          * @param newState The value specifying whether we should cache grammars
844          *                 or not.
845          *
846          * @see #isCachingGrammarFromParse
847          * @see #useCachedGrammarInParse
848          */
849        void cacheGrammarFromParse(const bool newState);
850
851        /** Set the 'Use cached grammar' flag
852          *
853          * This method allows users to enable or disable the use of cached
854          * grammars.  When set to true, the parser will use the cached grammar,
855          * instead of building the grammar from scratch, to validate XML
856          * documents.
857          *
858          * If the 'Grammar caching' flag is set to true, this method ignores the
859          * value passed in.
860          *
861          * The parser's default state is: false.
862          *
863          * @param newState The value specifying whether we should use the cached
864          *                 grammar or not.
865          *
866          * @see #isUsingCachedGrammarInParse
867          * @see #cacheGrammarFromParse
868          */
869        void useCachedGrammarInParse(const bool newState);
870
871        /** Enable/disable src offset calculation
872          *
873          * This method allows users to enable/disable src offset calculation.
874          * Disabling the calculation will improve performance.
875          *
876          * The parser's default state is: false.
877          *
878          * @param newState The value specifying whether we should enable or
879          *                 disable src offset calculation
880          *
881          * @see #getCalculateSrcOfs
882          */
883        void setCalculateSrcOfs(const bool newState);
884
885        /** Force standard uri
886          *
887          * This method allows users to tell the parser to force standard uri conformance.
888          *
889          * The parser's default state is: false.
890          *
891          * @param newState The value specifying whether the parser should reject malformed URI.
892          *
893          * @see #getStandardUriConformant
894          */
895        void setStandardUriConformant(const bool newState);
896
897        /** Set the scanner to use when scanning the XML document
898          *
899          * This method allows users to set the scanner to use
900          * when scanning a given XML document.
901          *
902          * @param scannerName The name of the desired scanner
903          */
904        void useScanner(const XMLCh* const scannerName);
905
906        /** Set maximum input buffer size
907          *
908          * This method allows users to limit the size of buffers used in parsing
909          * XML character data. The effect of setting this size is to limit the
910          * size of a ContentHandler::characters() call.
911          *
912          * The parser's default input buffer size is 1 megabyte.
913          *
914          * @param bufferSize The maximum input buffer size
915          */
916        void setInputBufferSize(const XMLSize_t bufferSize);
917
918        /** Set the 'ignore cached DTD grammar' flag
919          *
920          * This method gives users the option to ignore a cached DTD grammar, when
921          * an XML document contains both an internal and external DTD, and the use
922          * cached grammar from parse option is enabled. Currently, we do not allow
923          * using cached DTD grammar when an internal subset is present in the
924          * document. This option will only affect the behavior of the parser when
925          * an internal and external DTD both exist in a document (i.e. no effect
926          * if document has no internal subset).
927          *
928          * The parser's default state is false
929          *
930          * @param newValue The state to set
931          */
932        void setIgnoreCachedDTD(const bool newValue);
933
934        /** Set the 'ignore annotation' flag
935          *
936          * This method gives users the option to not generate XSAnnotations
937          * when "traversing" a schema.
938          *
939          * The parser's default state is false
940          *
941          * @param newValue The state to set
942          */
943        void setIgnoreAnnotations(const bool newValue);
944
945        /** Set the 'disable default entity resolution' flag
946          *
947          * This method gives users the option to not perform default entity
948          * resolution.  If the user's resolveEntity method returns NULL the
949          * parser will try to resolve the entity on its own.  When this option
950          * is set to true, the parser will not attempt to resolve the entity
951          * when the resolveEntity method returns NULL.
952          *
953          * The parser's default state is false
954          *
955          * @param newValue The state to set
956          *
957          * @see #EntityResolver
958          */
959        void setDisableDefaultEntityResolution(const bool newValue);
960
961        /** Set the 'skip DTD validation' flag
962          *
963          * This method gives users the option to skip DTD validation only when
964          * schema validation is on (i.e. when performing validation,  we will
965          * ignore the DTD, except for entities, when schema validation is enabled).
966          *
967          * NOTE: This option is ignored if schema validation is disabled.
968          *
969          * The parser's default state is false
970          *
971          * @param newValue The state to set
972          */
973        void setSkipDTDValidation(const bool newValue);
974
975        /** Set the 'handle multiple schema imports' flag
976          *
977          * This method gives users the ability to import multiple schemas that
978          * have the same namespace.
979          *
980          * NOTE: This option is ignored if schema validation is disabled.
981          *
982          * The parser's default state is false
983          *
984          * @param newValue The state to set
985          */
986        void setHandleMultipleImports(const bool newValue);
987        //@}
988
989
990        // -----------------------------------------------------------------------
991        //  Advanced document handler list maintenance methods
992        // -----------------------------------------------------------------------
993
994        /** @name Advanced document handler list maintenance methods */
995        //@{
996        /**
997          * This method installs the specified 'advanced' document callback
998          * handler, thereby allowing the user to customize the processing,
999          * if they choose to do so. Any number of advanced callback handlers
1000          * maybe installed.
1001          *
1002          * <p>The methods in the advanced callback interface represent
1003          * Xerces-C extensions. There is no specification for this interface.</p>
1004          *
1005          * Note - XMLDocumentHandler calls, when used with SAXParser, will not provide correct namespace information. This is becaue the SAX parser does not support namespace aware processing.
1006          *
1007          * @param toInstall A pointer to the users advanced callback handler.
1008          *
1009          * @see #removeAdvDocHandler
1010          */
1011        void installAdvDocHandler(XMLDocumentHandler* const toInstall);
1012
1013        /**
1014          * This method removes the 'advanced' document handler callback from
1015          * the underlying parser scanner. If no handler is installed, advanced
1016          * callbacks are not invoked by the scanner.
1017          * @param toRemove A pointer to the advanced callback handler which
1018          *                 should be removed.
1019          *
1020          * Note - XMLDocumentHandler calls, when used with SAXParser, will not provide correct namespace information. This is becaue the SAX parser does not support namespace aware processing.
1021          *
1022          * @see #installAdvDocHandler
1023          */
1024        bool removeAdvDocHandler(XMLDocumentHandler* const toRemove);
1025        //@}
1026
1027
1028        // -----------------------------------------------------------------------
1029        //  Progressive scan methods
1030        // -----------------------------------------------------------------------
1031
1032        /** @name Progressive scan methods */
1033        //@{
1034
1035        /** Begin a progressive parse operation
1036          *
1037          * This method is used to start a progressive parse on a XML file.
1038          * To continue parsing, subsequent calls must be to the parseNext
1039          * method.
1040          *
1041          * It scans through the prolog and returns a token to be used on
1042          * subsequent scanNext() calls. If the return value is true, then the
1043          * token is legal and ready for further use. If it returns false, then
1044          * the scan of the prolog failed and the token is not going to work on
1045          * subsequent scanNext() calls.
1046          *
1047          * @param systemId A pointer to a Unicode string representing the path
1048          *                 to the XML file to be parsed.
1049          * @param toFill   A token maintaing state information to maintain
1050          *                 internal consistency between invocation of 'parseNext'
1051          *                 calls.
1052          *
1053          * @return 'true', if successful in parsing the prolog. It indicates the
1054          *         user can go ahead with parsing the rest of the file. It
1055          *         returns 'false' to indicate that the parser could parse the
1056          *         prolog (which means the token will not be valid.)
1057          *
1058          * @see #parseNext
1059          * @see #parseFirst(char*,...)
1060          * @see #parseFirst(InputSource&,...)
1061          */
1062        bool parseFirst
1063        (
1064                const   XMLCh* const    systemId
1065                ,       XMLPScanToken&  toFill
1066        );
1067
1068        /** Begin a progressive parse operation
1069          *
1070          * This method is used to start a progressive parse on a XML file.
1071          * To continue parsing, subsequent calls must be to the parseNext
1072          * method.
1073          *
1074          * It scans through the prolog and returns a token to be used on
1075          * subsequent scanNext() calls. If the return value is true, then the
1076          * token is legal and ready for further use. If it returns false, then
1077          * the scan of the prolog failed and the token is not going to work on
1078          * subsequent scanNext() calls.
1079          *
1080          * @param systemId A pointer to a regular native string representing
1081          *                 the path to the XML file to be parsed.
1082          * @param toFill   A token maintaing state information to maintain
1083          *                 internal consistency between invocation of 'parseNext'
1084          *                 calls.
1085          *
1086          * @return 'true', if successful in parsing the prolog. It indicates the
1087          *         user can go ahead with parsing the rest of the file. It
1088          *         returns 'false' to indicate that the parser could not parse
1089          *         the prolog.
1090          *
1091          * @see #parseNext
1092          * @see #parseFirst(XMLCh*,...)
1093          * @see #parseFirst(InputSource&,...)
1094          */
1095        bool parseFirst
1096        (
1097                const   char* const     systemId
1098                ,       XMLPScanToken&  toFill
1099        );
1100
1101        /** Begin a progressive parse operation
1102          *
1103          * This method is used to start a progressive parse on a XML file.
1104          * To continue parsing, subsequent calls must be to the parseNext
1105          * method.
1106          *
1107          * It scans through the prolog and returns a token to be used on
1108          * subsequent scanNext() calls. If the return value is true, then the
1109          * token is legal and ready for further use. If it returns false, then
1110          * the scan of the prolog failed and the token is not going to work on
1111          * subsequent scanNext() calls.
1112          *
1113          * @param source   A const reference to the InputSource object which
1114          *                 points to the XML file to be parsed.
1115          * @param toFill   A token maintaing state information to maintain
1116          *                 internal consistency between invocation of 'parseNext'
1117          *                 calls.
1118          *
1119          * @return 'true', if successful in parsing the prolog. It indicates the
1120          *         user can go ahead with parsing the rest of the file. It
1121          *         returns 'false' to indicate that the parser could not parse
1122          *         the prolog.
1123          *
1124          * @see #parseNext
1125          * @see #parseFirst(XMLCh*,...)
1126          * @see #parseFirst(char*,...)
1127          */
1128        bool parseFirst
1129        (
1130                const   InputSource&    source
1131                ,       XMLPScanToken&  toFill
1132        );
1133
1134        /** Continue a progressive parse operation
1135          *
1136          * This method is used to continue with progressive parsing of
1137          * XML files started by a call to 'parseFirst' method.
1138          *
1139          * It parses the XML file and stops as soon as it comes across
1140          * a XML token (as defined in the XML specification). Relevant
1141          * callback handlers are invoked as required by the SAX
1142          * specification.
1143          *
1144          * @param token A token maintaing state information to maintain
1145          *              internal consistency between invocation of 'parseNext'
1146          *              calls.
1147          *
1148          * @return 'true', if successful in parsing the next XML token.
1149          *         It indicates the user can go ahead with parsing the rest
1150          *         of the file. It returns 'false' to indicate that the parser
1151          *         could not find next token as per the XML specification
1152          *         production rule.
1153          *
1154          * @see #parseFirst(XMLCh*,...)
1155          * @see #parseFirst(char*,...)
1156          * @see #parseFirst(InputSource&,...)
1157          */
1158        bool parseNext(XMLPScanToken& token);
1159
1160        /** Reset the parser after a progressive parse
1161          *
1162          * If a progressive parse loop exits before the end of the document
1163          * is reached, the parser has no way of knowing this. So it will leave
1164          * open any files or sockets or memory buffers that were in use at
1165          * the time that the parse loop exited.
1166          *
1167          * The next parse operation will cause these open files and such to
1168          * be closed, but the next parse operation might occur at some unknown
1169          * future point. To avoid this problem, you should reset the parser if
1170          * you exit the loop early.
1171          *
1172          * If you exited because of an error, then this cleanup will be done
1173          * for you. Its only when you exit the file prematurely of your own
1174          * accord, because you've found what you wanted in the file most
1175          * likely.
1176          *
1177          * @param token A token maintaing state information to maintain
1178          *              internal consistency between invocation of 'parseNext'
1179          *              calls.
1180          */
1181        void parseReset(XMLPScanToken& token);
1182
1183        //@}
1184
1185        // -----------------------------------------------------------------------
1186        //  Grammar preparsing interface
1187        // -----------------------------------------------------------------------
1188
1189        /** @name Implementation of Grammar preparsing interface's. */
1190        //@{
1191        /**
1192          * Preparse schema grammar (XML Schema, DTD, etc.) via an input source
1193          * object.
1194          *
1195          * This method invokes the preparsing process on a schema grammar XML
1196          * file specified by the SAX InputSource parameter. If the 'toCache' flag
1197          * is enabled, the parser will cache the grammars for re-use. If a grammar
1198          * key is found in the pool, no caching of any grammar will take place.
1199          *
1200          *
1201          * @param source A const reference to the SAX InputSource object which
1202          *               points to the schema grammar file to be preparsed.
1203          * @param grammarType The grammar type (Schema or DTD).
1204          * @param toCache If <code>true</code>, we cache the preparsed grammar,
1205          *                otherwise, no caching. Default is <code>false</code>.
1206          * @return The preparsed schema grammar object (SchemaGrammar or
1207          *         DTDGrammar). That grammar object is owned by the parser.
1208          *
1209          * @exception SAXException Any SAX exception, possibly
1210          *            wrapping another exception.
1211          * @exception XMLException An exception from the parser or client
1212          *            handler code.
1213          * @exception DOMException A DOM exception as per DOM spec.
1214          *
1215          * @see InputSource#InputSource
1216          */
1217        Grammar* loadGrammar(const InputSource& source,
1218                                                 const Grammar::GrammarType grammarType,
1219                                                 const bool toCache = false);
1220
1221        /**
1222          * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL
1223          *
1224          * This method invokes the preparsing process on a schema grammar XML
1225          * file specified by the file path parameter. If the 'toCache' flag
1226          * is enabled, the parser will cache the grammars for re-use. If a grammar
1227          * key is found in the pool, no caching of any grammar will take place.
1228          *
1229          *
1230          * @param systemId A const XMLCh pointer to the Unicode string which
1231          *                 contains the path to the XML grammar file to be
1232          *                 preparsed.
1233          * @param grammarType The grammar type (Schema or DTD).
1234          * @param toCache If <code>true</code>, we cache the preparsed grammar,
1235          *                otherwise, no caching. Default is <code>false</code>.
1236          * @return The preparsed schema grammar object (SchemaGrammar or
1237          *         DTDGrammar). That grammar object is owned by the parser.
1238          *
1239          * @exception SAXException Any SAX exception, possibly
1240          *            wrapping another exception.
1241          * @exception XMLException An exception from the parser or client
1242          *            handler code.
1243          * @exception DOMException A DOM exception as per DOM spec.
1244          */
1245        Grammar* loadGrammar(const XMLCh* const systemId,
1246                                                 const Grammar::GrammarType grammarType,
1247                                                 const bool toCache = false);
1248
1249        /**
1250          * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL
1251          *
1252          * This method invokes the preparsing process on a schema grammar XML
1253          * file specified by the file path parameter. If the 'toCache' flag
1254          * is enabled, the parser will cache the grammars for re-use. If a grammar
1255          * key is found in the pool, no caching of any grammar will take place.
1256          *
1257          *
1258          * @param systemId A const char pointer to a native string which contains
1259          *                 the path to the XML grammar file to be preparsed.
1260          * @param grammarType The grammar type (Schema or DTD).
1261          * @param toCache If <code>true</code>, we cache the preparsed grammar,
1262          *                otherwise, no caching. Default is <code>false</code>.
1263          * @return The preparsed schema grammar object (SchemaGrammar or
1264          *         DTDGrammar). That grammar object is owned by the parser.
1265          *
1266          * @exception SAXException Any SAX exception, possibly
1267          *            wrapping another exception.
1268          * @exception XMLException An exception from the parser or client
1269          *            handler code.
1270          * @exception DOMException A DOM exception as per DOM spec.
1271          */
1272        Grammar* loadGrammar(const char* const systemId,
1273                                                 const Grammar::GrammarType grammarType,
1274                                                 const bool toCache = false);
1275
1276        /**
1277          * This method allows the user to reset the pool of cached grammars.
1278          */
1279        void resetCachedGrammarPool();
1280
1281        //@}
1282
1283
1284        // -----------------------------------------------------------------------
1285        //  Implementation of the SAX Parser interface
1286        // -----------------------------------------------------------------------
1287
1288        /** @name Implementation of SAX 1.0 Parser interface's. */
1289        //@{
1290        /**
1291          * This method invokes the parsing process on the XML file specified
1292          * by the InputSource parameter.
1293          *
1294          * @param source A const reference to the InputSource object which
1295          *               points to the XML file to be parsed.
1296          *
1297          * @see Parser#parse(InputSource)
1298          */
1299        virtual void parse(const InputSource& source);
1300
1301        /**
1302          * This method invokes the parsing process on the XML file specified by
1303          * the Unicode string parameter 'systemId'.
1304          *
1305          * @param systemId A const XMLCh pointer to the Unicode string which
1306          *                 contains the path to the XML file to be parsed.
1307          *
1308          * @see Parser#parse(XMLCh*)
1309          */
1310        virtual void parse(const XMLCh* const systemId);
1311
1312        /**
1313          * This method invokes the parsing process on the XML file specified by
1314          * the native char* string parameter 'systemId'.
1315          *
1316          * @param systemId A const char pointer to a native string which
1317          *                 contains the path to the XML file to be parsed.
1318          */
1319        virtual void parse(const char* const systemId);
1320
1321        /**
1322          * This method installs the user specified SAX Document Handler
1323          * callback function on parser.
1324          *
1325          * @param handler A pointer to the document handler to be called
1326          *                when the parser comes across 'document' events
1327          *                as per the SAX specification.
1328          *
1329          * @see Parser#parse(char*)
1330          */
1331        virtual void setDocumentHandler(DocumentHandler* const handler);
1332
1333        /**
1334          * This method installs the user specified DTD handler on the parser.
1335          *
1336          * @param handler A pointer to the DTD handler to be called
1337          *                when the parser comes across 'DTD' events
1338          *                as per the SAX specification.
1339          *
1340          * @see Parser#setDTDHandler
1341          */
1342        virtual void setDTDHandler(DTDHandler* const handler);
1343
1344        /**
1345          * This method installs the user specified error handler on
1346          * the parser.
1347          *
1348          * @param handler A pointer to the error handler to be called
1349          *                when the parser comes across 'error' events
1350          *                as per the SAX specification.
1351          *
1352          * @see Parser#setErrorHandler
1353          */
1354        virtual void setErrorHandler(ErrorHandler* const handler);
1355
1356        /**
1357          * This method installs the user specified PSVI handler on
1358          * the parser.
1359          *
1360          * @param handler A pointer to the PSVI handler to be called
1361          *                when the parser comes across 'PSVI' events
1362          *                as per the schema specification.
1363          *
1364          * @see Parser#setPSVIHandler
1365          */
1366        virtual void setPSVIHandler(PSVIHandler* const handler);
1367
1368        /**
1369          * This method installs the user specified entity resolver on the
1370          * parser. It allows applications to trap and redirect calls to
1371          * external entities.
1372          *
1373          * <i>Any previously set entity resolver is merely dropped, since the parser
1374          * does not own them.  If both setEntityResolver and setXMLEntityResolver
1375          * are called, then the last one is used.</i>
1376          *
1377          * @param resolver A pointer to the entity resolver to be called
1378          *                 when the parser comes across references to
1379          *                 entities in the XML file.
1380          *
1381          * @see Parser#setEntityResolver
1382          */
1383        virtual void setEntityResolver(EntityResolver* const resolver);
1384
1385        /**
1386          * This method installs the user specified entity resolver on the
1387          * parser. It allows applications to trap and redirect calls to
1388          * external entities.
1389          *
1390          * <i>Any previously set entity resolver is merely dropped, since the parser
1391          * does not own them.  If both setEntityResolver and setXMLEntityResolver
1392          * are called, then the last one is used.</i>
1393          *
1394          * @param resolver A pointer to the entity resolver to be called
1395          *                 when the parser comes across references to
1396          *                 entities in the XML file.
1397          *
1398          * @see Parser#setXMLEntityResolver
1399          */
1400        virtual void setXMLEntityResolver(XMLEntityResolver* const resolver);
1401
1402        //@}
1403
1404
1405        // -----------------------------------------------------------------------
1406        //  Implementation of the XMLDocumentHandler interface
1407        // -----------------------------------------------------------------------
1408
1409        /** @name Implementation of the XMLDocumentHandler Interface. */
1410        //@{
1411        /**
1412          * This method is used to report all the characters scanned
1413          * by the parser. The driver will invoke the 'characters'
1414          * method of the user installed SAX Document Handler.
1415          *
1416          * <p>If any advanced callback handlers are installed, the
1417          * corresponding 'docCharacters' method will also be invoked.</p>
1418          *
1419          * @param chars   A const pointer to a Unicode string representing the
1420          *                character data.
1421          * @param length  The length of the Unicode string returned in 'chars'.
1422          * @param cdataSection  A flag indicating if the characters represent
1423          *                      content from the CDATA section.
1424          * @see DocumentHandler#characters
1425          */
1426        virtual void docCharacters
1427        (
1428                const   XMLCh* const    chars
1429                , const XMLSize_t       length
1430                , const bool            cdataSection
1431        );
1432
1433        /**
1434          * This method is used to report any comments scanned by the parser.
1435          * This method is a no-op unless, unless an advanced callback handler
1436          * is installed, in which case the corresponding 'docComment' method
1437          * is invoked.
1438          *
1439          * @param comment A const pointer to a null terminated Unicode
1440          *                string representing the comment text.
1441          */
1442        virtual void docComment
1443        (
1444                const   XMLCh* const    comment
1445        );
1446
1447        /**
1448          * This method is used to report any PI scanned by the parser.
1449          *
1450          * <p>Any PI's occurring before any 'content' are not reported
1451          * to any SAX handler as per the specification. However, all
1452          * PI's within content are reported via the SAX Document Handler's
1453          * 'processingInstruction' method.
1454          *
1455          * <p>If any advanced callback handlers are installed, the
1456          * corresponding 'docPI' method will be invoked.</p>
1457          *
1458          * @param target A const pointer to a Unicode string representing the
1459          *               target of the PI declaration.
1460          * @param data   A const pointer to a Unicode string representing the
1461          *               data of the PI declaration. See the PI production rule
1462          *               in the XML specification for details.
1463          *
1464          * @see DocumentHandler#processingInstruction
1465          */
1466        virtual void docPI
1467        (
1468                const   XMLCh* const    target
1469                , const XMLCh* const    data
1470        );
1471
1472        /**
1473          * This method is used to indicate the end of root element
1474          * was just scanned by the parser. Corresponding 'endDocument'
1475          * method of the user installed SAX Document Handler will also
1476          * be invoked.
1477          *
1478          * <p>In addition, if any advanced callback handlers are installed,
1479          * the corresponding 'endDocument' method is invoked.</p>
1480          *
1481          * @see DocumentHandler#endDocument
1482          */
1483        virtual void endDocument();
1484
1485        /**
1486          * This method is used to indicate the end tag of an element.
1487          * The driver will invoke the corresponding 'endElement' method of
1488          * the SAX Document Handler interface.
1489          *
1490          * <p>If any advanced callback handlers are installed, the
1491          * corresponding 'endElement' method is also invoked.</p>
1492          *
1493          * @param elemDecl A const reference to the object containing element
1494          *                 declaration information.
1495          * @param urlId    An id referring to the namespace prefix, if
1496          *                 namespaces setting is switched on.
1497          * @param isRoot   A flag indicating whether this element was the
1498          *                 root element.
1499          * @param elemPrefix A const pointer to a Unicode string containing
1500          *                   the namespace prefix for this element. Applicable
1501          *                   only when namespace processing is enabled.
1502          * @see DocumentHandler#endElement
1503          */
1504        virtual void endElement
1505        (
1506                const   XMLElementDecl& elemDecl
1507                , const unsigned int    urlId
1508                , const bool            isRoot
1509                , const XMLCh* const    elemPrefix
1510        );
1511
1512        /**
1513          * This method is used to indicate that an end of an entity reference
1514          * was just scanned.
1515          *
1516          * <p>If any advanced callback handlers are installed, the
1517          * corresponding 'endEntityReference' method is invoked.</p>
1518          *
1519          * @param entDecl A const reference to the object containing the
1520          *                entity declaration information.
1521          */
1522        virtual void endEntityReference
1523        (
1524                const   XMLEntityDecl&  entDecl
1525        );
1526
1527        /**
1528          * This method is used to report all the whitespace characters,
1529          * which are determined to be 'ignorable'. This distinction
1530          * between characters is only made, if validation is enabled.
1531          * Corresponding 'ignorableWhitespace' method of the user installed
1532          * SAX Document Handler interface is called.
1533          *
1534          * <p>Any whitespace before content is not reported to the SAX
1535          * Document Handler method, as per the SAX specification.
1536          * However, if any advanced callback handlers are installed, the
1537          * corresponding 'ignorableWhitespace' method is invoked.</p>
1538          *
1539          * @param chars   A const pointer to a Unicode string representing the
1540          *                ignorable whitespace character data.
1541          * @param length  The length of the Unicode string 'chars'.
1542          * @param cdataSection  A flag indicating if the characters represent
1543          *                      content from the CDATA section.
1544          * @see DocumentHandler#ignorableWhitespace
1545          */
1546        virtual void ignorableWhitespace
1547        (
1548                const   XMLCh* const    chars
1549                , const XMLSize_t       length
1550                , const bool            cdataSection
1551        );
1552
1553        /**
1554          * This method allows the user installed Document Handler and
1555          * any advanced callback handlers to 'reset' themselves.
1556          */
1557        virtual void resetDocument();
1558
1559        /**
1560          * This method is used to report the start of the parsing process.
1561          * The corresponding user installed SAX Document Handler's method
1562          * 'startDocument' is invoked.
1563          *
1564          * <p>If any advanced callback handlers are installed, then the
1565          * corresponding 'startDocument' method is also called.</p>
1566          *
1567          * @see DocumentHandler#startDocument
1568          */
1569        virtual void startDocument();
1570
1571        /**
1572          * This method is used to report the start of an element. It is
1573          * called at the end of the element, by which time all attributes
1574          * specified are also parsed. The corresponding user installed
1575          * SAX Document Handler's method 'startElement' is invoked.
1576          *
1577          * <p>If any advanced callback handlers are installed, then the
1578          * corresponding 'startElement' method is also called.</p>
1579          *
1580          * @param elemDecl A const reference to the object containing element
1581          *                 declaration information.
1582          * @param urlId    An id referring to the namespace prefix, if
1583          *                 namespaces setting is switched on.
1584          * @param elemPrefix A const pointer to a Unicode string containing
1585          *                   the namespace prefix for this element. Applicable
1586          *                   only when namespace processing is enabled.
1587          * @param attrList  A const reference to the object containing the
1588          *                  list of attributes just scanned for this element.
1589          * @param attrCount A count of number of attributes in the list
1590          *                  specified by the parameter 'attrList'.
1591          * @param isEmpty  A flag indicating whether this is an empty element
1592          *                 or not.
1593          * @param isRoot   A flag indicating whether this element was the
1594          *                 root element.
1595          * @see DocumentHandler#startElement
1596          */
1597        virtual void startElement
1598        (
1599                const   XMLElementDecl&         elemDecl
1600                , const unsigned int            urlId
1601                , const XMLCh* const            elemPrefix
1602                , const RefVectorOf<XMLAttr>&   attrList
1603                , const XMLSize_t               attrCount
1604                , const bool                    isEmpty
1605                , const bool                    isRoot
1606        );
1607
1608        /**
1609          * This method is used to indicate the start of an entity reference.
1610          *
1611          * <p>If any advanced callback handlers are installed, the
1612          * corresponding 'endEntityReference' method is invoked.</p>
1613          *
1614          * @param entDecl A const reference to the object containing the
1615          *                entity declaration information.
1616          */
1617        virtual void startEntityReference
1618        (
1619                const   XMLEntityDecl&  entDecl
1620        );
1621
1622        /**
1623          * This method is used to report the XML decl scanned by the parser.
1624          * Refer to the XML specification to see the meaning of parameters.
1625          *
1626          * <b>This method is a no-op for this SAX driver
1627          * implementation.</b>
1628          *
1629          * @param versionStr A const pointer to a Unicode string representing
1630          *                   version string value.
1631          * @param encodingStr A const pointer to a Unicode string representing
1632          *                    the encoding string value.
1633          * @param standaloneStr A const pointer to a Unicode string
1634          *                      representing the standalone string value.
1635          * @param actualEncodingStr A const pointer to a Unicode string
1636          *                          representing the actual encoding string
1637          *                          value.
1638          */
1639        virtual void XMLDecl
1640        (
1641                const   XMLCh* const    versionStr
1642                , const XMLCh* const    encodingStr
1643                , const XMLCh* const    standaloneStr
1644                , const XMLCh* const    actualEncodingStr
1645        );
1646        //@}
1647
1648
1649        // -----------------------------------------------------------------------
1650        //  Implementation of the XMLErrorReporter interface
1651        // -----------------------------------------------------------------------
1652
1653        /** @name Implementation of the XMLErrorReporter Interface. */
1654        //@{
1655        /**
1656          * This method is used to report back errors found while parsing the
1657          * XML file. The driver will call the corresponding user installed
1658          * SAX Error Handler methods: 'fatal', 'error', 'warning' depending
1659          * on the severity of the error. This classification is defined by
1660          * the XML specification.
1661          *
1662          * @param errCode An integer code for the error.
1663          * @param msgDomain A const pointer to an Unicode string representing
1664          *                  the message domain to use.
1665          * @param errType An enumeration classifying the severity of the error.
1666          * @param errorText A const pointer to an Unicode string representing
1667          *                  the text of the error message.
1668          * @param systemId  A const pointer to an Unicode string representing
1669          *                  the system id of the XML file where this error
1670          *                  was discovered.
1671          * @param publicId  A const pointer to an Unicode string representing
1672          *                  the public id of the XML file where this error
1673          *                  was discovered.
1674          * @param lineNum   The line number where the error occurred.
1675          * @param colNum    The column number where the error occurred.
1676          * @see ErrorHandler
1677          */
1678        virtual void error
1679        (
1680                const   unsigned int                errCode
1681                , const XMLCh* const                msgDomain
1682                , const XMLErrorReporter::ErrTypes  errType
1683                , const XMLCh* const                errorText
1684                , const XMLCh* const                systemId
1685                , const XMLCh* const                publicId
1686                , const XMLFileLoc                  lineNum
1687                , const XMLFileLoc                  colNum
1688        );
1689
1690        /**
1691          * This method allows the user installed Error Handler
1692          * callback to 'reset' itself.
1693          *
1694          * <b>This method is a no-op for this SAX driver
1695          * implementation.</b>
1696          *
1697          */
1698        virtual void resetErrors();
1699        //@}
1700
1701
1702        // -----------------------------------------------------------------------
1703        //  Implementation of the XMLEntityHandler interface
1704        // -----------------------------------------------------------------------
1705
1706        /** @name Implementation of the XMLEntityHandler Interface. */
1707        //@{
1708        /**
1709          * This method is used to indicate the end of parsing of an external
1710          * entity file.
1711          *
1712          * <b>This method is a no-op for this SAX driver
1713          * implementation.</b>
1714          *
1715          * @param inputSource A const reference to the InputSource object
1716          *                    which points to the XML file being parsed.
1717          * @see InputSource
1718          */
1719        virtual void endInputSource(const InputSource& inputSource);
1720
1721        /**
1722          * This method allows an installed XMLEntityHandler to further
1723          * process any system id's of external entities encountered in
1724          * the XML file being parsed, such as redirection etc.
1725          *
1726          * <b>This method always returns 'false'
1727          * for this SAX driver implementation.</b>
1728          *
1729          * @param systemId  A const pointer to an Unicode string representing
1730          *                  the system id scanned by the parser.
1731          * @param toFill    A pointer to a buffer in which the application
1732          *                  processed system id is stored.
1733          * @return 'true', if any processing is done, 'false' otherwise.
1734          */
1735        virtual bool expandSystemId
1736        (
1737                const   XMLCh* const    systemId
1738                ,       XMLBuffer&      toFill
1739        );
1740
1741        /**
1742          * This method allows the installed XMLEntityHandler to reset
1743          * itself.
1744          *
1745          * <b>This method is a no-op for this SAX driver
1746          * implementation.</b>
1747          */
1748        virtual void resetEntities();
1749
1750        /** Resolve a public/system id
1751          *
1752          * This method allows a user installed entity handler to further
1753          * process any pointers to external entities. The applications can
1754          * implement 'redirection' via this callback.
1755          *
1756          * @param resourceIdentifier An object containing the type of
1757          *        resource to be resolved and the associated data members
1758          *        corresponding to this type.
1759          * @return The value returned by the user installed resolveEntity
1760          *         method or NULL otherwise to indicate no processing was done.
1761          *         The returned InputSource is owned by the parser which is
1762          *         responsible to clean up the memory.
1763          * @see XMLEntityHandler
1764          * @see XMLEntityResolver
1765          */
1766        virtual InputSource* resolveEntity
1767        (
1768                XMLResourceIdentifier* resourceIdentifier
1769        );
1770
1771        /**
1772          * This method is used to indicate the start of parsing an
1773          * external entity file.
1774          *
1775          * <b>This method is a no-op for this SAX driver
1776          * implementation.</b>
1777          *
1778          * @param inputSource A const reference to the InputSource object
1779          *                    which points to the external entity
1780          *                    being parsed.
1781          */
1782        virtual void startInputSource(const InputSource& inputSource);
1783        //@}
1784
1785
1786        // -----------------------------------------------------------------------
1787        //  Implementation of the Deprecated DocTypeHandler Interface
1788        // -----------------------------------------------------------------------
1789        /** @name Implementation of the deprecated DocTypeHandler Interface */
1790        //@{
1791        /**
1792          * This method is used to report an attribute definition.
1793          *
1794          * <b>This method is a no-op for this SAX
1795          * driver implementation.</b>
1796          *
1797          * @param elemDecl A const reference to the object containing information
1798          *                 about the element whose attribute definition was just
1799          *                 parsed.
1800          * @param attDef   A const reference to the object containing information
1801          *                 attribute definition.
1802          * @param ignore   The flag indicating whether this attribute definition
1803          *                 was ignored by the parser or not.
1804          */
1805        virtual void attDef
1806        (
1807                const   DTDElementDecl& elemDecl
1808                , const DTDAttDef&      attDef
1809                , const bool            ignore
1810        );
1811
1812        /**
1813          * This method is used to report a comment occurring within the DTD.
1814          *
1815          * <b>This method is a no-op for this SAX driver
1816          * implementation.</b>
1817          *
1818          * @param comment  A const pointer to a Unicode string representing the
1819          *                 text of the comment just parsed.
1820          */
1821        virtual void doctypeComment
1822        (
1823                const   XMLCh* const    comment
1824        );
1825
1826        /**
1827          * This method is used to report the DOCTYPE declaration.
1828          *
1829          * <b>This method is a no-op for this SAX driver
1830          * implementation.</b>
1831          *
1832          * @param elemDecl A const reference to the object containing information
1833          *                 about the root element definition declaration of the
1834          *                 XML document being parsed.
1835          * @param publicId A const pointer to a Unicode string representing the
1836          *                 public id of the DTD file.
1837          * @param systemId A const pointer to a Unicode string representing the
1838          *                 system id of the DTD file.
1839          * @param hasIntSubset A flag indicating if this XML file contains any
1840          *                     internal subset.
1841          * @param hasExtSubset A flag indicating if this XML file contains any
1842          *                     external subset. Default is false.
1843          */
1844        virtual void doctypeDecl
1845        (
1846                const   DTDElementDecl& elemDecl
1847                , const XMLCh* const    publicId
1848                , const XMLCh* const    systemId
1849                , const bool            hasIntSubset
1850                , const bool            hasExtSubset = false
1851        );
1852
1853        /**
1854          * This method is used to report any PI declarations
1855          * occurring inside the DTD definition block.
1856          *
1857          * <b>This method is a no-op for this SAX driver
1858          * implementation.</b>
1859          *
1860          * @param target A const pointer to a Unicode string representing the
1861          *               target of the PI declaration.
1862          * @param data   A const pointer to a Unicode string representing the
1863          *               data of the PI declaration. See the PI production rule
1864          *               in the XML specification for details.
1865          */
1866        virtual void doctypePI
1867        (
1868                const   XMLCh* const    target
1869                , const XMLCh* const    data
1870        );
1871
1872        /**
1873          * This method is used to report any whitespaces
1874          * occurring inside the DTD definition block.
1875          *
1876          * <b>This method is a no-op for this SAX driver
1877          * implementation.</b>
1878          *
1879          * @param chars  A const pointer to a Unicode string representing the
1880          *               whitespace characters.
1881          * @param length The length of the whitespace Unicode string.
1882          */
1883        virtual void doctypeWhitespace
1884        (
1885                const   XMLCh* const    chars
1886                , const XMLSize_t       length
1887        );
1888
1889        /**
1890          * This method is used to report an element declarations
1891          * successfully scanned by the parser.
1892          *
1893          * <b>This method is a no-op for this SAX driver
1894          * implementation.</b>
1895          *
1896          * @param decl   A const reference to the object containing element
1897          *               declaration information.
1898          * @param isIgnored The flag indicating whether this definition was
1899          *                  ignored by the parser or not.
1900          */
1901        virtual void elementDecl
1902        (
1903                const   DTDElementDecl& decl
1904                , const bool            isIgnored
1905        );
1906
1907        /**
1908          * This method is used to report the end of an attribute
1909          * list declaration for an element.
1910          *
1911          * <b>This method is a no-op for this SAX driver
1912          * implementation.</b>
1913          *
1914          * @param elemDecl A const reference to the object containing element
1915          *                 declaration information.
1916          */
1917        virtual void endAttList
1918        (
1919                const   DTDElementDecl& elemDecl
1920        );
1921
1922        /**
1923          * This method is used to report the end of the internal subset.
1924          *
1925          * <b>This method is a no-op for this SAX driver
1926          * implementation.</b>
1927          */
1928        virtual void endIntSubset();
1929
1930        /**
1931          * This method is used to report the end of the external subset.
1932          *
1933          * <b>This method is a no-op for this SAX driver
1934          * implementation.</b>
1935          */
1936        virtual void endExtSubset();
1937
1938        /**
1939          * This method is used to report any entity declarations.
1940          * For unparsed entities, this driver will invoke the
1941          * SAX DTDHandler::unparsedEntityDecl callback.
1942          *
1943          * @param entityDecl A const reference to the object containing
1944          *                   the entity declaration information.
1945          * @param isPEDecl  The flag indicating whether this was a
1946          *                  parameter entity declaration or not.
1947          * @param isIgnored The flag indicating whether this definition
1948          *                  was ignored by the parser or not.
1949          *
1950          * @see DTDHandler#unparsedEntityDecl
1951          */
1952        virtual void entityDecl
1953        (
1954                const   DTDEntityDecl&  entityDecl
1955                , const bool            isPEDecl
1956                , const bool            isIgnored
1957        );
1958
1959        /**
1960          * This method allows the user installed DTD handler to
1961          * reset itself.
1962          */
1963        virtual void resetDocType();
1964
1965        /**
1966          * This method is used to report any notation declarations.
1967          * If there is a user installed DTDHandler, then the driver will
1968          * invoke the SAX DTDHandler::notationDecl callback.
1969          *
1970          * @param notDecl A const reference to the object containing the notation
1971          *                declaration information.
1972          * @param isIgnored The flag indicating whether this definition was ignored
1973          *                  by the parser or not.
1974          *
1975          * @see DTDHandler#notationDecl
1976          */
1977        virtual void notationDecl
1978        (
1979                const   XMLNotationDecl&    notDecl
1980                , const bool                isIgnored
1981        );
1982
1983        /**
1984          * This method is used to indicate the start of an element's attribute
1985          * list declaration.
1986          *
1987          * <b>This method is a no-op for this SAX driver
1988          * implementation.</b>
1989          *
1990          * @param elemDecl A const reference to the object containing element
1991          *                 declaration information.
1992          */
1993        virtual void startAttList
1994        (
1995                const   DTDElementDecl& elemDecl
1996        );
1997
1998        /**
1999          * This method is used indicate the start of the internal subset.
2000          *
2001          * <b>This method is a no-op for this SAX driver
2002          * implementation.</b>
2003          */
2004        virtual void startIntSubset();
2005
2006        /**
2007          * This method is used indicate the start of the external subset.
2008          *
2009          * <b>This method is a no-op for this SAX driver
2010          * implementation.</b>
2011          */
2012        virtual void startExtSubset();
2013
2014        /**
2015          * This method is used to report the TextDecl. Refer to the XML
2016          * specification for the syntax of a TextDecl.
2017          *
2018          * <b>This method is a no-op for this SAX driver
2019          * implementation.</b>
2020          *
2021          * @param versionStr A const pointer to a Unicode string representing
2022          *                   the version number of the 'version' clause.
2023          * @param encodingStr A const pointer to a Unicode string representing
2024          *                    the encoding name of the 'encoding' clause.
2025          */
2026        virtual void TextDecl
2027        (
2028                const   XMLCh* const    versionStr
2029                , const XMLCh* const    encodingStr
2030        );
2031        //@}
2032
2033protected :
2034        // -----------------------------------------------------------------------
2035        //  Protected Methods
2036        // -----------------------------------------------------------------------
2037        /**
2038          * This method returns a reference to the underlying scanner object.
2039          * It allows read only access to data maintained in the scanner.
2040          *
2041          * @return A const reference to the underlying scanner object.
2042          */
2043        const XMLScanner& getScanner() const;
2044
2045        /** Get the Grammar resolver
2046          *
2047          * This provides derived classes with access to the grammar resolver.
2048          */
2049        GrammarResolver* getGrammarResolver() const;
2050
2051
2052private:
2053        // -----------------------------------------------------------------------
2054        //  Unimplemented constructors and operators
2055        // -----------------------------------------------------------------------
2056        SAXParser(const SAXParser&);
2057        SAXParser& operator=(const SAXParser&);
2058
2059        // -----------------------------------------------------------------------
2060        //  Initialize/Cleanup methods
2061        // -----------------------------------------------------------------------
2062        void initialize();
2063        void cleanUp();
2064        void resetInProgress();
2065
2066        // -----------------------------------------------------------------------
2067        //  Private data members
2068        //
2069        //  fAttrList
2070        //      A temporary implementation of the basic SAX attribute list
2071        //      interface. We use this one over and over on each startElement
2072        //      event to allow SAX-like access to the element attributes.
2073        //
2074        //  fDocHandler
2075        //      The installed SAX doc handler, if any. Null if none.
2076        //
2077        //  fDTDHandler
2078        //      The installed SAX DTD handler, if any. Null if none.
2079        //
2080        //  fElemDepth
2081        //      This is used to track the element nesting depth, so that we can
2082        //      know when we are inside content. This is so we can ignore char
2083        //      data outside of content.
2084        //
2085        //  fEntityResolver
2086        //      The installed SAX entity handler, if any. Null if none.
2087        //
2088        //  fErrorHandler
2089        //      The installed SAX error handler, if any. Null if none.
2090        //
2091        //  fPSVIHandler
2092        //      The installed PSVI handler, if any. Null if none.
2093        //
2094        //  fAdvDHCount
2095        //  fAdvDHList
2096        //  fAdvDHListSize
2097        //      This is an array of pointers to XMLDocumentHandlers, which is
2098        //      how we see installed advanced document handlers. There will
2099        //      usually not be very many at all, so a simple array is used
2100        //      instead of a collection, for performance. It will grow if needed,
2101        //      but that is unlikely.
2102        //
2103        //      The count is how many handlers are currently installed. The size
2104        //      is how big the array itself is (for expansion purposes.) When
2105        //      count == size, is time to expand.
2106        //
2107        //  fParseInProgress
2108        //      This flag is set once a parse starts. It is used to prevent
2109        //      multiple entrance or reentrance of the parser.
2110        //
2111        //  fScanner
2112        //      The scanner being used by this parser. It is created internally
2113        //      during construction.
2114        //
2115        //   fGrammarPool
2116        //      The grammar pool passed from external application (through derivatives).
2117        //      which could be 0, not owned.
2118        //
2119        // -----------------------------------------------------------------------
2120        bool                 fParseInProgress;
2121        XMLSize_t            fElemDepth;
2122        XMLSize_t            fAdvDHCount;
2123        XMLSize_t            fAdvDHListSize;
2124        VecAttrListImpl      fAttrList;
2125        DocumentHandler*     fDocHandler;
2126        DTDHandler*          fDTDHandler;
2127        EntityResolver*      fEntityResolver;
2128        XMLEntityResolver*   fXMLEntityResolver;
2129        ErrorHandler*        fErrorHandler;
2130        PSVIHandler*         fPSVIHandler;
2131        XMLDocumentHandler** fAdvDHList;
2132        XMLScanner*          fScanner;
2133        GrammarResolver*     fGrammarResolver;
2134        #ifndef TEST_NAMESPACE_RESOLVER
2135        XMLStringPool*       fURIStringPool;
2136        #endif
2137        XMLValidator*        fValidator;
2138        MemoryManager*       fMemoryManager;
2139        XMLGrammarPool*      fGrammarPool;
2140//      XMLBuffer            fElemQNameBuf;
2141};
2142
2143
2144// ---------------------------------------------------------------------------
2145//  SAXParser: Getter methods
2146// ---------------------------------------------------------------------------
2147inline DocumentHandler* SAXParser::getDocumentHandler()
2148{
2149        return fDocHandler;
2150}
2151
2152inline const DocumentHandler* SAXParser::getDocumentHandler() const
2153{
2154        return fDocHandler;
2155}
2156
2157inline EntityResolver* SAXParser::getEntityResolver()
2158{
2159        return fEntityResolver;
2160}
2161
2162inline XMLEntityResolver* SAXParser::getXMLEntityResolver()
2163{
2164        return fXMLEntityResolver;
2165}
2166
2167inline const XMLEntityResolver* SAXParser::getXMLEntityResolver() const
2168{
2169        return fXMLEntityResolver;
2170}
2171
2172inline const EntityResolver* SAXParser::getEntityResolver() const
2173{
2174        return fEntityResolver;
2175}
2176
2177inline ErrorHandler* SAXParser::getErrorHandler()
2178{
2179        return fErrorHandler;
2180}
2181
2182inline const ErrorHandler* SAXParser::getErrorHandler() const
2183{
2184        return fErrorHandler;
2185}
2186
2187inline PSVIHandler* SAXParser::getPSVIHandler()
2188{
2189        return fPSVIHandler;
2190}
2191
2192inline const PSVIHandler* SAXParser::getPSVIHandler() const
2193{
2194        return fPSVIHandler;
2195}
2196
2197inline const XMLScanner& SAXParser::getScanner() const
2198{
2199        return *fScanner;
2200}
2201
2202inline GrammarResolver* SAXParser::getGrammarResolver() const
2203{
2204        return fGrammarResolver;
2205}
2206
2207XERCES_CPP_NAMESPACE_END
2208
2209#endif
Note: See TracBrowser for help on using the repository browser.