source: NonGTP/Xerces/xerces/include/xercesc/sax2/SAX2XMLReader.hpp @ 358

Revision 358, 39.1 KB checked in by bittner, 19 years ago (diff)

xerces added

Line 
1/*
2 * Copyright 1999-2001,2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17/*
18 * $Log: SAX2XMLReader.hpp,v $
19 * Revision 1.12  2004/09/30 14:07:43  peiyongz
20 * setInputBufferSize
21 *
22 * Revision 1.11  2004/09/08 13:56:20  peiyongz
23 * Apache License Version 2.0
24 *
25 * Revision 1.10  2003/03/07 18:10:30  tng
26 * Return a reference instead of void for operator=
27 *
28 * Revision 1.9  2003/01/09 19:07:27  tng
29 * [Bug 15802] Add "const" qualifier to getURIText.
30 *
31 * Revision 1.8  2002/12/23 15:23:18  knoaman
32 * Added a public api to various parsers to return the src offset within the input
33 * source.
34 *
35 * Revision 1.7  2002/11/04 14:55:45  tng
36 * C++ Namespace Support.
37 *
38 * Revision 1.6  2002/07/11 18:29:09  knoaman
39 * Grammar caching/preparsing - initial implementation.
40 *
41 * Revision 1.5  2002/07/04 15:35:44  tng
42 * API Documentation typo fix.
43 *
44 * Revision 1.4  2002/06/27 18:46:53  tng
45 * API Documentation Update.
46 *
47 * Revision 1.3  2002/06/17 15:39:49  tng
48 * To be consistent, SAX2 is updated with:
49 * 1. the progressive parse methods should use the fReuseGrammar flag set from setFeature instead of using parameter
50 * 2. add feature "http://apache.org/xml/features/continue-after-fatal-error", and users should use setFeature instead of setExitOnFirstFatalError
51 * 3. add feature "http://apache.org/xml/features/validation-error-as-fatal", and users should use setFeature instead of setValidationConstraintFatal
52 *
53 * Revision 1.2  2002/05/30 16:22:53  tng
54 * Add feature to optionally ignore external DTD.
55 *
56 * Revision 1.1.1.1  2002/02/01 22:22:09  peiyongz
57 * sane_include
58 *
59 * Revision 1.18  2002/01/28 18:45:40  knoaman
60 * Update documentation for SAX2 feature 'namespace-prefixes'.
61 *
62 * Revision 1.17  2002/01/28 17:08:33  knoaman
63 * SAX2-ext's DeclHandler support.
64 *
65 * Revision 1.16  2002/01/18 16:31:26  tng
66 * Break program.xml which takes too long to load, into program-sax.xml, program-sax2.xml, program-dom.xml, program-idom.xml.
67 *
68 * Revision 1.15  2002/01/02 15:36:54  tng
69 * Some documentation update.
70 *
71 * Revision 1.14  2001/11/20 18:51:44  tng
72 * Schema: schemaLocation and noNamespaceSchemaLocation to be specified outside the instance document.  New methods setExternalSchemaLocation and setExternalNoNamespaceSchemaLocation are added (for SAX2, two new properties are added).
73 *
74 * Revision 1.13  2001/11/14 14:15:59  tng
75 * Update SAX2 feature documentation.
76 *
77 * Revision 1.12  2001/09/12 13:03:43  tng
78 * [Bug 3155] SAX2 does not offer progressive parse.
79 *
80 * Revision 1.11  2001/08/01 19:11:02  tng
81 * Add full schema constraint checking flag to the samples and the parser.
82 *
83 * Revision 1.10  2001/06/27 17:40:16  knoaman
84 * Fix for bug #2353.
85 *
86 * Revision 1.9  2001/06/19 16:44:31  tng
87 * Add installAdvDocHandler to SAX2XMLReader as the code is there already.
88 *
89 * Revision 1.8  2001/06/04 21:03:07  jberry
90 * Add pure virtual getErrorCount to SAX2XMLReader interface.
91 *
92 * Revision 1.7  2001/05/11 13:26:25  tng
93 * Copyright update.
94 *
95 * Revision 1.6  2001/02/15 15:56:31  tng
96 * Schema: Add setSchemaValidation and getSchemaValidation for DOMParser and SAXParser.
97 * Add feature "http://apache.org/xml/features/validation/schema" for SAX2XMLReader.
98 * New data field  fSchemaValidation in XMLScanner as the flag.
99 *
100 * Revision 1.5  2001/01/12 21:22:00  tng
101 * Documentation Enhancement: Add list of SAX2 feature strings that are supported.
102 *
103 * Revision 1.4  2000/12/22 15:17:04  tng
104 * SAX2-ext's LexicalHandler support added by David Bertoni.
105 *
106 * Revision 1.3  2000/08/09 22:19:29  jpolast
107 * many conformance & stability changes:
108 *   - ContentHandler::resetDocument() removed
109 *   - attrs param of ContentHandler::startDocument() made const
110 *   - SAXExceptions thrown now have msgs
111 *   - removed duplicate function signatures that had 'const'
112 *       [ eg: getContentHander() ]
113 *   - changed getFeature and getProperty to apply to const objs
114 *   - setProperty now takes a void* instead of const void*
115 *   - SAX2XMLReaderImpl does not inherit from SAXParser anymore
116 *   - Reuse Validator (http://apache.org/xml/features/reuse-validator) implemented
117 *   - Features & Properties now read-only during parse
118 *
119 * Revision 1.2  2000/08/07 18:21:27  jpolast
120 * change SAX_EXPORT module to SAX2_EXPORT
121 *
122 * Revision 1.1  2000/08/02 18:02:35  jpolast
123 * initial checkin of sax2 implementation
124 * submitted by Simon Fell (simon@fell.com)
125 * and Joe Polastre (jpolast@apache.org)
126 *
127 *
128 */
129
130#ifndef SAX2XMLReader_HPP
131#define SAX2XMLReader_HPP
132
133#include <xercesc/util/XercesDefs.hpp>
134#include <xercesc/util/XMLUniDefs.hpp>
135#include <xercesc/framework/XMLValidator.hpp>
136#include <xercesc/framework/XMLPScanToken.hpp>
137
138XERCES_CPP_NAMESPACE_BEGIN
139
140class ContentHandler ;
141class DTDHandler;
142class EntityResolver;
143class ErrorHandler;
144class InputSource;
145class LexicalHandler;
146class DeclHandler;
147class XMLDocumentHandler;
148class Grammar;
149
150class SAX2_EXPORT SAX2XMLReader
151{
152public:
153    // -----------------------------------------------------------------------
154    //  Class types
155    // -----------------------------------------------------------------------
156    /** @name Public constants */
157    //@{
158
159    /** ValScheme enum used in setValidationScheme
160      *    Val_Never:  Do not report validation errors.
161      *    Val_Always: The parser will always report validation errors.
162      *    Val_Auto:   The parser will report validation errors only if a grammar is specified.
163      *
164      * @see #setValidationScheme
165      */
166    enum ValSchemes
167    {
168        Val_Never
169        , Val_Always
170        , Val_Auto
171    };
172    //@}
173
174
175    // -----------------------------------------------------------------------
176    //  Constructors and Destructor
177    // -----------------------------------------------------------------------
178    /** @name Constructors and Destructor */
179    //@{
180    /** The default constructor */
181    SAX2XMLReader()
182    {
183    }
184    /** The destructor */
185    virtual ~SAX2XMLReader()
186    {
187    }
188    //@}
189
190    //-----------------------------------------------------------------------
191    // The XMLReader interface
192    //-----------------------------------------------------------------------
193    /** @name Implementation of SAX 2.0 XMLReader interface's. */
194    //@{
195
196    /**
197      * This method returns the installed content handler.
198      *
199      * @return A pointer to the installed content handler object.
200      */
201    virtual ContentHandler* getContentHandler() const = 0 ;
202
203    /**
204      * This method returns the installed DTD handler.
205      *
206      * @return A pointer to the installed DTD handler object.
207      */
208    virtual DTDHandler* getDTDHandler() const = 0;
209
210    /**
211      * This method returns the installed entity resolver.
212      *
213      * @return A pointer to the installed entity resolver object.
214      */
215    virtual EntityResolver* getEntityResolver() const = 0 ;
216
217    /**
218      * This method returns the installed error handler.
219      *
220      * @return A pointer to the installed error handler object.
221      */
222    virtual ErrorHandler* getErrorHandler() const = 0 ;
223
224        /**
225     * Query the current state of any feature in a SAX2 XMLReader.
226          *
227          * @param name The unique identifier (URI) of the feature being set.
228          * @return The current state of the feature.
229     * @exception SAXNotRecognizedException If the requested feature is not known.
230          */
231        virtual bool getFeature(const XMLCh* const name) const = 0;
232
233        /**
234     * Query the current value of a property in a SAX2 XMLReader.
235     *
236     * The parser owns the returned pointer.  The memory allocated for
237     * the returned pointer will be destroyed when the parser is deleted.
238     *
239     * To ensure assessiblity of the returned information after the parser
240     * is deleted, callers need to copy and store the returned information
241     * somewhere else; otherwise you may get unexpected result.  Since the returned
242     * pointer is a generic void pointer, see
243     * http://xml.apache.org/xerces-c/program-sax2.html#SAX2Properties to learn
244     * exactly what type of property value each property returns for replication.
245     *
246     * @param name The unique identifier (URI) of the property being set.
247     * @return     The current value of the property.  The pointer spans the same
248     *             life-time as the parser.  A null pointer is returned if nothing
249     *             was specified externally.
250     * @exception  SAXNotRecognizedException If the requested property is not known.
251     */
252        virtual void* getProperty(const XMLCh* const name) const = 0 ;
253
254  /**
255    * Allow an application to register a document event handler.
256    *
257    * If the application does not register a document handler, all
258    * document events reported by the SAX parser will be silently
259    * ignored (this is the default behaviour implemented by
260    * HandlerBase).
261    *
262    * Applications may register a new or different handler in the
263    * middle of a parse, and the SAX parser must begin using the new
264    * handler immediately.
265    *
266    * @param handler The document handler.
267    * @see DocumentHandler#DocumentHandler
268    * @see HandlerBase#HandlerBase
269    */
270    virtual void setContentHandler(ContentHandler* const handler) = 0;
271
272  /**
273    * Allow an application to register a DTD event handler.
274    *
275    * If the application does not register a DTD handler, all DTD
276    * events reported by the SAX parser will be silently ignored (this
277    * is the default behaviour implemented by HandlerBase).
278    *
279    * Applications may register a new or different handler in the middle
280    * of a parse, and the SAX parser must begin using the new handler
281    * immediately.
282    *
283    * @param handler The DTD handler.
284    * @see DTDHandler#DTDHandler
285    * @see HandlerBase#HandlerBase
286    */
287    virtual void setDTDHandler(DTDHandler* const handler) = 0;
288
289  /**
290    * Allow an application to register a custom entity resolver.
291    *
292    * If the application does not register an entity resolver, the
293    * SAX parser will resolve system identifiers and open connections
294    * to entities itself (this is the default behaviour implemented in
295    * DefaultHandler).
296    *
297    * Applications may register a new or different entity resolver
298    * in the middle of a parse, and the SAX parser must begin using
299    * the new resolver immediately.
300    *
301    * @param resolver The object for resolving entities.
302    * @see EntityResolver#EntityResolver
303    * @see DefaultHandler#DefaultHandler
304    */
305    virtual void setEntityResolver(EntityResolver* const resolver) = 0;
306
307  /**
308    * Allow an application to register an error event handler.
309    *
310    * If the application does not register an error event handler,
311    * all error events reported by the SAX parser will be silently
312    * ignored, except for fatalError, which will throw a SAXException
313    * (this is the default behaviour implemented by HandlerBase).
314    *
315    * Applications may register a new or different handler in the
316    * middle of a parse, and the SAX parser must begin using the new
317    * handler immediately.
318    *
319    * @param handler The error handler.
320    * @see ErrorHandler#ErrorHandler
321    * @see SAXException#SAXException
322    * @see HandlerBase#HandlerBase
323    */
324    virtual void setErrorHandler(ErrorHandler* const handler) = 0;
325
326  /**
327    * Set the state of any feature in a SAX2 XMLReader.
328    * Supported features in SAX2 for xerces-c are:
329    * <br>(See http://xml.apache.org/xerces-c/program-sax2.html#SAX2Features for detail description).
330    *
331    * <br>http://xml.org/sax/features/validation (default: true)
332    * <br>http://xml.org/sax/features/namespaces (default: true)
333    * <br>http://xml.org/sax/features/namespace-prefixes (default: false)
334    * <br>http://apache.org/xml/features/validation/dynamic (default: false)
335    * <br>http://apache.org/xml/features/validation/reuse-grammar (default: false)
336    * <br>http://apache.org/xml/features/validation/schema (default: true)
337    * <br>http://apache.org/xml/features/validation/schema-full-checking (default: false)
338    * <br>http://apache.org/xml/features/nonvalidating/load-external-dtd (default: true)
339    * <br>http://apache.org/xml/features/continue-after-fatal-error (default: false)
340    * <br>http://apache.org/xml/features/validation-error-as-fatal (default: false)
341    * <br>http://apache.org/xml/features/validation/reuse-validator (Deprecated) (default: false)
342    *
343    * @param name The unique identifier (URI) of the feature.
344    * @param value The requested state of the feature (true or false).
345    * @exception SAXNotRecognizedException If the requested feature is not known.
346    * @exception SAXNotSupportedException Feature modification is not supported during parse
347    *
348    */
349        virtual void setFeature(const XMLCh* const name, const bool value) = 0;
350
351  /**
352    * Set the value of any property in a SAX2 XMLReader.
353    * Supported properties in SAX2 for xerces-c are:
354    * <br>(See http://xml.apache.org/xerces-c/program-sax2.html#SAX2Properties for detail description).
355    *
356    * <br>http://apache.org/xml/properties/schema/external-schemaLocation
357    * <br>http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation.
358    *
359    * It takes a void pointer as the property value.  Application is required to initialize this void
360    * pointer to a correct type.  See http://xml.apache.org/xerces-c/program-sax2.html#SAX2Properties
361    * to learn exactly what type of property value each property expects for processing.
362    * Passing a void pointer that was initialized with a wrong type will lead to unexpected result.
363    * If the same property is set more than once, the last one takes effect.
364    *
365    * @param name The unique identifier (URI) of the property being set.
366    * @param value The requested value for the property.  See
367    *            http://xml.apache.org/xerces-c/program-sax2.html#SAX2Properties to learn
368    *            exactly what type of property value each property expects for processing.
369    *            Passing a void pointer that was initialized with a wrong type will lead
370    *            to unexpected result.
371    * @exception SAXNotRecognizedException If the requested property is not known.
372    * @exception SAXNotSupportedException Property modification is not supported during parse
373    */
374        virtual void setProperty(const XMLCh* const name, void* value) = 0 ;
375
376  /**
377    * Parse an XML document.
378    *
379    * The application can use this method to instruct the SAX parser
380    * to begin parsing an XML document from any valid input
381    * source (a character stream, a byte stream, or a URI).
382    *
383    * Applications may not invoke this method while a parse is in
384    * progress (they should create a new Parser instead for each
385    * additional XML document).  Once a parse is complete, an
386    * application may reuse the same Parser object, possibly with a
387    * different input source.
388    *
389    * @param source The input source for the top-level of the
390    *               XML document.
391    * @exception SAXException Any SAX exception, possibly
392    *            wrapping another exception.
393    * @exception XMLException An exception from the parser or client
394    *            handler code.
395    * @see InputSource#InputSource
396    * @see #setEntityResolver
397    * @see #setDTDHandler
398    * @see #setDocumentHandler
399    * @see #setErrorHandler
400    */
401    virtual void parse
402    (
403        const   InputSource&    source
404    ) = 0;
405
406  /**
407    * Parse an XML document from a system identifier (URI).
408    *
409    * This method is a shortcut for the common case of reading a
410    * document from a system identifier.  It is the exact equivalent
411    * of the following:
412    *
413    * parse(new URLInputSource(systemId));
414    *
415    * If the system identifier is a URL, it must be fully resolved
416    * by the application before it is passed to the parser.
417    *
418    * @param systemId The system identifier (URI).
419    * @exception SAXException Any SAX exception, possibly
420    *            wrapping another exception.
421    * @exception XMLException An exception from the parser or client
422    *            handler code.
423    * @see #parse(InputSource)
424    */
425    virtual void parse
426    (
427        const   XMLCh* const    systemId
428    ) = 0;
429
430  /**
431    * Parse an XML document from a system identifier (URI).
432    *
433    * This method is a shortcut for the common case of reading a
434    * document from a system identifier.  It is the exact equivalent
435    * of the following:
436    *
437    * parse(new URLInputSource(systemId));
438    *
439    * If the system identifier is a URL, it must be fully resolved
440    * by the application before it is passed to the parser.
441    *
442    * @param systemId The system identifier (URI).
443    * @exception SAXException Any SAX exception, possibly
444    *            wrapping another exception.
445    * @exception XMLException An exception from the parser or client
446    *            handler code.
447    * @see #parse(InputSource)
448    */
449    virtual void parse
450    (
451        const   char* const     systemId
452    ) = 0;
453       
454    //@}
455
456    // -----------------------------------------------------------------------
457    //  SAX 2.0-ext
458    // -----------------------------------------------------------------------
459    /** @name SAX 2.0-ext */
460    //@{
461    /**
462      * This method returns the installed declaration handler.
463      *
464      * @return A pointer to the installed declaration handler object.
465      */
466    virtual DeclHandler* getDeclarationHandler() const = 0 ;
467
468        /**
469      * This method returns the installed lexical handler.
470      *
471      * @return A pointer to the installed lexical handler object.
472      */
473    virtual LexicalHandler* getLexicalHandler() const = 0 ;
474
475   /**
476    * Allow an application to register a declaration event handler.
477    *
478    * If the application does not register a declaration handler,
479    * all events reported by the SAX parser will be silently
480    * ignored. (this is the default behaviour implemented by DefaultHandler).
481    *
482    * Applications may register a new or different handler in the
483    * middle of a parse, and the SAX parser must begin using the new
484    * handler immediately.
485    *
486    * @param handler The DTD declaration handler.
487    * @see DeclHandler#DeclHandler
488    * @see SAXException#SAXException
489    * @see DefaultHandler#DefaultHandler
490    */
491    virtual void setDeclarationHandler(DeclHandler* const handler) = 0;
492
493   /**
494    * Allow an application to register a lexical event handler.
495    *
496    * If the application does not register a lexical handler,
497    * all events reported by the SAX parser will be silently
498    * ignored. (this is the default behaviour implemented by HandlerBase).
499    *
500    * Applications may register a new or different handler in the
501    * middle of a parse, and the SAX parser must begin using the new
502    * handler immediately.
503    *
504    * @param handler The error handler.
505    * @see LexicalHandler#LexicalHandler
506    * @see SAXException#SAXException
507    * @see HandlerBase#HandlerBase
508    */
509    virtual void setLexicalHandler(LexicalHandler* const handler) = 0;
510
511    //@}
512
513    // -----------------------------------------------------------------------
514    //  Getter Methods
515    // -----------------------------------------------------------------------
516    /** @name Getter Methods (Xerces-C specific) */
517    //@{
518    /**
519          * This method is used to get the current validator.
520          *
521          * <b>SAX2XMLReader assumes responsibility for the validator.  It will be
522          * deleted when the XMLReader is destroyed.</b>
523          *
524          * @return A pointer to the validator.  An application should not deleted
525          * the object returned.
526          *
527          */
528        virtual XMLValidator* getValidator() const = 0;
529
530    /** Get error count from the last parse operation.
531      *
532      * This method returns the error count from the last parse
533      * operation. Note that this count is actually stored in the
534      * scanner, so this method simply returns what the
535      * scanner reports.
536      *
537      * @return number of errors encountered during the latest
538      *                 parse operation.
539      */
540    virtual int getErrorCount() const = 0 ;
541
542    /**
543      * This method returns the state of the parser's
544      * exit-on-First-Fatal-Error flag.
545      *
546      * <p>Or you can query the feature "http://apache.org/xml/features/continue-after-fatal-error"
547      * which indicates the opposite state.</p>
548      *
549      * @return true, if the parser is currently configured to
550      *         exit on the first fatal error, false otherwise.
551      *
552      * @see #setExitOnFirstFatalError
553      * @see #getFeature
554      */
555    virtual bool getExitOnFirstFatalError() const = 0;
556
557    /**
558      * This method returns the state of the parser's
559      * validation-constraint-fatal flag.
560      *
561      * <p>Or you can query the feature "http://apache.org/xml/features/validation-error-as-fatal"
562      * which means the same thing.
563      *
564      * @return true, if the parser is currently configured to
565      *         set validation constraint errors as fatal, false
566      *         otherwise.
567      *
568      * @see #setValidationContraintFatal
569      * @see #getFeature
570      */
571    virtual bool getValidationConstraintFatal() const = 0;
572
573    /**
574      * Retrieve the grammar that is associated with the specified namespace key
575      *
576      * @param  nameSpaceKey Namespace key
577      * @return Grammar associated with the Namespace key.
578      */
579    virtual Grammar* getGrammar(const XMLCh* const nameSpaceKey) = 0;
580
581    /**
582      * Retrieve the grammar where the root element is declared.
583      *
584      * @return Grammar where root element declared
585      */
586    virtual Grammar* getRootGrammar() = 0;
587
588    /**
589      * Returns the string corresponding to a URI id from the URI string pool.
590      *
591      * @param uriId id of the string in the URI string pool.
592      * @return URI string corresponding to the URI id.
593      */
594    virtual const XMLCh* getURIText(unsigned int uriId) const = 0;
595
596    /**
597      * Returns the current src offset within the input source.
598      *
599      * @return offset within the input source
600      */
601    virtual unsigned int getSrcOffset() const = 0;
602
603    //@}
604
605    // -----------------------------------------------------------------------
606    //  Setter Methods
607    // -----------------------------------------------------------------------
608    /** @name Setter Methods (Xerces-C specific) */
609    //@{
610    /**
611          * This method is used to set a validator.
612          *
613          * <b>SAX2XMLReader assumes responsibility for the validator.  It will be
614          * deleted when the XMLReader is destroyed.</b>
615          *
616          * @param valueToAdopt A pointer to the validator that the reader should use.
617          *
618          */
619        virtual void setValidator(XMLValidator* valueToAdopt) = 0;
620
621    /**
622      * This method allows users to set the parser's behaviour when it
623      * encounters the first fatal error. If set to true, the parser
624      * will exit at the first fatal error. If false, then it will
625      * report the error and continue processing.
626      *
627      * <p>The default value is 'true' and the parser exits on the
628      * first fatal error.</p>
629      *
630      * <p>Or you can set the feature "http://apache.org/xml/features/continue-after-fatal-error"
631      * which has the opposite behaviour.</p>
632      *
633      * <p>If both the feature above and this function are used, the latter takes effect.</p>
634      *
635      * @param newState The value specifying whether the parser should
636      *                 continue or exit when it encounters the first
637      *                 fatal error.
638      *
639      * @see #getExitOnFirstFatalError
640      * @see #setFeature
641      */
642    virtual void setExitOnFirstFatalError(const bool newState) = 0;
643
644    /**
645      * This method allows users to set the parser's behaviour when it
646      * encounters a validtion constraint error. If set to true, and the
647      * the parser will treat validation error as fatal and will exit depends on the
648      * state of "getExitOnFirstFatalError". If false, then it will
649      * report the error and continue processing.
650      *
651      * Note: setting this true does not mean the validation error will be printed with
652      * the word "Fatal Error".   It is still printed as "Error", but the parser
653      * will exit if "setExitOnFirstFatalError" is set to true.
654      *
655      * <p>The default value is 'false'.</p>
656      *
657      * <p>Or you can set the feature "http://apache.org/xml/features/validation-error-as-fatal"
658      * which means the same thing.</p>
659      *
660      * <p>If both the feature above and this function are used, the latter takes effect.</p>
661      *
662      * @param newState If true, the parser will exit if "setExitOnFirstFatalError"
663      *                 is set to true.
664      *
665      * @see #getValidationConstraintFatal
666      * @see #setExitOnFirstFatalError
667      * @see #setFeature
668      */
669    virtual void setValidationConstraintFatal(const bool newState) = 0;
670    //@}
671
672
673    // -----------------------------------------------------------------------
674    //  Progressive scan methods
675    // -----------------------------------------------------------------------
676
677    /** @name Progressive scan methods */
678    //@{
679
680    /** Begin a progressive parse operation
681      *
682      * This method is used to start a progressive parse on a XML file.
683      * To continue parsing, subsequent calls must be to the parseNext
684      * method.
685      *
686      * It scans through the prolog and returns a token to be used on
687      * subsequent scanNext() calls. If the return value is true, then the
688      * token is legal and ready for further use. If it returns false, then
689      * the scan of the prolog failed and the token is not going to work on
690      * subsequent scanNext() calls.
691      *
692      * @param systemId A pointer to a Unicode string represting the path
693      *                 to the XML file to be parsed.
694      * @param toFill   A token maintaing state information to maintain
695      *                 internal consistency between invocation of 'parseNext'
696      *                 calls.
697      *
698      * @return 'true', if successful in parsing the prolog. It indicates the
699      *         user can go ahead with parsing the rest of the file. It
700      *         returns 'false' to indicate that the parser could parse the
701      *         prolog (which means the token will not be valid.)
702      *
703      * @see #parseNext
704      * @see #parseFirst(char*,...)
705      * @see #parseFirst(InputSource&,...)
706      */
707    virtual bool parseFirst
708    (
709        const   XMLCh* const    systemId
710        ,       XMLPScanToken&  toFill
711    ) = 0;
712
713    /** Begin a progressive parse operation
714      *
715      * This method is used to start a progressive parse on a XML file.
716      * To continue parsing, subsequent calls must be to the parseNext
717      * method.
718      *
719      * It scans through the prolog and returns a token to be used on
720      * subsequent scanNext() calls. If the return value is true, then the
721      * token is legal and ready for further use. If it returns false, then
722      * the scan of the prolog failed and the token is not going to work on
723      * subsequent scanNext() calls.
724      *
725      * @param systemId A pointer to a regular native string represting
726      *                 the path to the XML file to be parsed.
727      * @param toFill   A token maintaing state information to maintain
728      *                 internal consIstency between invocation of 'parseNext'
729      *                 calls.
730      *
731      * @return 'true', if successful in parsing the prolog. It indicates the
732      *         user can go ahead with parsing the rest of the file. It
733      *         returns 'false' to indicate that the parser could not parse
734      *         the prolog.
735      *
736      * @see #parseNext
737      * @see #parseFirst(XMLCh*,...)
738      * @see #parseFirst(InputSource&,...)
739      */
740    virtual bool parseFirst
741    (
742        const   char* const     systemId
743        ,       XMLPScanToken&  toFill
744    ) = 0;
745
746    /** Begin a progressive parse operation
747      *
748      * This method is used to start a progressive parse on a XML file.
749      * To continue parsing, subsequent calls must be to the parseNext
750      * method.
751      *
752      * It scans through the prolog and returns a token to be used on
753      * subsequent scanNext() calls. If the return value is true, then the
754      * token is legal and ready for further use. If it returns false, then
755      * the scan of the prolog failed and the token is not going to work on
756      * subsequent scanNext() calls.
757      *
758      * @param source   A const reference to the InputSource object which
759      *                 points to the XML file to be parsed.
760      * @param toFill   A token maintaing state information to maintain
761      *                 internal consistency between invocation of 'parseNext'
762      *                 calls.
763      *
764      * @return 'true', if successful in parsing the prolog. It indicates the
765      *         user can go ahead with parsing the rest of the file. It
766      *         returns 'false' to indicate that the parser could not parse
767      *         the prolog.
768      *
769      * @see #parseNext
770      * @see #parseFirst(XMLCh*,...)
771      * @see #parseFirst(char*,...)
772      */
773    virtual bool parseFirst
774    (
775        const   InputSource&    source
776        ,       XMLPScanToken&  toFill
777    ) = 0;
778
779    /** Continue a progressive parse operation
780      *
781      * This method is used to continue with progressive parsing of
782      * XML files started by a call to 'parseFirst' method.
783      *
784      * It parses the XML file and stops as soon as it comes across
785      * a XML token (as defined in the XML specification). Relevant
786      * callback handlers are invoked as required by the SAX
787      * specification.
788      *
789      * @param token A token maintaing state information to maintain
790      *              internal consistency between invocation of 'parseNext'
791      *              calls.
792      *
793      * @return 'true', if successful in parsing the next XML token.
794      *         It indicates the user can go ahead with parsing the rest
795      *         of the file. It returns 'false' to indicate that the parser
796      *         could not find next token as per the XML specification
797      *         production rule.
798      *
799      * @see #parseFirst(XMLCh*,...)
800      * @see #parseFirst(char*,...)
801      * @see #parseFirst(InputSource&,...)
802      */
803    virtual bool parseNext(XMLPScanToken& token) = 0;
804
805    /** Reset the parser after a progressive parse
806      *
807      * If a progressive parse loop exits before the end of the document
808      * is reached, the parser has no way of knowing this. So it will leave
809      * open any files or sockets or memory buffers that were in use at
810      * the time that the parse loop exited.
811      *
812      * The next parse operation will cause these open files and such to
813      * be closed, but the next parse operation might occur at some unknown
814      * future point. To avoid this problem, you should reset the parser if
815      * you exit the loop early.
816      *
817      * If you exited because of an error, then this cleanup will be done
818      * for you. Its only when you exit the file prematurely of your own
819      * accord, because you've found what you wanted in the file most
820      * likely.
821      *
822      * @param token A token maintaing state information to maintain
823      *              internal consistency between invocation of 'parseNext'
824      *              calls.
825      */
826    virtual void parseReset(XMLPScanToken& token) = 0;
827
828    //@}
829
830    // -----------------------------------------------------------------------
831    //  Grammar preparsing interface
832    // -----------------------------------------------------------------------
833
834    /** @name Grammar preparsing interface's. */
835    //@{
836    /**
837      * Preparse schema grammar (XML Schema, DTD, etc.) via an input source
838      * object.
839      *
840      * This method invokes the preparsing process on a schema grammar XML
841      * file specified by the SAX InputSource parameter. If the 'toCache' flag
842      * is enabled, the parser will cache the grammars for re-use. If a grammar
843      * key is found in the pool, no caching of any grammar will take place.
844      *
845      * <p><b>"Experimental - subject to change"</b></p>
846      *
847      * @param source A const reference to the SAX InputSource object which
848      *               points to the schema grammar file to be preparsed.
849      * @param grammarType The grammar type (Schema or DTD).
850      * @param toCache If <code>true</code>, we cache the preparsed grammar,
851      *                otherwise, no chaching. Default is <code>false</code>.
852      * @return The preparsed schema grammar object (SchemaGrammar or
853      *         DTDGrammar). That grammar object is owned by the parser.
854      *
855      * @exception SAXException Any SAX exception, possibly
856      *            wrapping another exception.
857      * @exception XMLException An exception from the parser or client
858      *            handler code.
859      * @exception DOMException A DOM exception as per DOM spec.
860      *
861      * @see InputSource#InputSource
862      */
863    virtual Grammar* loadGrammar(const InputSource& source,
864                                 const short grammarType,
865                                 const bool toCache = false) = 0;
866
867    /**
868      * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL
869      *
870      * This method invokes the preparsing process on a schema grammar XML
871      * file specified by the file path parameter. If the 'toCache' flag
872      * is enabled, the parser will cache the grammars for re-use. If a grammar
873      * key is found in the pool, no caching of any grammar will take place.
874      *
875      * <p><b>"Experimental - subject to change"</b></p>
876      *
877      * @param systemId A const XMLCh pointer to the Unicode string which
878      *                 contains the path to the XML grammar file to be
879      *                 preparsed.
880      * @param grammarType The grammar type (Schema or DTD).
881      * @param toCache If <code>true</code>, we cache the preparsed grammar,
882      *                otherwise, no chaching. Default is <code>false</code>.
883      * @return The preparsed schema grammar object (SchemaGrammar or
884      *         DTDGrammar). That grammar object is owned by the parser.
885      *
886      * @exception SAXException Any SAX exception, possibly
887      *            wrapping another exception.
888      * @exception XMLException An exception from the parser or client
889      *            handler code.
890      * @exception DOMException A DOM exception as per DOM spec.
891      */
892    virtual Grammar* loadGrammar(const XMLCh* const systemId,
893                                 const short grammarType,
894                                 const bool toCache = false) = 0;
895
896    /**
897      * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL
898      *
899      * This method invokes the preparsing process on a schema grammar XML
900      * file specified by the file path parameter. If the 'toCache' flag
901      * is enabled, the parser will cache the grammars for re-use. If a grammar
902      * key is found in the pool, no caching of any grammar will take place.
903      *
904      * <p><b>"Experimental - subject to change"</b></p>
905      *
906      * @param systemId A const char pointer to a native string which contains
907      *                 the path to the XML grammar file to be preparsed.
908      * @param grammarType The grammar type (Schema or DTD).
909      * @param toCache If <code>true</code>, we cache the preparsed grammar,
910      *                otherwise, no chaching. Default is <code>false</code>.
911      * @return The preparsed schema grammar object (SchemaGrammar or
912      *         DTDGrammar). That grammar object is owned by the parser.
913      *
914      * @exception SAXException Any SAX exception, possibly
915      *            wrapping another exception.
916      * @exception XMLException An exception from the parser or client
917      *            handler code.
918      * @exception DOMException A DOM exception as per DOM spec.
919      */
920    virtual Grammar* loadGrammar(const char* const systemId,
921                                 const short grammarType,
922                                 const bool toCache = false) = 0;
923
924    /**
925      * Clear the cached grammar pool
926      */
927    virtual void resetCachedGrammarPool() = 0;
928
929    /** Set maximum input buffer size
930      *
931      * This method allows users to limit the size of buffers used in parsing
932      * XML character data. The effect of setting this size is to limit the
933      * size of a ContentHandler::characters() call.
934      *
935      * The parser's default input buffer size is 1 megabyte.
936      *
937      * @param bufferSize The maximum input buffer size
938      */
939    void setInputBufferSize(const size_t bufferSize) {};
940
941    //@}
942
943
944    // -----------------------------------------------------------------------
945    //  Advanced document handler list maintenance methods
946    // -----------------------------------------------------------------------
947
948    /** @name Advanced document handler list maintenance methods */
949    //@{
950    /**
951      * This method installs the specified 'advanced' document callback
952      * handler, thereby allowing the user to customize the processing,
953      * if they choose to do so. Any number of advanced callback handlers
954      * maybe installed.
955      *
956      * <p>The methods in the advanced callback interface represent
957      * Xerces-C extensions. There is no specification for this interface.</p>
958      *
959      * @param toInstall A pointer to the users advanced callback handler.
960      *
961      * @see #removeAdvDocHandler
962      */
963    virtual void installAdvDocHandler(XMLDocumentHandler* const toInstall) = 0;
964
965    /**
966      * This method removes the 'advanced' document handler callback from
967      * the underlying parser scanner. If no handler is installed, advanced
968      * callbacks are not invoked by the scanner.
969      * @param toRemove A pointer to the advanced callback handler which
970      *                 should be removed.
971      *
972      * @see #installAdvDocHandler
973      */
974    virtual bool removeAdvDocHandler(XMLDocumentHandler* const toRemove) = 0;
975    //@}
976
977private :
978    /* The copy constructor, you cannot call this directly */
979    SAX2XMLReader(const SAX2XMLReader&);
980
981    /* The assignment operator, you cannot call this directly */
982    SAX2XMLReader& operator=(const SAX2XMLReader&);
983
984};
985
986XERCES_CPP_NAMESPACE_END
987
988#endif
Note: See TracBrowser for help on using the repository browser.