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: SAX2XMLFilterImpl.hpp 569031 2007-08-23 15:05:28Z amassari $ |
---|
20 | */ |
---|
21 | |
---|
22 | #if !defined(SAX2XMLFilterImpl_HPP) |
---|
23 | #define SAX2XMLFilterImpl_HPP |
---|
24 | |
---|
25 | #include <xercesc/sax2/SAX2XMLFilter.hpp> |
---|
26 | #include <xercesc/sax/EntityResolver.hpp> |
---|
27 | #include <xercesc/sax/DTDHandler.hpp> |
---|
28 | #include <xercesc/sax2/ContentHandler.hpp> |
---|
29 | #include <xercesc/sax/ErrorHandler.hpp> |
---|
30 | |
---|
31 | XERCES_CPP_NAMESPACE_BEGIN |
---|
32 | |
---|
33 | /** |
---|
34 | * This class implements the SAX2 'XMLFilterImpl' interface and should be |
---|
35 | * used by applications as the base class for their SAX2 filters. |
---|
36 | * This implementation simply forwards every call to the parent object. |
---|
37 | * |
---|
38 | */ |
---|
39 | |
---|
40 | class PARSERS_EXPORT SAX2XMLFilterImpl : |
---|
41 | public SAX2XMLFilter |
---|
42 | , public EntityResolver |
---|
43 | , public DTDHandler |
---|
44 | , public ContentHandler |
---|
45 | , public ErrorHandler |
---|
46 | { |
---|
47 | public : |
---|
48 | // ----------------------------------------------------------------------- |
---|
49 | // Constructors and Destructor |
---|
50 | // ----------------------------------------------------------------------- |
---|
51 | /** @name Constructors and Destructor */ |
---|
52 | //@{ |
---|
53 | /** The default constructor */ |
---|
54 | SAX2XMLFilterImpl(SAX2XMLReader* parent); |
---|
55 | |
---|
56 | /** The destructor */ |
---|
57 | ~SAX2XMLFilterImpl() ; |
---|
58 | //@} |
---|
59 | |
---|
60 | //----------------------------------------------------------------------- |
---|
61 | // Implementation of SAX2XMLReader Interface |
---|
62 | //----------------------------------------------------------------------- |
---|
63 | //----------------------------------------------------------------------- |
---|
64 | // The XMLReader interface |
---|
65 | //----------------------------------------------------------------------- |
---|
66 | /** @name Implementation of SAX 2.0 XMLReader interface's. */ |
---|
67 | //@{ |
---|
68 | |
---|
69 | /** |
---|
70 | * This method returns the installed content handler. |
---|
71 | * |
---|
72 | * @return A pointer to the installed content handler object. |
---|
73 | */ |
---|
74 | virtual ContentHandler* getContentHandler() const ; |
---|
75 | |
---|
76 | /** |
---|
77 | * This method returns the installed DTD handler. |
---|
78 | * |
---|
79 | * @return A pointer to the installed DTD handler object. |
---|
80 | */ |
---|
81 | virtual DTDHandler* getDTDHandler() const ; |
---|
82 | |
---|
83 | /** |
---|
84 | * This method returns the installed entity resolver. |
---|
85 | * |
---|
86 | * @return A pointer to the installed entity resolver object. |
---|
87 | */ |
---|
88 | virtual EntityResolver* getEntityResolver() const ; |
---|
89 | |
---|
90 | /** |
---|
91 | * This method returns the installed error handler. |
---|
92 | * |
---|
93 | * @return A pointer to the installed error handler object. |
---|
94 | */ |
---|
95 | virtual ErrorHandler* getErrorHandler() const ; |
---|
96 | |
---|
97 | /** |
---|
98 | * Query the current state of any feature in a SAX2 XMLReader. |
---|
99 | * |
---|
100 | * @param name The unique identifier (URI) of the feature being set. |
---|
101 | * @return The current state of the feature. |
---|
102 | * @exception SAXNotRecognizedException If the requested feature is not known. |
---|
103 | */ |
---|
104 | virtual bool getFeature(const XMLCh* const name) const ; |
---|
105 | |
---|
106 | /** |
---|
107 | * Query the current value of a property in a SAX2 XMLReader. |
---|
108 | * |
---|
109 | * The parser owns the returned pointer. The memory allocated for |
---|
110 | * the returned pointer will be destroyed when the parser is deleted. |
---|
111 | * |
---|
112 | * To ensure assessiblity of the returned information after the parser |
---|
113 | * is deleted, callers need to copy and store the returned information |
---|
114 | * somewhere else; otherwise you may get unexpected result. Since the returned |
---|
115 | * pointer is a generic void pointer, see |
---|
116 | * http://xerces.apache.org/xerces-c/program-sax2.html#SAX2Properties to learn |
---|
117 | * exactly what type of property value each property returns for replication. |
---|
118 | * |
---|
119 | * @param name The unique identifier (URI) of the property being set. |
---|
120 | * @return The current value of the property. The pointer spans the same |
---|
121 | * life-time as the parser. A null pointer is returned if nothing |
---|
122 | * was specified externally. |
---|
123 | * @exception SAXNotRecognizedException If the requested property is not known. |
---|
124 | */ |
---|
125 | virtual void* getProperty(const XMLCh* const name) const ; |
---|
126 | |
---|
127 | /** |
---|
128 | * Allow an application to register a document event handler. |
---|
129 | * |
---|
130 | * If the application does not register a document handler, all |
---|
131 | * document events reported by the SAX parser will be silently |
---|
132 | * ignored (this is the default behaviour implemented by |
---|
133 | * HandlerBase). |
---|
134 | * |
---|
135 | * Applications may register a new or different handler in the |
---|
136 | * middle of a parse, and the SAX parser must begin using the new |
---|
137 | * handler immediately. |
---|
138 | * |
---|
139 | * @param handler The document handler. |
---|
140 | * @see DocumentHandler#DocumentHandler |
---|
141 | * @see HandlerBase#HandlerBase |
---|
142 | */ |
---|
143 | virtual void setContentHandler(ContentHandler* const handler) ; |
---|
144 | |
---|
145 | /** |
---|
146 | * Allow an application to register a DTD event handler. |
---|
147 | * |
---|
148 | * If the application does not register a DTD handler, all DTD |
---|
149 | * events reported by the SAX parser will be silently ignored (this |
---|
150 | * is the default behaviour implemented by HandlerBase). |
---|
151 | * |
---|
152 | * Applications may register a new or different handler in the middle |
---|
153 | * of a parse, and the SAX parser must begin using the new handler |
---|
154 | * immediately. |
---|
155 | * |
---|
156 | * @param handler The DTD handler. |
---|
157 | * @see DTDHandler#DTDHandler |
---|
158 | * @see HandlerBase#HandlerBase |
---|
159 | */ |
---|
160 | virtual void setDTDHandler(DTDHandler* const handler) ; |
---|
161 | |
---|
162 | /** |
---|
163 | * Allow an application to register a custom entity resolver. |
---|
164 | * |
---|
165 | * If the application does not register an entity resolver, the |
---|
166 | * SAX parser will resolve system identifiers and open connections |
---|
167 | * to entities itself (this is the default behaviour implemented in |
---|
168 | * DefaultHandler). |
---|
169 | * |
---|
170 | * Applications may register a new or different entity resolver |
---|
171 | * in the middle of a parse, and the SAX parser must begin using |
---|
172 | * the new resolver immediately. |
---|
173 | * |
---|
174 | * @param resolver The object for resolving entities. |
---|
175 | * @see EntityResolver#EntityResolver |
---|
176 | * @see DefaultHandler#DefaultHandler |
---|
177 | */ |
---|
178 | virtual void setEntityResolver(EntityResolver* const resolver) ; |
---|
179 | |
---|
180 | /** |
---|
181 | * Allow an application to register an error event handler. |
---|
182 | * |
---|
183 | * If the application does not register an error event handler, |
---|
184 | * all error events reported by the SAX parser will be silently |
---|
185 | * ignored, except for fatalError, which will throw a SAXException |
---|
186 | * (this is the default behaviour implemented by HandlerBase). |
---|
187 | * |
---|
188 | * Applications may register a new or different handler in the |
---|
189 | * middle of a parse, and the SAX parser must begin using the new |
---|
190 | * handler immediately. |
---|
191 | * |
---|
192 | * @param handler The error handler. |
---|
193 | * @see ErrorHandler#ErrorHandler |
---|
194 | * @see SAXException#SAXException |
---|
195 | * @see HandlerBase#HandlerBase |
---|
196 | */ |
---|
197 | virtual void setErrorHandler(ErrorHandler* const handler) ; |
---|
198 | |
---|
199 | /** |
---|
200 | * Set the state of any feature in a SAX2 XMLReader. |
---|
201 | * Supported features in SAX2 for xerces-c are: |
---|
202 | * <br>(See http://xerces.apache.org/xerces-c/program-sax2.html#SAX2Features for detail description). |
---|
203 | * |
---|
204 | * <br>http://xml.org/sax/features/validation (default: true) |
---|
205 | * <br>http://xml.org/sax/features/namespaces (default: true) |
---|
206 | * <br>http://xml.org/sax/features/namespace-prefixes (default: false) |
---|
207 | * <br>http://apache.org/xml/features/validation/dynamic (default: false) |
---|
208 | * <br>http://apache.org/xml/features/validation/reuse-grammar (default: false) |
---|
209 | * <br>http://apache.org/xml/features/validation/schema (default: true) |
---|
210 | * <br>http://apache.org/xml/features/validation/schema-full-checking (default: false) |
---|
211 | * <br>http://apache.org/xml/features/nonvalidating/load-external-dtd (default: true) |
---|
212 | * <br>http://apache.org/xml/features/continue-after-fatal-error (default: false) |
---|
213 | * <br>http://apache.org/xml/features/validation-error-as-fatal (default: false) |
---|
214 | * <br>http://apache.org/xml/features/validation/reuse-validator (Deprecated) (default: false) |
---|
215 | * |
---|
216 | * @param name The unique identifier (URI) of the feature. |
---|
217 | * @param value The requested state of the feature (true or false). |
---|
218 | * @exception SAXNotRecognizedException If the requested feature is not known. |
---|
219 | * @exception SAXNotSupportedException Feature modification is not supported during parse |
---|
220 | * |
---|
221 | */ |
---|
222 | virtual void setFeature(const XMLCh* const name, const bool value) ; |
---|
223 | |
---|
224 | /** |
---|
225 | * Set the value of any property in a SAX2 XMLReader. |
---|
226 | * Supported properties in SAX2 for xerces-c are: |
---|
227 | * <br>(See http://xerces.apache.org/xerces-c/program-sax2.html#SAX2Properties for detail description). |
---|
228 | * |
---|
229 | * <br>http://apache.org/xml/properties/schema/external-schemaLocation |
---|
230 | * <br>http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation. |
---|
231 | * |
---|
232 | * It takes a void pointer as the property value. Application is required to initialize this void |
---|
233 | * pointer to a correct type. See http://xerces.apache.org/xerces-c/program-sax2.html#SAX2Properties |
---|
234 | * to learn exactly what type of property value each property expects for processing. |
---|
235 | * Passing a void pointer that was initialized with a wrong type will lead to unexpected result. |
---|
236 | * If the same property is set more than once, the last one takes effect. |
---|
237 | * |
---|
238 | * @param name The unique identifier (URI) of the property being set. |
---|
239 | * @param value The requested value for the property. See |
---|
240 | * http://xerces.apache.org/xerces-c/program-sax2.html#SAX2Properties to learn |
---|
241 | * exactly what type of property value each property expects for processing. |
---|
242 | * Passing a void pointer that was initialized with a wrong type will lead |
---|
243 | * to unexpected result. |
---|
244 | * @exception SAXNotRecognizedException If the requested property is not known. |
---|
245 | * @exception SAXNotSupportedException Property modification is not supported during parse |
---|
246 | */ |
---|
247 | virtual void setProperty(const XMLCh* const name, void* value) ; |
---|
248 | |
---|
249 | /** |
---|
250 | * Parse an XML document. |
---|
251 | * |
---|
252 | * The application can use this method to instruct the SAX parser |
---|
253 | * to begin parsing an XML document from any valid input |
---|
254 | * source (a character stream, a byte stream, or a URI). |
---|
255 | * |
---|
256 | * Applications may not invoke this method while a parse is in |
---|
257 | * progress (they should create a new Parser instead for each |
---|
258 | * additional XML document). Once a parse is complete, an |
---|
259 | * application may reuse the same Parser object, possibly with a |
---|
260 | * different input source. |
---|
261 | * |
---|
262 | * @param source The input source for the top-level of the |
---|
263 | * XML document. |
---|
264 | * @exception SAXException Any SAX exception, possibly |
---|
265 | * wrapping another exception. |
---|
266 | * @exception XMLException An exception from the parser or client |
---|
267 | * handler code. |
---|
268 | * @see InputSource#InputSource |
---|
269 | * @see #setEntityResolver |
---|
270 | * @see #setDTDHandler |
---|
271 | * @see #setDocumentHandler |
---|
272 | * @see #setErrorHandler |
---|
273 | */ |
---|
274 | virtual void parse |
---|
275 | ( |
---|
276 | const InputSource& source |
---|
277 | ) ; |
---|
278 | |
---|
279 | /** |
---|
280 | * Parse an XML document from a system identifier (URI). |
---|
281 | * |
---|
282 | * This method is a shortcut for the common case of reading a |
---|
283 | * document from a system identifier. It is the exact equivalent |
---|
284 | * of the following: |
---|
285 | * |
---|
286 | * parse(new URLInputSource(systemId)); |
---|
287 | * |
---|
288 | * If the system identifier is a URL, it must be fully resolved |
---|
289 | * by the application before it is passed to the parser. |
---|
290 | * |
---|
291 | * @param systemId The system identifier (URI). |
---|
292 | * @exception SAXException Any SAX exception, possibly |
---|
293 | * wrapping another exception. |
---|
294 | * @exception XMLException An exception from the parser or client |
---|
295 | * handler code. |
---|
296 | * @see #parse(InputSource) |
---|
297 | */ |
---|
298 | virtual void parse |
---|
299 | ( |
---|
300 | const XMLCh* const systemId |
---|
301 | ) ; |
---|
302 | |
---|
303 | /** |
---|
304 | * Parse an XML document from a system identifier (URI). |
---|
305 | * |
---|
306 | * This method is a shortcut for the common case of reading a |
---|
307 | * document from a system identifier. It is the exact equivalent |
---|
308 | * of the following: |
---|
309 | * |
---|
310 | * parse(new URLInputSource(systemId)); |
---|
311 | * |
---|
312 | * If the system identifier is a URL, it must be fully resolved |
---|
313 | * by the application before it is passed to the parser. |
---|
314 | * |
---|
315 | * @param systemId The system identifier (URI). |
---|
316 | * @exception SAXException Any SAX exception, possibly |
---|
317 | * wrapping another exception. |
---|
318 | * @exception XMLException An exception from the parser or client |
---|
319 | * handler code. |
---|
320 | * @see #parse(InputSource) |
---|
321 | */ |
---|
322 | virtual void parse |
---|
323 | ( |
---|
324 | const char* const systemId |
---|
325 | ) ; |
---|
326 | |
---|
327 | //@} |
---|
328 | |
---|
329 | // ----------------------------------------------------------------------- |
---|
330 | // SAX 2.0-ext |
---|
331 | // ----------------------------------------------------------------------- |
---|
332 | /** @name SAX 2.0-ext */ |
---|
333 | //@{ |
---|
334 | /** |
---|
335 | * This method returns the installed declaration handler. |
---|
336 | * |
---|
337 | * @return A pointer to the installed declaration handler object. |
---|
338 | */ |
---|
339 | virtual DeclHandler* getDeclarationHandler() const ; |
---|
340 | |
---|
341 | /** |
---|
342 | * This method returns the installed lexical handler. |
---|
343 | * |
---|
344 | * @return A pointer to the installed lexical handler object. |
---|
345 | */ |
---|
346 | virtual LexicalHandler* getLexicalHandler() const ; |
---|
347 | |
---|
348 | /** |
---|
349 | * Allow an application to register a declaration event handler. |
---|
350 | * |
---|
351 | * If the application does not register a declaration handler, |
---|
352 | * all events reported by the SAX parser will be silently |
---|
353 | * ignored. (this is the default behaviour implemented by DefaultHandler). |
---|
354 | * |
---|
355 | * Applications may register a new or different handler in the |
---|
356 | * middle of a parse, and the SAX parser must begin using the new |
---|
357 | * handler immediately. |
---|
358 | * |
---|
359 | * @param handler The DTD declaration handler. |
---|
360 | * @see DeclHandler#DeclHandler |
---|
361 | * @see SAXException#SAXException |
---|
362 | * @see DefaultHandler#DefaultHandler |
---|
363 | */ |
---|
364 | virtual void setDeclarationHandler(DeclHandler* const handler) ; |
---|
365 | |
---|
366 | /** |
---|
367 | * Allow an application to register a lexical event handler. |
---|
368 | * |
---|
369 | * If the application does not register a lexical handler, |
---|
370 | * all events reported by the SAX parser will be silently |
---|
371 | * ignored. (this is the default behaviour implemented by HandlerBase). |
---|
372 | * |
---|
373 | * Applications may register a new or different handler in the |
---|
374 | * middle of a parse, and the SAX parser must begin using the new |
---|
375 | * handler immediately. |
---|
376 | * |
---|
377 | * @param handler The error handler. |
---|
378 | * @see LexicalHandler#LexicalHandler |
---|
379 | * @see SAXException#SAXException |
---|
380 | * @see HandlerBase#HandlerBase |
---|
381 | */ |
---|
382 | virtual void setLexicalHandler(LexicalHandler* const handler) ; |
---|
383 | |
---|
384 | //@} |
---|
385 | |
---|
386 | // ----------------------------------------------------------------------- |
---|
387 | // Getter Methods |
---|
388 | // ----------------------------------------------------------------------- |
---|
389 | /** @name Getter Methods (Xerces-C specific) */ |
---|
390 | //@{ |
---|
391 | /** |
---|
392 | * This method is used to get the current validator. |
---|
393 | * |
---|
394 | * <b>SAX2XMLReader assumes responsibility for the validator. It will be |
---|
395 | * deleted when the XMLReader is destroyed.</b> |
---|
396 | * |
---|
397 | * @return A pointer to the validator. An application should not deleted |
---|
398 | * the object returned. |
---|
399 | * |
---|
400 | */ |
---|
401 | virtual XMLValidator* getValidator() const ; |
---|
402 | |
---|
403 | /** Get error count from the last parse operation. |
---|
404 | * |
---|
405 | * This method returns the error count from the last parse |
---|
406 | * operation. Note that this count is actually stored in the |
---|
407 | * scanner, so this method simply returns what the |
---|
408 | * scanner reports. |
---|
409 | * |
---|
410 | * @return number of errors encountered during the latest |
---|
411 | * parse operation. |
---|
412 | */ |
---|
413 | virtual int getErrorCount() const ; |
---|
414 | |
---|
415 | /** |
---|
416 | * This method returns the state of the parser's |
---|
417 | * exit-on-First-Fatal-Error flag. |
---|
418 | * |
---|
419 | * <p>Or you can query the feature "http://apache.org/xml/features/continue-after-fatal-error" |
---|
420 | * which indicates the opposite state.</p> |
---|
421 | * |
---|
422 | * @return true, if the parser is currently configured to |
---|
423 | * exit on the first fatal error, false otherwise. |
---|
424 | * |
---|
425 | * @see #setExitOnFirstFatalError |
---|
426 | * @see #getFeature |
---|
427 | */ |
---|
428 | virtual bool getExitOnFirstFatalError() const ; |
---|
429 | |
---|
430 | /** |
---|
431 | * This method returns the state of the parser's |
---|
432 | * validation-constraint-fatal flag. |
---|
433 | * |
---|
434 | * <p>Or you can query the feature "http://apache.org/xml/features/validation-error-as-fatal" |
---|
435 | * which means the same thing. |
---|
436 | * |
---|
437 | * @return true, if the parser is currently configured to |
---|
438 | * set validation constraint errors as fatal, false |
---|
439 | * otherwise. |
---|
440 | * |
---|
441 | * @see #setValidationContraintFatal |
---|
442 | * @see #getFeature |
---|
443 | */ |
---|
444 | virtual bool getValidationConstraintFatal() const ; |
---|
445 | |
---|
446 | /** |
---|
447 | * Retrieve the grammar that is associated with the specified namespace key |
---|
448 | * |
---|
449 | * @param nameSpaceKey Namespace key |
---|
450 | * @return Grammar associated with the Namespace key. |
---|
451 | */ |
---|
452 | virtual Grammar* getGrammar(const XMLCh* const nameSpaceKey); |
---|
453 | |
---|
454 | /** |
---|
455 | * Retrieve the grammar where the root element is declared. |
---|
456 | * |
---|
457 | * @return Grammar where root element declared |
---|
458 | */ |
---|
459 | virtual Grammar* getRootGrammar(); |
---|
460 | |
---|
461 | /** |
---|
462 | * Returns the string corresponding to a URI id from the URI string pool. |
---|
463 | * |
---|
464 | * @param uriId id of the string in the URI string pool. |
---|
465 | * @return URI string corresponding to the URI id. |
---|
466 | */ |
---|
467 | virtual const XMLCh* getURIText(unsigned int uriId) const; |
---|
468 | |
---|
469 | /** |
---|
470 | * Returns the current src offset within the input source. |
---|
471 | * To be used only while parsing is in progress. |
---|
472 | * |
---|
473 | * @return offset within the input source |
---|
474 | */ |
---|
475 | virtual unsigned int getSrcOffset() const; |
---|
476 | |
---|
477 | //@} |
---|
478 | |
---|
479 | // ----------------------------------------------------------------------- |
---|
480 | // Setter Methods |
---|
481 | // ----------------------------------------------------------------------- |
---|
482 | /** @name Setter Methods (Xerces-C specific) */ |
---|
483 | //@{ |
---|
484 | /** |
---|
485 | * This method is used to set a validator. |
---|
486 | * |
---|
487 | * <b>SAX2XMLReader assumes responsibility for the validator. It will be |
---|
488 | * deleted when the XMLReader is destroyed.</b> |
---|
489 | * |
---|
490 | * @param valueToAdopt A pointer to the validator that the reader should use. |
---|
491 | * |
---|
492 | */ |
---|
493 | virtual void setValidator(XMLValidator* valueToAdopt) ; |
---|
494 | |
---|
495 | /** |
---|
496 | * This method allows users to set the parser's behaviour when it |
---|
497 | * encounters the first fatal error. If set to true, the parser |
---|
498 | * will exit at the first fatal error. If false, then it will |
---|
499 | * report the error and continue processing. |
---|
500 | * |
---|
501 | * <p>The default value is 'true' and the parser exits on the |
---|
502 | * first fatal error.</p> |
---|
503 | * |
---|
504 | * <p>Or you can set the feature "http://apache.org/xml/features/continue-after-fatal-error" |
---|
505 | * which has the opposite behaviour.</p> |
---|
506 | * |
---|
507 | * <p>If both the feature above and this function are used, the latter takes effect.</p> |
---|
508 | * |
---|
509 | * @param newState The value specifying whether the parser should |
---|
510 | * continue or exit when it encounters the first |
---|
511 | * fatal error. |
---|
512 | * |
---|
513 | * @see #getExitOnFirstFatalError |
---|
514 | * @see #setFeature |
---|
515 | */ |
---|
516 | virtual void setExitOnFirstFatalError(const bool newState) ; |
---|
517 | |
---|
518 | /** |
---|
519 | * This method allows users to set the parser's behaviour when it |
---|
520 | * encounters a validtion constraint error. If set to true, and the |
---|
521 | * the parser will treat validation error as fatal and will exit depends on the |
---|
522 | * state of "getExitOnFirstFatalError". If false, then it will |
---|
523 | * report the error and continue processing. |
---|
524 | * |
---|
525 | * Note: setting this true does not mean the validation error will be printed with |
---|
526 | * the word "Fatal Error". It is still printed as "Error", but the parser |
---|
527 | * will exit if "setExitOnFirstFatalError" is set to true. |
---|
528 | * |
---|
529 | * <p>The default value is 'false'.</p> |
---|
530 | * |
---|
531 | * <p>Or you can set the feature "http://apache.org/xml/features/validation-error-as-fatal" |
---|
532 | * which means the same thing.</p> |
---|
533 | * |
---|
534 | * <p>If both the feature above and this function are used, the latter takes effect.</p> |
---|
535 | * |
---|
536 | * @param newState If true, the parser will exit if "setExitOnFirstFatalError" |
---|
537 | * is set to true. |
---|
538 | * |
---|
539 | * @see #getValidationConstraintFatal |
---|
540 | * @see #setExitOnFirstFatalError |
---|
541 | * @see #setFeature |
---|
542 | */ |
---|
543 | virtual void setValidationConstraintFatal(const bool newState) ; |
---|
544 | //@} |
---|
545 | |
---|
546 | |
---|
547 | // ----------------------------------------------------------------------- |
---|
548 | // Progressive scan methods |
---|
549 | // ----------------------------------------------------------------------- |
---|
550 | |
---|
551 | /** @name Progressive scan methods */ |
---|
552 | //@{ |
---|
553 | |
---|
554 | /** Begin a progressive parse operation |
---|
555 | * |
---|
556 | * This method is used to start a progressive parse on a XML file. |
---|
557 | * To continue parsing, subsequent calls must be to the parseNext |
---|
558 | * method. |
---|
559 | * |
---|
560 | * It scans through the prolog and returns a token to be used on |
---|
561 | * subsequent scanNext() calls. If the return value is true, then the |
---|
562 | * token is legal and ready for further use. If it returns false, then |
---|
563 | * the scan of the prolog failed and the token is not going to work on |
---|
564 | * subsequent scanNext() calls. |
---|
565 | * |
---|
566 | * @param systemId A pointer to a Unicode string represting the path |
---|
567 | * to the XML file to be parsed. |
---|
568 | * @param toFill A token maintaing state information to maintain |
---|
569 | * internal consistency between invocation of 'parseNext' |
---|
570 | * calls. |
---|
571 | * |
---|
572 | * @return 'true', if successful in parsing the prolog. It indicates the |
---|
573 | * user can go ahead with parsing the rest of the file. It |
---|
574 | * returns 'false' to indicate that the parser could parse the |
---|
575 | * prolog (which means the token will not be valid.) |
---|
576 | * |
---|
577 | * @see #parseNext |
---|
578 | * @see #parseFirst(char*,...) |
---|
579 | * @see #parseFirst(InputSource&,...) |
---|
580 | */ |
---|
581 | virtual bool parseFirst |
---|
582 | ( |
---|
583 | const XMLCh* const systemId |
---|
584 | , XMLPScanToken& toFill |
---|
585 | ) ; |
---|
586 | |
---|
587 | /** Begin a progressive parse operation |
---|
588 | * |
---|
589 | * This method is used to start a progressive parse on a XML file. |
---|
590 | * To continue parsing, subsequent calls must be to the parseNext |
---|
591 | * method. |
---|
592 | * |
---|
593 | * It scans through the prolog and returns a token to be used on |
---|
594 | * subsequent scanNext() calls. If the return value is true, then the |
---|
595 | * token is legal and ready for further use. If it returns false, then |
---|
596 | * the scan of the prolog failed and the token is not going to work on |
---|
597 | * subsequent scanNext() calls. |
---|
598 | * |
---|
599 | * @param systemId A pointer to a regular native string represting |
---|
600 | * the path to the XML file to be parsed. |
---|
601 | * @param toFill A token maintaing state information to maintain |
---|
602 | * internal consIstency between invocation of 'parseNext' |
---|
603 | * calls. |
---|
604 | * |
---|
605 | * @return 'true', if successful in parsing the prolog. It indicates the |
---|
606 | * user can go ahead with parsing the rest of the file. It |
---|
607 | * returns 'false' to indicate that the parser could not parse |
---|
608 | * the prolog. |
---|
609 | * |
---|
610 | * @see #parseNext |
---|
611 | * @see #parseFirst(XMLCh*,...) |
---|
612 | * @see #parseFirst(InputSource&,...) |
---|
613 | */ |
---|
614 | virtual bool parseFirst |
---|
615 | ( |
---|
616 | const char* const systemId |
---|
617 | , XMLPScanToken& toFill |
---|
618 | ) ; |
---|
619 | |
---|
620 | /** Begin a progressive parse operation |
---|
621 | * |
---|
622 | * This method is used to start a progressive parse on a XML file. |
---|
623 | * To continue parsing, subsequent calls must be to the parseNext |
---|
624 | * method. |
---|
625 | * |
---|
626 | * It scans through the prolog and returns a token to be used on |
---|
627 | * subsequent scanNext() calls. If the return value is true, then the |
---|
628 | * token is legal and ready for further use. If it returns false, then |
---|
629 | * the scan of the prolog failed and the token is not going to work on |
---|
630 | * subsequent scanNext() calls. |
---|
631 | * |
---|
632 | * @param source A const reference to the InputSource object which |
---|
633 | * points to the XML file to be parsed. |
---|
634 | * @param toFill A token maintaing state information to maintain |
---|
635 | * internal consistency between invocation of 'parseNext' |
---|
636 | * calls. |
---|
637 | * |
---|
638 | * @return 'true', if successful in parsing the prolog. It indicates the |
---|
639 | * user can go ahead with parsing the rest of the file. It |
---|
640 | * returns 'false' to indicate that the parser could not parse |
---|
641 | * the prolog. |
---|
642 | * |
---|
643 | * @see #parseNext |
---|
644 | * @see #parseFirst(XMLCh*,...) |
---|
645 | * @see #parseFirst(char*,...) |
---|
646 | */ |
---|
647 | virtual bool parseFirst |
---|
648 | ( |
---|
649 | const InputSource& source |
---|
650 | , XMLPScanToken& toFill |
---|
651 | ) ; |
---|
652 | |
---|
653 | /** Continue a progressive parse operation |
---|
654 | * |
---|
655 | * This method is used to continue with progressive parsing of |
---|
656 | * XML files started by a call to 'parseFirst' method. |
---|
657 | * |
---|
658 | * It parses the XML file and stops as soon as it comes across |
---|
659 | * a XML token (as defined in the XML specification). Relevant |
---|
660 | * callback handlers are invoked as required by the SAX |
---|
661 | * specification. |
---|
662 | * |
---|
663 | * @param token A token maintaing state information to maintain |
---|
664 | * internal consistency between invocation of 'parseNext' |
---|
665 | * calls. |
---|
666 | * |
---|
667 | * @return 'true', if successful in parsing the next XML token. |
---|
668 | * It indicates the user can go ahead with parsing the rest |
---|
669 | * of the file. It returns 'false' to indicate that the parser |
---|
670 | * could not find next token as per the XML specification |
---|
671 | * production rule. |
---|
672 | * |
---|
673 | * @see #parseFirst(XMLCh*,...) |
---|
674 | * @see #parseFirst(char*,...) |
---|
675 | * @see #parseFirst(InputSource&,...) |
---|
676 | */ |
---|
677 | virtual bool parseNext(XMLPScanToken& token) ; |
---|
678 | |
---|
679 | /** Reset the parser after a progressive parse |
---|
680 | * |
---|
681 | * If a progressive parse loop exits before the end of the document |
---|
682 | * is reached, the parser has no way of knowing this. So it will leave |
---|
683 | * open any files or sockets or memory buffers that were in use at |
---|
684 | * the time that the parse loop exited. |
---|
685 | * |
---|
686 | * The next parse operation will cause these open files and such to |
---|
687 | * be closed, but the next parse operation might occur at some unknown |
---|
688 | * future point. To avoid this problem, you should reset the parser if |
---|
689 | * you exit the loop early. |
---|
690 | * |
---|
691 | * If you exited because of an error, then this cleanup will be done |
---|
692 | * for you. Its only when you exit the file prematurely of your own |
---|
693 | * accord, because you've found what you wanted in the file most |
---|
694 | * likely. |
---|
695 | * |
---|
696 | * @param token A token maintaing state information to maintain |
---|
697 | * internal consistency between invocation of 'parseNext' |
---|
698 | * calls. |
---|
699 | */ |
---|
700 | virtual void parseReset(XMLPScanToken& token) ; |
---|
701 | |
---|
702 | //@} |
---|
703 | |
---|
704 | // ----------------------------------------------------------------------- |
---|
705 | // Implementation of the grammar preparsing interface |
---|
706 | // ----------------------------------------------------------------------- |
---|
707 | |
---|
708 | /** @name Implementation of Grammar preparsing interface's. */ |
---|
709 | //@{ |
---|
710 | /** |
---|
711 | * Preparse schema grammar (XML Schema, DTD, etc.) via an input source |
---|
712 | * object. |
---|
713 | * |
---|
714 | * This method invokes the preparsing process on a schema grammar XML |
---|
715 | * file specified by the SAX InputSource parameter. If the 'toCache' flag |
---|
716 | * is enabled, the parser will cache the grammars for re-use. If a grammar |
---|
717 | * key is found in the pool, no caching of any grammar will take place. |
---|
718 | * |
---|
719 | * <p><b>"Experimental - subject to change"</b></p> |
---|
720 | * |
---|
721 | * @param source A const reference to the SAX InputSource object which |
---|
722 | * points to the schema grammar file to be preparsed. |
---|
723 | * @param grammarType The grammar type (Schema or DTD). |
---|
724 | * @param toCache If <code>true</code>, we cache the preparsed grammar, |
---|
725 | * otherwise, no chaching. Default is <code>false</code>. |
---|
726 | * @return The preparsed schema grammar object (SchemaGrammar or |
---|
727 | * DTDGrammar). That grammar object is owned by the parser. |
---|
728 | * |
---|
729 | * @exception SAXException Any SAX exception, possibly |
---|
730 | * wrapping another exception. |
---|
731 | * @exception XMLException An exception from the parser or client |
---|
732 | * handler code. |
---|
733 | * @exception DOMException A DOM exception as per DOM spec. |
---|
734 | * |
---|
735 | * @see InputSource#InputSource |
---|
736 | */ |
---|
737 | virtual Grammar* loadGrammar(const InputSource& source, |
---|
738 | const short grammarType, |
---|
739 | const bool toCache = false); |
---|
740 | |
---|
741 | /** |
---|
742 | * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL |
---|
743 | * |
---|
744 | * This method invokes the preparsing process on a schema grammar XML |
---|
745 | * file specified by the file path parameter. If the 'toCache' flag |
---|
746 | * is enabled, the parser will cache the grammars for re-use. If a grammar |
---|
747 | * key is found in the pool, no caching of any grammar will take place. |
---|
748 | * |
---|
749 | * <p><b>"Experimental - subject to change"</b></p> |
---|
750 | * |
---|
751 | * @param systemId A const XMLCh pointer to the Unicode string which |
---|
752 | * contains the path to the XML grammar file to be |
---|
753 | * preparsed. |
---|
754 | * @param grammarType The grammar type (Schema or DTD). |
---|
755 | * @param toCache If <code>true</code>, we cache the preparsed grammar, |
---|
756 | * otherwise, no chaching. Default is <code>false</code>. |
---|
757 | * @return The preparsed schema grammar object (SchemaGrammar or |
---|
758 | * DTDGrammar). That grammar object is owned by the parser. |
---|
759 | * |
---|
760 | * @exception SAXException Any SAX exception, possibly |
---|
761 | * wrapping another exception. |
---|
762 | * @exception XMLException An exception from the parser or client |
---|
763 | * handler code. |
---|
764 | * @exception DOMException A DOM exception as per DOM spec. |
---|
765 | */ |
---|
766 | virtual Grammar* loadGrammar(const XMLCh* const systemId, |
---|
767 | const short grammarType, |
---|
768 | const bool toCache = false); |
---|
769 | |
---|
770 | /** |
---|
771 | * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL |
---|
772 | * |
---|
773 | * This method invokes the preparsing process on a schema grammar XML |
---|
774 | * file specified by the file path parameter. If the 'toCache' flag |
---|
775 | * is enabled, the parser will cache the grammars for re-use. If a grammar |
---|
776 | * key is found in the pool, no caching of any grammar will take place. |
---|
777 | * |
---|
778 | * <p><b>"Experimental - subject to change"</b></p> |
---|
779 | * |
---|
780 | * @param systemId A const char pointer to a native string which contains |
---|
781 | * the path to the XML grammar file to be preparsed. |
---|
782 | * @param grammarType The grammar type (Schema or DTD). |
---|
783 | * @param toCache If <code>true</code>, we cache the preparsed grammar, |
---|
784 | * otherwise, no chaching. Default is <code>false</code>. |
---|
785 | * @return The preparsed schema grammar object (SchemaGrammar or |
---|
786 | * DTDGrammar). That grammar object is owned by the parser. |
---|
787 | * |
---|
788 | * @exception SAXException Any SAX exception, possibly |
---|
789 | * wrapping another exception. |
---|
790 | * @exception XMLException An exception from the parser or client |
---|
791 | * handler code. |
---|
792 | * @exception DOMException A DOM exception as per DOM spec. |
---|
793 | */ |
---|
794 | virtual Grammar* loadGrammar(const char* const systemId, |
---|
795 | const short grammarType, |
---|
796 | const bool toCache = false); |
---|
797 | |
---|
798 | /** |
---|
799 | * Clear the cached grammar pool |
---|
800 | */ |
---|
801 | virtual void resetCachedGrammarPool(); |
---|
802 | |
---|
803 | /** Set maximum input buffer size |
---|
804 | * |
---|
805 | * This method allows users to limit the size of buffers used in parsing |
---|
806 | * XML character data. The effect of setting this size is to limit the |
---|
807 | * size of a ContentHandler::characters() call. |
---|
808 | * |
---|
809 | * The parser's default input buffer size is 1 megabyte. |
---|
810 | * |
---|
811 | * @param bufferSize The maximum input buffer size |
---|
812 | */ |
---|
813 | void setInputBufferSize(const size_t bufferSize); |
---|
814 | |
---|
815 | //@} |
---|
816 | |
---|
817 | |
---|
818 | // ----------------------------------------------------------------------- |
---|
819 | // Advanced document handler list maintenance methods |
---|
820 | // ----------------------------------------------------------------------- |
---|
821 | |
---|
822 | /** @name Advanced document handler list maintenance methods */ |
---|
823 | //@{ |
---|
824 | /** |
---|
825 | * This method installs the specified 'advanced' document callback |
---|
826 | * handler, thereby allowing the user to customize the processing, |
---|
827 | * if they choose to do so. Any number of advanced callback handlers |
---|
828 | * maybe installed. |
---|
829 | * |
---|
830 | * <p>The methods in the advanced callback interface represent |
---|
831 | * Xerces-C extensions. There is no specification for this interface.</p> |
---|
832 | * |
---|
833 | * @param toInstall A pointer to the users advanced callback handler. |
---|
834 | * |
---|
835 | * @see #removeAdvDocHandler |
---|
836 | */ |
---|
837 | virtual void installAdvDocHandler(XMLDocumentHandler* const toInstall) ; |
---|
838 | |
---|
839 | /** |
---|
840 | * This method removes the 'advanced' document handler callback from |
---|
841 | * the underlying parser scanner. If no handler is installed, advanced |
---|
842 | * callbacks are not invoked by the scanner. |
---|
843 | * @param toRemove A pointer to the advanced callback handler which |
---|
844 | * should be removed. |
---|
845 | * |
---|
846 | * @see #installAdvDocHandler |
---|
847 | */ |
---|
848 | virtual bool removeAdvDocHandler(XMLDocumentHandler* const toRemove) ; |
---|
849 | //@} |
---|
850 | |
---|
851 | |
---|
852 | // ----------------------------------------------------------------------- |
---|
853 | // The XMLFilter interface |
---|
854 | // ----------------------------------------------------------------------- |
---|
855 | |
---|
856 | /** @name Implementation of SAX 2.0 XMLFilter interface's. */ |
---|
857 | //@{ |
---|
858 | /** |
---|
859 | * This method returns the parent XMLReader object. |
---|
860 | * |
---|
861 | * @return A pointer to the parent XMLReader object. |
---|
862 | */ |
---|
863 | virtual SAX2XMLReader* getParent() const; |
---|
864 | |
---|
865 | /** |
---|
866 | * Sets the parent XMLReader object; parse requests will be forwarded to this |
---|
867 | * object, and callback notifications coming from it will be postprocessed |
---|
868 | * |
---|
869 | * @param parent The new XMLReader parent. |
---|
870 | * @see SAX2XMLReader#SAX2XMLReader |
---|
871 | */ |
---|
872 | virtual void setParent(SAX2XMLReader* parent); |
---|
873 | //@} |
---|
874 | |
---|
875 | // ----------------------------------------------------------------------- |
---|
876 | // Implementation of the EntityResolver interface |
---|
877 | // ----------------------------------------------------------------------- |
---|
878 | /** @name The EntityResolver interface */ |
---|
879 | //@{ |
---|
880 | |
---|
881 | /** |
---|
882 | * Allow the application to resolve external entities. |
---|
883 | * |
---|
884 | * <p>The Parser will call this method before opening any external |
---|
885 | * entity except the top-level document entity (including the |
---|
886 | * external DTD subset, external entities referenced within the |
---|
887 | * DTD, and external entities referenced within the document |
---|
888 | * element): the application may request that the parser resolve |
---|
889 | * the entity itself, that it use an alternative URI, or that it |
---|
890 | * use an entirely different input source.</p> |
---|
891 | * |
---|
892 | * <p>Application writers can use this method to redirect external |
---|
893 | * system identifiers to secure and/or local URIs, to look up |
---|
894 | * public identifiers in a catalogue, or to read an entity from a |
---|
895 | * database or other input source (including, for example, a dialog |
---|
896 | * box).</p> |
---|
897 | * |
---|
898 | * <p>If the system identifier is a URL, the SAX parser must |
---|
899 | * resolve it fully before reporting it to the application.</p> |
---|
900 | * |
---|
901 | * @param publicId The public identifier of the external entity |
---|
902 | * being referenced, or null if none was supplied. |
---|
903 | * @param systemId The system identifier of the external entity |
---|
904 | * being referenced. |
---|
905 | * @return An InputSource object describing the new input source, |
---|
906 | * or null to request that the parser open a regular |
---|
907 | * URI connection to the system identifier. |
---|
908 | * The returned InputSource is owned by the parser which is |
---|
909 | * responsible to clean up the memory. |
---|
910 | * @exception SAXException Any SAX exception, possibly |
---|
911 | * wrapping another exception. |
---|
912 | * @exception IOException An IO exception, |
---|
913 | * possibly the result of creating a new InputStream |
---|
914 | * or Reader for the InputSource. |
---|
915 | * @see InputSource#InputSource |
---|
916 | */ |
---|
917 | virtual InputSource* resolveEntity |
---|
918 | ( |
---|
919 | const XMLCh* const publicId |
---|
920 | , const XMLCh* const systemId |
---|
921 | ); |
---|
922 | |
---|
923 | //@} |
---|
924 | |
---|
925 | // ----------------------------------------------------------------------- |
---|
926 | // Implementation of the DTDHandler interface |
---|
927 | // ----------------------------------------------------------------------- |
---|
928 | /** @name The DTD handler interface */ |
---|
929 | //@{ |
---|
930 | /** |
---|
931 | * Receive notification of a notation declaration event. |
---|
932 | * |
---|
933 | * <p>It is up to the application to record the notation for later |
---|
934 | * reference, if necessary.</p> |
---|
935 | * |
---|
936 | * <p>If a system identifier is present, and it is a URL, the SAX |
---|
937 | * parser must resolve it fully before passing it to the |
---|
938 | * application.</p> |
---|
939 | * |
---|
940 | * @param name The notation name. |
---|
941 | * @param publicId The notation's public identifier, or null if |
---|
942 | * none was given. |
---|
943 | * @param systemId The notation's system identifier, or null if |
---|
944 | * none was given. |
---|
945 | * @exception SAXException Any SAX exception, possibly |
---|
946 | * wrapping another exception. |
---|
947 | * @see #unparsedEntityDecl |
---|
948 | * @see AttributeList#AttributeList |
---|
949 | */ |
---|
950 | virtual void notationDecl |
---|
951 | ( |
---|
952 | const XMLCh* const name |
---|
953 | , const XMLCh* const publicId |
---|
954 | , const XMLCh* const systemId |
---|
955 | ); |
---|
956 | |
---|
957 | /** |
---|
958 | * Receive notification of an unparsed entity declaration event. |
---|
959 | * |
---|
960 | * <p>Note that the notation name corresponds to a notation |
---|
961 | * reported by the notationDecl() event. It is up to the |
---|
962 | * application to record the entity for later reference, if |
---|
963 | * necessary.</p> |
---|
964 | * |
---|
965 | * <p>If the system identifier is a URL, the parser must resolve it |
---|
966 | * fully before passing it to the application.</p> |
---|
967 | * |
---|
968 | * @exception SAXException Any SAX exception, possibly |
---|
969 | * wrapping another exception. |
---|
970 | * @param name The unparsed entity's name. |
---|
971 | * @param publicId The entity's public identifier, or null if none |
---|
972 | * was given. |
---|
973 | * @param systemId The entity's system identifier (it must always |
---|
974 | * have one). |
---|
975 | * @param notationName The name of the associated notation. |
---|
976 | * @see #notationDecl |
---|
977 | * @see AttributeList#AttributeList |
---|
978 | */ |
---|
979 | virtual void unparsedEntityDecl |
---|
980 | ( |
---|
981 | const XMLCh* const name |
---|
982 | , const XMLCh* const publicId |
---|
983 | , const XMLCh* const systemId |
---|
984 | , const XMLCh* const notationName |
---|
985 | ); |
---|
986 | |
---|
987 | /** |
---|
988 | * Reset the DocType object on its reuse |
---|
989 | * |
---|
990 | * <p>This method helps in reseting the DTD object implementational |
---|
991 | * defaults each time the DTD is begun.</p> |
---|
992 | * |
---|
993 | */ |
---|
994 | virtual void resetDocType(); |
---|
995 | |
---|
996 | //@} |
---|
997 | |
---|
998 | // ----------------------------------------------------------------------- |
---|
999 | // Implementation of the ContentHandler interface |
---|
1000 | // ----------------------------------------------------------------------- |
---|
1001 | /** @name The virtual document handler interface */ |
---|
1002 | |
---|
1003 | //@{ |
---|
1004 | /** |
---|
1005 | * Receive notification of character data. |
---|
1006 | * |
---|
1007 | * <p>The Parser will call this method to report each chunk of |
---|
1008 | * character data. SAX parsers may return all contiguous character |
---|
1009 | * data in a single chunk, or they may split it into several |
---|
1010 | * chunks; however, all of the characters in any single event |
---|
1011 | * must come from the same external entity, so that the Locator |
---|
1012 | * provides useful information.</p> |
---|
1013 | * |
---|
1014 | * <p>The application must not attempt to read from the array |
---|
1015 | * outside of the specified range.</p> |
---|
1016 | * |
---|
1017 | * <p>Note that some parsers will report whitespace using the |
---|
1018 | * ignorableWhitespace() method rather than this one (validating |
---|
1019 | * parsers must do so).</p> |
---|
1020 | * |
---|
1021 | * @param chars The characters from the XML document. |
---|
1022 | * @param length The number of characters to read from the array. |
---|
1023 | * @exception SAXException Any SAX exception, possibly |
---|
1024 | * wrapping another exception. |
---|
1025 | * @see #ignorableWhitespace |
---|
1026 | * @see Locator#Locator |
---|
1027 | */ |
---|
1028 | virtual void characters |
---|
1029 | ( |
---|
1030 | const XMLCh* const chars |
---|
1031 | , const unsigned int length |
---|
1032 | ); |
---|
1033 | |
---|
1034 | /** |
---|
1035 | * Receive notification of the end of a document. |
---|
1036 | * |
---|
1037 | * <p>The SAX parser will invoke this method only once, and it will |
---|
1038 | * be the last method invoked during the parse. The parser shall |
---|
1039 | * not invoke this method until it has either abandoned parsing |
---|
1040 | * (because of an unrecoverable error) or reached the end of |
---|
1041 | * input.</p> |
---|
1042 | * |
---|
1043 | * @exception SAXException Any SAX exception, possibly |
---|
1044 | * wrapping another exception. |
---|
1045 | */ |
---|
1046 | virtual void endDocument (); |
---|
1047 | |
---|
1048 | /** |
---|
1049 | * Receive notification of the end of an element. |
---|
1050 | * |
---|
1051 | * <p>The SAX parser will invoke this method at the end of every |
---|
1052 | * element in the XML document; there will be a corresponding |
---|
1053 | * startElement() event for every endElement() event (even when the |
---|
1054 | * element is empty).</p> |
---|
1055 | * |
---|
1056 | * @param uri The URI of the asscioated namespace for this element |
---|
1057 | * @param localname The local part of the element name |
---|
1058 | * @param qname The QName of this element |
---|
1059 | * @exception SAXException Any SAX exception, possibly |
---|
1060 | * wrapping another exception. |
---|
1061 | */ |
---|
1062 | virtual void endElement |
---|
1063 | ( |
---|
1064 | const XMLCh* const uri, |
---|
1065 | const XMLCh* const localname, |
---|
1066 | const XMLCh* const qname |
---|
1067 | ); |
---|
1068 | |
---|
1069 | /** |
---|
1070 | * Receive notification of ignorable whitespace in element content. |
---|
1071 | * |
---|
1072 | * <p>Validating Parsers must use this method to report each chunk |
---|
1073 | * of ignorable whitespace (see the W3C XML 1.0 recommendation, |
---|
1074 | * section 2.10): non-validating parsers may also use this method |
---|
1075 | * if they are capable of parsing and using content models.</p> |
---|
1076 | * |
---|
1077 | * <p>SAX parsers may return all contiguous whitespace in a single |
---|
1078 | * chunk, or they may split it into several chunks; however, all of |
---|
1079 | * the characters in any single event must come from the same |
---|
1080 | * external entity, so that the Locator provides useful |
---|
1081 | * information.</p> |
---|
1082 | * |
---|
1083 | * <p>The application must not attempt to read from the array |
---|
1084 | * outside of the specified range.</p> |
---|
1085 | * |
---|
1086 | * @param chars The characters from the XML document. |
---|
1087 | * @param length The number of characters to read from the array. |
---|
1088 | * @exception SAXException Any SAX exception, possibly |
---|
1089 | * wrapping another exception. |
---|
1090 | * @see #characters |
---|
1091 | */ |
---|
1092 | virtual void ignorableWhitespace |
---|
1093 | ( |
---|
1094 | const XMLCh* const chars |
---|
1095 | , const unsigned int length |
---|
1096 | ); |
---|
1097 | |
---|
1098 | /** |
---|
1099 | * Receive notification of a processing instruction. |
---|
1100 | * |
---|
1101 | * <p>The Parser will invoke this method once for each processing |
---|
1102 | * instruction found: note that processing instructions may occur |
---|
1103 | * before or after the main document element.</p> |
---|
1104 | * |
---|
1105 | * <p>A SAX parser should never report an XML declaration (XML 1.0, |
---|
1106 | * section 2.8) or a text declaration (XML 1.0, section 4.3.1) |
---|
1107 | * using this method.</p> |
---|
1108 | * |
---|
1109 | * @param target The processing instruction target. |
---|
1110 | * @param data The processing instruction data, or null if |
---|
1111 | * none was supplied. |
---|
1112 | * @exception SAXException Any SAX exception, possibly |
---|
1113 | * wrapping another exception. |
---|
1114 | */ |
---|
1115 | virtual void processingInstruction |
---|
1116 | ( |
---|
1117 | const XMLCh* const target |
---|
1118 | , const XMLCh* const data |
---|
1119 | ); |
---|
1120 | |
---|
1121 | /** |
---|
1122 | * Receive an object for locating the origin of SAX document events. |
---|
1123 | * |
---|
1124 | * SAX parsers are strongly encouraged (though not absolutely |
---|
1125 | * required) to supply a locator: if it does so, it must supply |
---|
1126 | * the locator to the application by invoking this method before |
---|
1127 | * invoking any of the other methods in the DocumentHandler |
---|
1128 | * interface. |
---|
1129 | * |
---|
1130 | * The locator allows the application to determine the end |
---|
1131 | * position of any document-related event, even if the parser is |
---|
1132 | * not reporting an error. Typically, the application will |
---|
1133 | * use this information for reporting its own errors (such as |
---|
1134 | * character content that does not match an application's |
---|
1135 | * business rules). The information returned by the locator |
---|
1136 | * is probably not sufficient for use with a search engine. |
---|
1137 | * |
---|
1138 | * Note that the locator will return correct information only |
---|
1139 | * during the invocation of the events in this interface. The |
---|
1140 | * application should not attempt to use it at any other time. |
---|
1141 | * |
---|
1142 | * @param locator An object that can return the location of |
---|
1143 | * any SAX document event. The object is only |
---|
1144 | * 'on loan' to the client code and they are not |
---|
1145 | * to attempt to delete or modify it in any way! |
---|
1146 | * |
---|
1147 | * @see Locator#Locator |
---|
1148 | */ |
---|
1149 | virtual void setDocumentLocator(const Locator* const locator); |
---|
1150 | |
---|
1151 | /** |
---|
1152 | * Receive notification of the beginning of a document. |
---|
1153 | * |
---|
1154 | * <p>The SAX parser will invoke this method only once, before any |
---|
1155 | * other methods in this interface or in DTDHandler (except for |
---|
1156 | * setDocumentLocator).</p> |
---|
1157 | * |
---|
1158 | * @exception SAXException Any SAX exception, possibly |
---|
1159 | * wrapping another exception. |
---|
1160 | */ |
---|
1161 | virtual void startDocument(); |
---|
1162 | |
---|
1163 | /** |
---|
1164 | * Receive notification of the beginning of an element. |
---|
1165 | * |
---|
1166 | * <p>The Parser will invoke this method at the beginning of every |
---|
1167 | * element in the XML document; there will be a corresponding |
---|
1168 | * endElement() event for every startElement() event (even when the |
---|
1169 | * element is empty). All of the element's content will be |
---|
1170 | * reported, in order, before the corresponding endElement() |
---|
1171 | * event.</p> |
---|
1172 | * |
---|
1173 | * <p>Note that the attribute list provided will |
---|
1174 | * contain only attributes with explicit values (specified or |
---|
1175 | * defaulted): #IMPLIED attributes will be omitted.</p> |
---|
1176 | * |
---|
1177 | * @param uri The URI of the asscioated namespace for this element |
---|
1178 | * @param localname The local part of the element name |
---|
1179 | * @param qname The QName of this element |
---|
1180 | * @param attrs The attributes attached to the element, if any. |
---|
1181 | * @exception SAXException Any SAX exception, possibly |
---|
1182 | * wrapping another exception. |
---|
1183 | * @see #endElement |
---|
1184 | * @see Attributes#Attributes |
---|
1185 | */ |
---|
1186 | virtual void startElement |
---|
1187 | ( |
---|
1188 | const XMLCh* const uri, |
---|
1189 | const XMLCh* const localname, |
---|
1190 | const XMLCh* const qname, |
---|
1191 | const Attributes& attrs |
---|
1192 | ); |
---|
1193 | |
---|
1194 | /** |
---|
1195 | * Receive notification of the start of an namespace prefix mapping. |
---|
1196 | * |
---|
1197 | * <p>By default, do nothing. Application writers may override this |
---|
1198 | * method in a subclass to take specific actions at the start of |
---|
1199 | * each namespace prefix mapping.</p> |
---|
1200 | * |
---|
1201 | * @param prefix The namespace prefix used |
---|
1202 | * @param uri The namespace URI used. |
---|
1203 | * @exception SAXException Any SAX exception, possibly |
---|
1204 | * wrapping another exception. |
---|
1205 | */ |
---|
1206 | virtual void startPrefixMapping |
---|
1207 | ( |
---|
1208 | const XMLCh* const prefix, |
---|
1209 | const XMLCh* const uri |
---|
1210 | ); |
---|
1211 | |
---|
1212 | /** |
---|
1213 | * Receive notification of the end of an namespace prefix mapping. |
---|
1214 | * |
---|
1215 | * <p>By default, do nothing. Application writers may override this |
---|
1216 | * method in a subclass to take specific actions at the end of |
---|
1217 | * each namespace prefix mapping.</p> |
---|
1218 | * |
---|
1219 | * @param prefix The namespace prefix used |
---|
1220 | * @exception SAXException Any SAX exception, possibly |
---|
1221 | * wrapping another exception. |
---|
1222 | */ |
---|
1223 | virtual void endPrefixMapping |
---|
1224 | ( |
---|
1225 | const XMLCh* const prefix |
---|
1226 | ); |
---|
1227 | |
---|
1228 | /** |
---|
1229 | * Receive notification of a skipped entity |
---|
1230 | * |
---|
1231 | * <p>The parser will invoke this method once for each entity |
---|
1232 | * skipped. All processors may skip external entities, |
---|
1233 | * depending on the values of the features:<br> |
---|
1234 | * http://xml.org/sax/features/external-general-entities<br> |
---|
1235 | * http://xml.org/sax/features/external-parameter-entities</p> |
---|
1236 | * |
---|
1237 | * <p>Note: Xerces (specifically) never skips any entities, regardless |
---|
1238 | * of the above features. This function is never called in the |
---|
1239 | * Xerces implementation of SAX2.</p> |
---|
1240 | * |
---|
1241 | * <p>Introduced with SAX2</p> |
---|
1242 | * |
---|
1243 | * @param name The name of the skipped entity. If it is a parameter entity, |
---|
1244 | * the name will begin with %, and if it is the external DTD subset, |
---|
1245 | * it will be the string [dtd]. |
---|
1246 | * @exception SAXException Any SAX exception, possibly |
---|
1247 | * wrapping another exception. |
---|
1248 | */ |
---|
1249 | virtual void skippedEntity |
---|
1250 | ( |
---|
1251 | const XMLCh* const name |
---|
1252 | ); |
---|
1253 | |
---|
1254 | //@} |
---|
1255 | |
---|
1256 | // ----------------------------------------------------------------------- |
---|
1257 | // Implementation of the ErrorHandler interface |
---|
1258 | // ----------------------------------------------------------------------- |
---|
1259 | /** @name The error handler interface */ |
---|
1260 | //@{ |
---|
1261 | /** |
---|
1262 | * Receive notification of a warning. |
---|
1263 | * |
---|
1264 | * <p>SAX parsers will use this method to report conditions that |
---|
1265 | * are not errors or fatal errors as defined by the XML 1.0 |
---|
1266 | * recommendation. The default behaviour is to take no action.</p> |
---|
1267 | * |
---|
1268 | * <p>The SAX parser must continue to provide normal parsing events |
---|
1269 | * after invoking this method: it should still be possible for the |
---|
1270 | * application to process the document through to the end.</p> |
---|
1271 | * |
---|
1272 | * @param exc The warning information encapsulated in a |
---|
1273 | * SAX parse exception. |
---|
1274 | * @exception SAXException Any SAX exception, possibly |
---|
1275 | * wrapping another exception. |
---|
1276 | * @see SAXParseException#SAXParseException |
---|
1277 | */ |
---|
1278 | virtual void warning(const SAXParseException& exc); |
---|
1279 | |
---|
1280 | /** |
---|
1281 | * Receive notification of a recoverable error. |
---|
1282 | * |
---|
1283 | * <p>This corresponds to the definition of "error" in section 1.2 |
---|
1284 | * of the W3C XML 1.0 Recommendation. For example, a validating |
---|
1285 | * parser would use this callback to report the violation of a |
---|
1286 | * validity constraint. The default behaviour is to take no |
---|
1287 | * action.</p> |
---|
1288 | * |
---|
1289 | * <p>The SAX parser must continue to provide normal parsing events |
---|
1290 | * after invoking this method: it should still be possible for the |
---|
1291 | * application to process the document through to the end. If the |
---|
1292 | * application cannot do so, then the parser should report a fatal |
---|
1293 | * error even if the XML 1.0 recommendation does not require it to |
---|
1294 | * do so.</p> |
---|
1295 | * |
---|
1296 | * @param exc The error information encapsulated in a |
---|
1297 | * SAX parse exception. |
---|
1298 | * @exception SAXException Any SAX exception, possibly |
---|
1299 | * wrapping another exception. |
---|
1300 | * @see SAXParseException#SAXParseException |
---|
1301 | */ |
---|
1302 | virtual void error(const SAXParseException& exc); |
---|
1303 | |
---|
1304 | /** |
---|
1305 | * Receive notification of a non-recoverable error. |
---|
1306 | * |
---|
1307 | * <p>This corresponds to the definition of "fatal error" in |
---|
1308 | * section 1.2 of the W3C XML 1.0 Recommendation. For example, a |
---|
1309 | * parser would use this callback to report the violation of a |
---|
1310 | * well-formedness constraint.</p> |
---|
1311 | * |
---|
1312 | * <p>The application must assume that the document is unusable |
---|
1313 | * after the parser has invoked this method, and should continue |
---|
1314 | * (if at all) only for the sake of collecting addition error |
---|
1315 | * messages: in fact, SAX parsers are free to stop reporting any |
---|
1316 | * other events once this method has been invoked.</p> |
---|
1317 | * |
---|
1318 | * @param exc The error information encapsulated in a |
---|
1319 | * SAX parse exception. |
---|
1320 | * @exception SAXException Any SAX exception, possibly |
---|
1321 | * wrapping another exception. |
---|
1322 | * @see SAXParseException#SAXParseException |
---|
1323 | */ |
---|
1324 | virtual void fatalError(const SAXParseException& exc); |
---|
1325 | |
---|
1326 | /** |
---|
1327 | * Reset the Error handler object on its reuse |
---|
1328 | * |
---|
1329 | * <p>This method helps in reseting the Error handler object |
---|
1330 | * implementational defaults each time the Error handler is begun.</p> |
---|
1331 | * |
---|
1332 | */ |
---|
1333 | virtual void resetErrors(); |
---|
1334 | |
---|
1335 | //@} |
---|
1336 | |
---|
1337 | |
---|
1338 | private : |
---|
1339 | // ----------------------------------------------------------------------- |
---|
1340 | // Unimplemented constructors and operators |
---|
1341 | // ----------------------------------------------------------------------- |
---|
1342 | SAX2XMLFilterImpl(const SAX2XMLFilterImpl&); |
---|
1343 | SAX2XMLFilterImpl& operator=(const SAX2XMLFilterImpl&); |
---|
1344 | |
---|
1345 | // ----------------------------------------------------------------------- |
---|
1346 | // Private data members |
---|
1347 | // |
---|
1348 | // fParentReader |
---|
1349 | // The object that we are filtering |
---|
1350 | // |
---|
1351 | // fDocHandler |
---|
1352 | // The installed SAX content handler, if any. Null if none. |
---|
1353 | // |
---|
1354 | // fDTDHandler |
---|
1355 | // The installed SAX DTD handler, if any. Null if none. |
---|
1356 | // |
---|
1357 | // fEntityResolver |
---|
1358 | // The installed SAX entity handler, if any. Null if none. |
---|
1359 | // |
---|
1360 | // fErrorHandler |
---|
1361 | // The installed SAX error handler, if any. Null if none. |
---|
1362 | // |
---|
1363 | // ----------------------------------------------------------------------- |
---|
1364 | SAX2XMLReader* fParentReader; |
---|
1365 | ContentHandler* fDocHandler; |
---|
1366 | DTDHandler* fDTDHandler; |
---|
1367 | EntityResolver* fEntityResolver; |
---|
1368 | ErrorHandler* fErrorHandler; |
---|
1369 | }; |
---|
1370 | |
---|
1371 | |
---|
1372 | // --------------------------------------------------------------------------- |
---|
1373 | // SAX2XMLReader: Getter methods |
---|
1374 | // --------------------------------------------------------------------------- |
---|
1375 | inline SAX2XMLReader* SAX2XMLFilterImpl::getParent() const |
---|
1376 | { |
---|
1377 | return fParentReader; |
---|
1378 | } |
---|
1379 | |
---|
1380 | inline ContentHandler* SAX2XMLFilterImpl::getContentHandler() const |
---|
1381 | { |
---|
1382 | return fDocHandler; |
---|
1383 | } |
---|
1384 | |
---|
1385 | inline DTDHandler* SAX2XMLFilterImpl::getDTDHandler() const |
---|
1386 | { |
---|
1387 | return fDTDHandler; |
---|
1388 | } |
---|
1389 | |
---|
1390 | inline EntityResolver* SAX2XMLFilterImpl::getEntityResolver() const |
---|
1391 | { |
---|
1392 | return fEntityResolver; |
---|
1393 | } |
---|
1394 | |
---|
1395 | inline ErrorHandler* SAX2XMLFilterImpl::getErrorHandler() const |
---|
1396 | { |
---|
1397 | return fErrorHandler; |
---|
1398 | } |
---|
1399 | |
---|
1400 | inline LexicalHandler* SAX2XMLFilterImpl::getLexicalHandler() const |
---|
1401 | { |
---|
1402 | return 0; |
---|
1403 | } |
---|
1404 | |
---|
1405 | inline DeclHandler* SAX2XMLFilterImpl::getDeclarationHandler() const |
---|
1406 | { |
---|
1407 | return 0; |
---|
1408 | } |
---|
1409 | |
---|
1410 | inline void SAX2XMLFilterImpl::setContentHandler(ContentHandler* const handler) |
---|
1411 | { |
---|
1412 | fDocHandler = handler; |
---|
1413 | } |
---|
1414 | |
---|
1415 | inline void SAX2XMLFilterImpl::setDTDHandler(DTDHandler* const handler) |
---|
1416 | { |
---|
1417 | fDTDHandler = handler; |
---|
1418 | } |
---|
1419 | |
---|
1420 | inline void SAX2XMLFilterImpl::setErrorHandler(ErrorHandler* const handler) |
---|
1421 | { |
---|
1422 | fErrorHandler = handler; |
---|
1423 | } |
---|
1424 | |
---|
1425 | inline void SAX2XMLFilterImpl::setEntityResolver(EntityResolver* const resolver) |
---|
1426 | { |
---|
1427 | fEntityResolver = resolver; |
---|
1428 | } |
---|
1429 | |
---|
1430 | inline void SAX2XMLFilterImpl::setLexicalHandler(LexicalHandler* const /*handler*/) |
---|
1431 | { |
---|
1432 | } |
---|
1433 | |
---|
1434 | inline void SAX2XMLFilterImpl::setDeclarationHandler(DeclHandler* const /*handler*/) |
---|
1435 | { |
---|
1436 | } |
---|
1437 | |
---|
1438 | inline void SAX2XMLFilterImpl::installAdvDocHandler(XMLDocumentHandler* const /*toInstall*/) |
---|
1439 | { |
---|
1440 | } |
---|
1441 | |
---|
1442 | inline bool SAX2XMLFilterImpl::removeAdvDocHandler(XMLDocumentHandler* const /*toRemove*/) |
---|
1443 | { |
---|
1444 | return false; |
---|
1445 | } |
---|
1446 | |
---|
1447 | XERCES_CPP_NAMESPACE_END |
---|
1448 | |
---|
1449 | #endif |
---|