source: icXML/icXML-devel/src/xercesc/sax2/SAX2XMLReader.hpp @ 3157

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

Fixes for icXML 0.9

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