/src/xerces-c/src/xercesc/dom/DOMLSParser.hpp
Line | Count | Source (jump to first uncovered 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: DOMLSParser.hpp 1800006 2017-06-27 02:40:16Z scantor $ |
20 | | * |
21 | | */ |
22 | | |
23 | | #if !defined(XERCESC_INCLUDE_GUARD_DOMLSPARSER_HPP) |
24 | | #define XERCESC_INCLUDE_GUARD_DOMLSPARSER_HPP |
25 | | |
26 | | #include <xercesc/dom/DOMConfiguration.hpp> |
27 | | #include <xercesc/dom/DOMLSParserFilter.hpp> |
28 | | #include <xercesc/util/XercesDefs.hpp> |
29 | | #include <xercesc/validators/common/Grammar.hpp> |
30 | | |
31 | | XERCES_CPP_NAMESPACE_BEGIN |
32 | | |
33 | | |
34 | | class DOMErrorHandler; |
35 | | class DOMLSInput; |
36 | | class DOMNode; |
37 | | class DOMDocument; |
38 | | |
39 | | /** |
40 | | * DOMLSParser provides an API for parsing XML documents and building the |
41 | | * corresponding DOM document tree. A DOMLSParser instance is obtained from |
42 | | * the DOMImplementationLS interface by invoking its createLSParser method. |
43 | | * |
44 | | * @since DOM Level 3 |
45 | | * |
46 | | */ |
47 | | class CDOM_EXPORT DOMLSParser |
48 | | { |
49 | | protected : |
50 | | // ----------------------------------------------------------------------- |
51 | | // Hidden constructors |
52 | | // ----------------------------------------------------------------------- |
53 | | /** @name Hidden constructors */ |
54 | | //@{ |
55 | 0 | DOMLSParser() {}; |
56 | | //@} |
57 | | |
58 | | private: |
59 | | // ----------------------------------------------------------------------- |
60 | | // Unimplemented constructors and operators |
61 | | // ----------------------------------------------------------------------- |
62 | | /** @name Unimplemented constructors and operators */ |
63 | | //@{ |
64 | | DOMLSParser(const DOMLSParser &); |
65 | | DOMLSParser & operator = (const DOMLSParser &); |
66 | | //@} |
67 | | |
68 | | public: |
69 | | // ----------------------------------------------------------------------- |
70 | | // All constructors are hidden, just the destructor is available |
71 | | // ----------------------------------------------------------------------- |
72 | | /** @name Destructor */ |
73 | | //@{ |
74 | | /** |
75 | | * Destructor |
76 | | * |
77 | | */ |
78 | 0 | virtual ~DOMLSParser() {}; |
79 | | //@} |
80 | | |
81 | | // ----------------------------------------------------------------------- |
82 | | // Class types |
83 | | // ----------------------------------------------------------------------- |
84 | | /** @name Public Constants */ |
85 | | //@{ |
86 | | /** |
87 | | * A set of possible actions for the parseWithContext method. |
88 | | * |
89 | | * <p><code>ACTION_APPEND_AS_CHILDREN</code>: |
90 | | * Append the result of the parse operation as children of the context node. |
91 | | * For this action to work, the context node must be a <code>DOMElement</code> |
92 | | * or a <code>DOMDocumentFragment</code>. </p> |
93 | | * |
94 | | * <p><code>ACTION_INSERT_AFTER</code>: |
95 | | * Insert the result of the parse operation as the immediately following sibling |
96 | | * of the context node. For this action to work the context node's parent must |
97 | | * be a <code>DOMElement</code> or a <code>DOMDocumentFragment</code>. </p> |
98 | | * |
99 | | * <p><code>ACTION_INSERT_BEFORE</code>: |
100 | | * Insert the result of the parse operation as the immediately preceding sibling |
101 | | * of the context node. For this action to work the context node's parent must |
102 | | * be a <code>DOMElement</code> or a <code>DOMDocumentFragment</code>. </p> |
103 | | * |
104 | | * <p><code>ACTION_REPLACE</code>: |
105 | | * Replace the context node with the result of the parse operation. For this |
106 | | * action to work, the context node must have a parent, and the parent must be |
107 | | * a <code>DOMElement</code> or a <code>DOMDocumentFragment</code>. </p> |
108 | | * |
109 | | * <p><code>ACTION_REPLACE_CHILDREN</code>: |
110 | | * Replace all the children of the context node with the result of the parse |
111 | | * operation. For this action to work, the context node must be a <code>DOMElement</code>, |
112 | | * a <code>DOMDocument</code>, or a <code>DOMDocumentFragment</code>. </p> |
113 | | * |
114 | | * @see parseWithContext(...) |
115 | | * @since DOM Level 3 |
116 | | */ |
117 | | enum ActionType |
118 | | { |
119 | | ACTION_APPEND_AS_CHILDREN = 1, |
120 | | ACTION_REPLACE_CHILDREN = 2, |
121 | | ACTION_INSERT_BEFORE = 3, |
122 | | ACTION_INSERT_AFTER = 4, |
123 | | ACTION_REPLACE = 5 |
124 | | }; |
125 | | //@} |
126 | | |
127 | | // ----------------------------------------------------------------------- |
128 | | // Virtual DOMLSParser interface |
129 | | // ----------------------------------------------------------------------- |
130 | | /** @name Functions introduced in DOM Level 3 */ |
131 | | //@{ |
132 | | |
133 | | // ----------------------------------------------------------------------- |
134 | | // Getter methods |
135 | | // ----------------------------------------------------------------------- |
136 | | |
137 | | /** |
138 | | * Get a pointer to the <code>DOMConfiguration</code> object used when parsing |
139 | | * an input source. |
140 | | * This <code>DOMConfiguration</code> is specific to the parse operation. |
141 | | * No parameter values from this <code>DOMConfiguration</code> object are passed |
142 | | * automatically to the <code>DOMConfiguration</code> object on the |
143 | | * <code>DOMDocument</code> that is created, or used, by the parse operation. |
144 | | * The DOM application is responsible for passing any needed parameter values |
145 | | * from this <code>DOMConfiguration</code> object to the <code>DOMConfiguration</code> |
146 | | * object referenced by the <code>DOMDocument</code> object. |
147 | | * |
148 | | * In addition to the parameters recognized in on the <code>DOMConfiguration</code> |
149 | | * interface defined in [DOM Level 3 Core], the <code>DOMConfiguration</code> objects |
150 | | * for <code>DOMLSParser</code> add or modify the following parameters: |
151 | | * |
152 | | * "charset-overrides-xml-encoding" |
153 | | * true [optional] (default) |
154 | | * If a higher level protocol such as HTTP [IETF RFC 2616] provides an |
155 | | * indication of the character encoding of the input stream being processed, |
156 | | * that will override any encoding specified in the XML declaration or the |
157 | | * Text declaration (see also section 4.3.3, "Character Encoding in Entities", |
158 | | * in [XML 1.0]). Explicitly setting an encoding in the <code>DOMLSInput</code> |
159 | | * overrides any encoding from the protocol. |
160 | | * false [required] |
161 | | * The parser ignores any character set encoding information from higher-level |
162 | | * protocols. |
163 | | * |
164 | | * "disallow-doctype" |
165 | | * true |
166 | | * Throw a fatal "doctype-not-allowed" error if a doctype node is found while |
167 | | * parsing the document. This is useful when dealing with things like SOAP |
168 | | * envelopes where doctype nodes are not allowed. |
169 | | * false (default) |
170 | | * Allow doctype nodes in the document. |
171 | | * |
172 | | * "ignore-unknown-character-denormalizations" |
173 | | * true [required] (default) |
174 | | * If, while verifying full normalization when [XML 1.1] is supported, a |
175 | | * processor encounters characters for which it cannot determine the normalization |
176 | | * properties, then the processor will ignore any possible denormalizations |
177 | | * caused by these characters. |
178 | | * This parameter is ignored for [XML 1.0]. |
179 | | * false [optional] |
180 | | * Report an fatal "unknown-character-denormalization" error if a character |
181 | | * is encountered for which the processor cannot determine the normalization |
182 | | * properties. |
183 | | * |
184 | | * "infoset" |
185 | | * See the definition of DOMConfiguration for a description of this parameter. |
186 | | * Unlike in [DOM Level 3 Core], this parameter will default to true for DOMLSParser. |
187 | | * |
188 | | * "namespaces" |
189 | | * true [required] (default) |
190 | | * Perform the namespace processing as defined in [XML Namespaces] and |
191 | | * [XML Namespaces 1.1]. |
192 | | * false [optional] |
193 | | * Do not perform the namespace processing. |
194 | | * |
195 | | * "resource-resolver" [required] |
196 | | * A pointer to a DOMLSResourceResolver object, or NULL. If the value of this parameter |
197 | | * is not null when an external resource (such as an external XML entity or an XML schema |
198 | | * location) is encountered, the implementation will request that the DOMLSResourceResolver |
199 | | * referenced in this parameter resolves the resource. |
200 | | * |
201 | | * "supported-media-types-only" |
202 | | * true [optional] |
203 | | * Check that the media type of the parsed resource is a supported media type. If |
204 | | * an unsupported media type is encountered, a fatal error of type "unsupported-media-type" |
205 | | * will be raised. The media types defined in [IETF RFC 3023] must always be accepted. |
206 | | * false [required] (default) |
207 | | * Accept any media type. |
208 | | * |
209 | | * "validate" |
210 | | * See the definition of <code>DOMConfiguration</code> for a description of this parameter. |
211 | | * Unlike in [DOM Level 3 Core], the processing of the internal subset is always accomplished, even |
212 | | * if this parameter is set to false. |
213 | | * |
214 | | * "validate-if-schema" |
215 | | * See the definition of <code>DOMConfiguration</code> for a description of this parameter. |
216 | | * Unlike in [DOM Level 3 Core], the processing of the internal subset is always accomplished, even |
217 | | * if this parameter is set to false. |
218 | | * |
219 | | * "well-formed" |
220 | | * See the definition of <code>DOMConfiguration</code> for a description of this parameter. |
221 | | * Unlike in [DOM Level 3 Core], this parameter cannot be set to false. |
222 | | * |
223 | | * In addition to these, Xerces adds these non standard parameters: |
224 | | * |
225 | | * "http://apache.org/xml/properties/entity-resolver" |
226 | | * A pointer to a XMLEntityResolver object, or NULL. If the value of this parameter |
227 | | * is not null when an external resource (such as an external XML entity or an XML schema |
228 | | * location) is encountered, the implementation will request that the XMLEntityResolver |
229 | | * referenced in this parameter resolves the resource. |
230 | | * |
231 | | * "http://apache.org/xml/properties/schema/external-schemaLocation" |
232 | | * A string holding a set of [namespaceUri schemaLocation] entries that will be treated as |
233 | | * the content of the attribute xsi:schemaLocation of the root element |
234 | | * |
235 | | * "http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation" |
236 | | * A string holding the schemaLocation for the empty namespace URI that will be treated as |
237 | | * the content of the attribute xsi:noNamespaceSchemaLocation of the root element |
238 | | * |
239 | | * "http://apache.org/xml/properties/security-manager" |
240 | | * A pointer to a SecurityManager object that will control how many entity references will be |
241 | | * expanded during parsing |
242 | | * |
243 | | * "http://apache.org/xml/properties/scannerName" |
244 | | * A string holding the type of scanner used while parsing. The valid names are: |
245 | | * <ul> |
246 | | * <li>IGXMLScanner: the default one, capable of both XMLSchema and DTD validation</li> |
247 | | * <li>SGXMLScanner: a scanner that can only perform XMLSchema validation</li> |
248 | | * <li>DGXMLScanner: a scanner that can only perform DTD validation</li> |
249 | | * <li>WFXMLScanner: a scanner that cannot perform any type validation, only well-formedness</li> |
250 | | * </ul> |
251 | | * |
252 | | * "http://apache.org/xml/properties/parser-use-DOMDocument-from-Implementation" |
253 | | * A string holding the capabilities of the DOM implementation to be used to create the DOMDocument |
254 | | * resulting from the parse operation. For instance, "LS" or "Core" |
255 | | * |
256 | | * "http://apache.org/xml/features/validation/schema" |
257 | | * true |
258 | | * Enable XMLSchema validation (note that also namespace processing should be enabled) |
259 | | * false (default) |
260 | | * Don't perform XMLSchema validation |
261 | | * |
262 | | * "http://apache.org/xml/features/validation/schema-full-checking" |
263 | | * true |
264 | | * Turn on full XMLSchema checking (e.g. Unique Particle Attribution) |
265 | | * false (default) |
266 | | * Don't perform full XMLSchema checking |
267 | | * |
268 | | * "http://apache.org/xml/features/validating/load-schema" |
269 | | * true (default) |
270 | | * Allow the parser to load schemas that are not in the grammar pool |
271 | | * false |
272 | | * Schemas that are not in the grammar pool are ignored |
273 | | * |
274 | | * "http://apache.org/xml/features/dom/user-adopts-DOMDocument" |
275 | | * true |
276 | | * The DOMDocument objects returned by <code>parse</code> will be owned by the caller |
277 | | * false (default) |
278 | | * The DOMDocument objects returned by <code>parse</code> will be owned by this <code>DOMLSParser</code> |
279 | | * and deleted when released |
280 | | * |
281 | | * "http://apache.org/xml/features/nonvalidating/load-external-dtd" |
282 | | * true (default) |
283 | | * Allow the parser to load external DTDs |
284 | | * false |
285 | | * References to external DTDs will be ignored |
286 | | * |
287 | | * "http://apache.org/xml/features/continue-after-fatal-error" |
288 | | * true |
289 | | * Parsing should try to continue even if a fatal error has been triggered, trying to generate a DOM tree |
290 | | * from a non well-formed XML |
291 | | * false (default) |
292 | | * Violation of XML rules will abort parsing |
293 | | * |
294 | | * "http://apache.org/xml/features/validation-error-as-fatal" |
295 | | * true |
296 | | * Validation errors are treated as fatal errors, and abort parsing (unless "continue-after-fatal-error" |
297 | | * has been specified) |
298 | | * false (default) |
299 | | * Validation errors are normal errors |
300 | | * |
301 | | * "http://apache.org/xml/features/validation/cache-grammarFromParse" |
302 | | * true |
303 | | * XMLSchemas referenced by an XML file are cached in order to be reused by other parse operations |
304 | | * false (default) |
305 | | * XMLSchemas loaded during a parse operation will be discarded before the next one |
306 | | * |
307 | | * "http://apache.org/xml/features/validation/use-cachedGrammarInParse" |
308 | | * true |
309 | | * During this parse operation, reuse the XMLSchemas found in the cache |
310 | | * false (default) |
311 | | * Don't reuse the XMLSchemas found in the cache |
312 | | * |
313 | | * "http://apache.org/xml/features/calculate-src-ofs" |
314 | | * true |
315 | | * During parsing update the position in the source stream |
316 | | * false (default) |
317 | | * Don't waste time computing the position in the source stream |
318 | | * |
319 | | * "http://apache.org/xml/features/standard-uri-conformant" |
320 | | * true |
321 | | * Require that every URL being resolved is made of valid URL characters only |
322 | | * false (default) |
323 | | * Allow invalid URL characters in URL (e.g. spaces) |
324 | | * |
325 | | * "http://apache.org/xml/features/dom-has-psvi-info" |
326 | | * true |
327 | | * Add schema informations to DOMElement and DOMAttr nodes in the output DOM tree |
328 | | * false (default) |
329 | | * Don't store schema informations in the output DOM tree |
330 | | * |
331 | | * "http://apache.org/xml/features/generate-synthetic-annotations" |
332 | | * true |
333 | | * Create annotation objects in the representation of the loaded XMLSchemas |
334 | | * false (default) |
335 | | * Discard annotations found in the loaded XMLSchemas |
336 | | * |
337 | | * "http://apache.org/xml/features/validate-annotations" |
338 | | * true |
339 | | * Check that annotations are valid according to their XMLSchema definition |
340 | | * false (default) |
341 | | * Don't validate annotations |
342 | | * |
343 | | * "http://apache.org/xml/features/validation/identity-constraint-checking" |
344 | | * true (default) |
345 | | * Enforce identity constraints specified in the XMLSchema |
346 | | * false |
347 | | * Don't enforce identity constraints |
348 | | * |
349 | | * "http://apache.org/xml/features/validation/ignoreCachedDTD" |
350 | | * true |
351 | | * Don't reuse DTDs found in the cache, even if use-cachedGrammarInParse is <code>true</code> |
352 | | * false (default) |
353 | | * Reuse DTDs found in the cache, if use-cachedGrammarInParse is <code>true</code> |
354 | | * |
355 | | * "http://apache.org/xml/features/schema/ignore-annotations" |
356 | | * true |
357 | | * Don't process annotations found in an XMLSchema |
358 | | * false (default) |
359 | | * Process the annotations found in an XMLSchema |
360 | | * |
361 | | * "http://apache.org/xml/features/disable-default-entity-resolution" |
362 | | * true |
363 | | * Entities will be resolved only by a resolver installed by the user |
364 | | * false (default) |
365 | | * If the entity resolver has not been installed, or it refuses to resolve the given entity, the |
366 | | * parser will try to locate it himself |
367 | | * |
368 | | * "http://apache.org/xml/features/validation/schema/skip-dtd-validation" |
369 | | * true |
370 | | * If XMLSchema validation is <code>true</code>, DTD validation will not be performed |
371 | | * false (default) |
372 | | * If a DTD is found, it will be used to validate the XML |
373 | | * |
374 | | * @return The pointer to the configuration object. |
375 | | * @since DOM Level 3 |
376 | | */ |
377 | | virtual DOMConfiguration* getDomConfig() = 0; |
378 | | |
379 | | /** |
380 | | * Get a const pointer to the application filter |
381 | | * |
382 | | * This method returns the installed application filter. If no filter |
383 | | * has been installed, then it will be a zero pointer. |
384 | | * |
385 | | * @return A const pointer to the installed application filter |
386 | | * @since DOM Level 3 |
387 | | */ |
388 | | virtual const DOMLSParserFilter* getFilter() const = 0; |
389 | | |
390 | | /** |
391 | | * Return whether the parser is asynchronous |
392 | | * |
393 | | * @return <code>true</code> if the <code>DOMLSParser</code> is asynchronous, |
394 | | * <code>false</code> if it is synchronous |
395 | | * @since DOM Level 3 |
396 | | */ |
397 | | virtual bool getAsync() const = 0; |
398 | | |
399 | | /** |
400 | | * Return whether the parser is busy parsing |
401 | | * |
402 | | * @return <code>true</code> if the <code>DOMLSParser</code> is currently busy |
403 | | * loading a document, otherwise <code>false</code>. |
404 | | * @since DOM Level 3 |
405 | | */ |
406 | | virtual bool getBusy() const = 0; |
407 | | |
408 | | // ----------------------------------------------------------------------- |
409 | | // Setter methods |
410 | | // ----------------------------------------------------------------------- |
411 | | /** |
412 | | * Set the application filter |
413 | | * |
414 | | * When the application provides a filter, the parser will call out to |
415 | | * the filter at the completion of the construction of each <code>DOMElement</code> |
416 | | * node. The filter implementation can choose to remove the element from the |
417 | | * document being constructed or to terminate the parse early. |
418 | | * The filter is invoked after the operations requested by the DOMConfiguration |
419 | | * parameters have been applied. For example, if "validate" is set to true, |
420 | | * the validation is done before invoking the filter. |
421 | | * |
422 | | * <i>Any previously set filter is merely dropped, since the parser |
423 | | * does not own them.</i> |
424 | | * |
425 | | * @param filter A const pointer to the user supplied application |
426 | | * filter. |
427 | | * |
428 | | * @see #getFilter |
429 | | * @since DOM Level 3 |
430 | | */ |
431 | | virtual void setFilter(DOMLSParserFilter* const filter) = 0; |
432 | | |
433 | | // ----------------------------------------------------------------------- |
434 | | // Parsing methods |
435 | | // ----------------------------------------------------------------------- |
436 | | /** |
437 | | * Parse an XML document from a resource identified by a <code>DOMLSInput</code>. |
438 | | * |
439 | | * The parser owns the returned DOMDocument. It will be deleted |
440 | | * when the parser is released. |
441 | | * |
442 | | * @param source The <code>DOMLSInput</code> from which the source of the document |
443 | | * is to be read. |
444 | | * @return If the <code>DOMLSParser</code> is a synchronous <code>DOMLSParser</code> |
445 | | * the newly created and populated <code>DOMDocument</code> is returned. |
446 | | * If the <code>DOMLSParser</code> is asynchronous then <code>NULL</code> |
447 | | * is returned since the document object may not yet be constructed when |
448 | | * this method returns. |
449 | | * @exception DOMException INVALID_STATE_ERR: Raised if the <code>DOMLSParser::busy</code> |
450 | | * attribute is true. |
451 | | * @exception DOMLSException PARSE_ERR: Starting from Xerces-C++ 4.0.0 this exception is |
452 | | * raised if the <code>DOMLSParser</code> was unable |
453 | | * to load the XML document. DOM applications should |
454 | | * attach a <code>DOMErrorHandler</code> using the |
455 | | * parameter "error-handler" if they wish to get details |
456 | | * on the error. |
457 | | * |
458 | | * @see DOMLSInput#DOMLSInput |
459 | | * @see DOMConfiguration |
460 | | * @see resetDocumentPool |
461 | | * @since DOM Level 3 |
462 | | */ |
463 | | virtual DOMDocument* parse(const DOMLSInput* source) = 0; |
464 | | |
465 | | /** |
466 | | * Parse an XML document from a location identified by a URI reference [IETF RFC 2396]. |
467 | | * If the URI contains a fragment identifier (see section 4.1 in [IETF RFC 2396]), |
468 | | * the behavior is not defined by this specification, future versions of this |
469 | | * specification may define the behavior. |
470 | | * |
471 | | * The parser owns the returned DOMDocument. It will be deleted |
472 | | * when the parser is released. |
473 | | * |
474 | | * @param uri The location of the XML document to be read (in Unicode) |
475 | | * @return If the <code>DOMLSParser</code> is a synchronous <code>DOMLSParser</code> |
476 | | * the newly created and populated <code>DOMDocument</code> is returned. |
477 | | * If the <code>DOMLSParser</code> is asynchronous then <code>NULL</code> |
478 | | * is returned since the document object is not yet parsed when this method returns. |
479 | | * @exception DOMException INVALID_STATE_ERR: Raised if the <code>DOMLSParser::busy</code> |
480 | | * attribute is true. |
481 | | * @exception DOMLSException PARSE_ERR: Starting from Xerces-C++ 4.0.0 this exception is |
482 | | * raised if the <code>DOMLSParser</code> was unable |
483 | | * to load the XML document. DOM applications should |
484 | | * attach a <code>DOMErrorHandler</code> using the |
485 | | * parameter "error-handler" if they wish to get details |
486 | | * on the error. |
487 | | * |
488 | | * @see #parse(DOMLSInput,...) |
489 | | * @see resetDocumentPool |
490 | | * @since DOM Level 3 |
491 | | */ |
492 | | virtual DOMDocument* parseURI(const XMLCh* const uri) = 0; |
493 | | |
494 | | /** |
495 | | * Parse an XML document from a location identified by a URI reference [IETF RFC 2396]. |
496 | | * If the URI contains a fragment identifier (see section 4.1 in [IETF RFC 2396]), |
497 | | * the behavior is not defined by this specification, future versions of this |
498 | | * specification may define the behavior. |
499 | | * |
500 | | * The parser owns the returned DOMDocument. It will be deleted |
501 | | * when the parser is released. |
502 | | * |
503 | | * @param uri The location of the XML document to be read (in the local code page) |
504 | | * @return If the <code>DOMLSParser</code> is a synchronous <code>DOMLSParser</code> |
505 | | * the newly created and populated <code>DOMDocument</code> is returned. |
506 | | * If the <code>DOMLSParser</code> is asynchronous then <code>NULL</code> |
507 | | * is returned since the document object is not yet parsed when this method returns. |
508 | | * @exception DOMException INVALID_STATE_ERR: Raised if the <code>DOMLSParser::busy</code> |
509 | | * attribute is true. |
510 | | * @exception DOMLSException PARSE_ERR: Starting from Xerces-C++ 4.0.0 this exception is |
511 | | * raised if the <code>DOMLSParser</code> was unable |
512 | | * to load the XML document. DOM applications should |
513 | | * attach a <code>DOMErrorHandler</code> using the |
514 | | * parameter "error-handler" if they wish to get details |
515 | | * on the error. |
516 | | * |
517 | | * @see #parse(DOMLSInput,...) |
518 | | * @see resetDocumentPool |
519 | | * @since DOM Level 3 |
520 | | */ |
521 | | virtual DOMDocument* parseURI(const char* const uri) = 0; |
522 | | |
523 | | /** |
524 | | * Parse an XML fragment from a resource identified by a <code>DOMLSInput</code> |
525 | | * and insert the content into an existing document at the position specified |
526 | | * with the context and action arguments. When parsing the input stream, the |
527 | | * context node (or its parent, depending on where the result will be inserted) |
528 | | * is used for resolving unbound namespace prefixes. The context node's |
529 | | * <code>ownerDocument</code> node (or the node itself if the node of type |
530 | | * <code>DOCUMENT_NODE</code>) is used to resolve default attributes and entity |
531 | | * references. |
532 | | * As the new data is inserted into the document, at least one mutation event |
533 | | * is fired per new immediate child or sibling of the context node. |
534 | | * If the context node is a <code>DOMDocument</code> node and the action is |
535 | | * <code>ACTION_REPLACE_CHILDREN</code>, then the document that is passed as |
536 | | * the context node will be changed such that its <code>xmlEncoding</code>, |
537 | | * <code>documentURI</code>, <code>xmlVersion</code>, <code>inputEncoding</code>, |
538 | | * <code>xmlStandalone</code>, and all other such attributes are set to what they |
539 | | * would be set to if the input source was parsed using <code>DOMLSParser::parse()</code>. |
540 | | * This method is always synchronous, even if the <code>DOMLSParser</code> is |
541 | | * asynchronous (<code>DOMLSParser::getAsync()</code> returns true). |
542 | | * If an error occurs while parsing, the caller is notified through the <code>ErrorHandler</code> |
543 | | * instance associated with the "error-handler" parameter of the <code>DOMConfiguration</code>. |
544 | | * When calling <code>parseWithContext</code>, the values of the following configuration |
545 | | * parameters will be ignored and their default values will always be used instead: |
546 | | * "validate", |
547 | | * "validate-if-schema" |
548 | | * "element-content-whitespace". |
549 | | * Other parameters will be treated normally, and the parser is expected to call |
550 | | * the <code>DOMLSParserFilter</code> just as if a whole document was parsed. |
551 | | * |
552 | | * @param source The <code>DOMLSInput</code> from which the source document is |
553 | | * to be read. The source document must be an XML fragment, i.e. |
554 | | * anything except a complete XML document (except in the case where |
555 | | * the context node of type <code>DOCUMENT_NODE</code>, and the action is |
556 | | * <code>ACTION_REPLACE_CHILDREN</code>), a <code>DOCTYPE</code> |
557 | | * (internal subset), entity declaration(s), notation declaration(s), |
558 | | * or XML or text declaration(s). |
559 | | * @param contextNode The node that is used as the context for the data that is being |
560 | | * parsed. This node must be a <code>DOMDocument</code> node, a |
561 | | * <code>DOMDocumentFragment</code> node, or a node of a type that |
562 | | * is allowed as a child of an <code>DOMElement</code> node, e.g. |
563 | | * it cannot be an <code>DOMAttribute</code> node. |
564 | | * @param action This parameter describes which action should be taken between the new |
565 | | * set of nodes being inserted and the existing children of the context node. |
566 | | * The set of possible actions is defined in <code>ACTION_TYPES</code> above. |
567 | | * @return Return the node that is the result of the parse operation. If the result is more |
568 | | * than one top-level node, the first one is returned. |
569 | | * |
570 | | * @exception DOMException |
571 | | * HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be inserted before, after, |
572 | | * or as a child of the context node (see also <code>DOMNode::insertBefore</code> |
573 | | * or <code>DOMNode::replaceChild</code> in [DOM Level 3 Core]). |
574 | | * NOT_SUPPORTED_ERR: Raised if the <code>DOMLSParser</code> doesn't support this method, |
575 | | * or if the context node is of type <code>DOMDocument</code> and the DOM |
576 | | * implementation doesn't support the replacement of the <code>DOMDocumentType</code> |
577 | | * child or <code>DOMElement</code> child. |
578 | | * NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a read only node and the content |
579 | | * is being appended to its child list, or if the parent node of |
580 | | * the context node is read only node and the content is being |
581 | | * inserted in its child list. |
582 | | * INVALID_STATE_ERR: Raised if the <code>DOMLSParser::getBusy()</code> returns true. |
583 | | * |
584 | | * @exception DOMLSException PARSE_ERR: Raised if the <code>DOMLSParser</code> was unable to load |
585 | | * the XML fragment. DOM applications should attach a |
586 | | * <code>DOMErrorHandler</code> using the parameter "error-handler" |
587 | | * if they wish to get details on the error. |
588 | | * @since DOM Level 3 |
589 | | */ |
590 | | virtual DOMNode* parseWithContext(const DOMLSInput* source, DOMNode* contextNode, const ActionType action) = 0; |
591 | | |
592 | | /** |
593 | | * Abort the loading of the document that is currently being loaded by the <code>DOMLSParser</code>. |
594 | | * If the <code>DOMLSParser</code> is currently not busy, a call to this method does nothing. |
595 | | * |
596 | | * Note: invoking this method will remove the installed <code>DOMLSParserFilter</code> filter |
597 | | * |
598 | | * @since DOM Level 3 |
599 | | */ |
600 | | virtual void abort() = 0; |
601 | | //@} |
602 | | |
603 | | // ----------------------------------------------------------------------- |
604 | | // Non-standard Extension |
605 | | // ----------------------------------------------------------------------- |
606 | | /** @name Non-standard Extension */ |
607 | | //@{ |
608 | | /** |
609 | | * Called to indicate that this DOMLSParser is no longer in use |
610 | | * and that the implementation may relinquish any resources associated with it. |
611 | | * |
612 | | * Access to a released object will lead to unexpected result. |
613 | | */ |
614 | | virtual void release() = 0; |
615 | | |
616 | | /** Reset the documents vector pool and release all the associated memory |
617 | | * back to the system. |
618 | | * |
619 | | * When parsing a document using a DOM parser, all memory allocated |
620 | | * for a DOM tree is associated to the DOM document. |
621 | | * |
622 | | * If you do multiple parse using the same DOM parser instance, then |
623 | | * multiple DOM documents will be generated and saved in a vector pool. |
624 | | * All these documents (and thus all the allocated memory) |
625 | | * won't be deleted until the parser instance is destroyed. |
626 | | * |
627 | | * If you don't need these DOM documents anymore and don't want to |
628 | | * destroy the DOM parser instance at this moment, then you can call this method |
629 | | * to reset the document vector pool and release all the allocated memory |
630 | | * back to the system. |
631 | | * |
632 | | * It is an error to call this method if you are in the middle of a |
633 | | * parse (e.g. in the mid of a progressive parse). |
634 | | * |
635 | | * @exception IOException An exception from the parser if this function |
636 | | * is called when a parse is in progress. |
637 | | * |
638 | | */ |
639 | | virtual void resetDocumentPool() = 0; |
640 | | |
641 | | /** |
642 | | * Preparse schema grammar (XML Schema, DTD, etc.) via an input source |
643 | | * object. |
644 | | * |
645 | | * This method invokes the preparsing process on a schema grammar XML |
646 | | * file specified by the DOMLSInput parameter. If the 'toCache' flag |
647 | | * is enabled, the parser will cache the grammars for re-use. If a grammar |
648 | | * key is found in the pool, no caching of any grammar will take place. |
649 | | * |
650 | | * @param source A const reference to the DOMLSInput object which |
651 | | * points to the schema grammar file to be preparsed. |
652 | | * @param grammarType The grammar type (Schema or DTD). |
653 | | * @param toCache If <code>true</code>, we cache the preparsed grammar, |
654 | | * otherwise, no chaching. Default is <code>false</code>. |
655 | | * @return The preparsed schema grammar object (SchemaGrammar or |
656 | | * DTDGrammar). That grammar object is owned by the parser. |
657 | | * |
658 | | * @exception SAXException Any SAX exception, possibly |
659 | | * wrapping another exception. |
660 | | * @exception XMLException An exception from the parser or client |
661 | | * handler code. |
662 | | * @exception DOMException A DOM exception as per DOM spec. |
663 | | * |
664 | | * @see DOMLSInput#DOMLSInput |
665 | | */ |
666 | | virtual Grammar* loadGrammar(const DOMLSInput* source, |
667 | | const Grammar::GrammarType grammarType, |
668 | | const bool toCache = false) = 0; |
669 | | |
670 | | /** |
671 | | * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL |
672 | | * |
673 | | * This method invokes the preparsing process on a schema grammar XML |
674 | | * file specified by the file path parameter. If the 'toCache' flag is |
675 | | * enabled, the parser will cache the grammars for re-use. If a grammar |
676 | | * key is found in the pool, no caching of any grammar will take place. |
677 | | * |
678 | | * @param systemId A const XMLCh pointer to the Unicode string which |
679 | | * contains the path to the XML grammar file to be |
680 | | * preparsed. |
681 | | * @param grammarType The grammar type (Schema or DTD). |
682 | | * @param toCache If <code>true</code>, we cache the preparsed grammar, |
683 | | * otherwise, no chaching. Default is <code>false</code>. |
684 | | * @return The preparsed schema grammar object (SchemaGrammar or |
685 | | * DTDGrammar). That grammar object is owned by the parser. |
686 | | * |
687 | | * @exception SAXException Any SAX exception, possibly |
688 | | * wrapping another exception. |
689 | | * @exception XMLException An exception from the parser or client |
690 | | * handler code. |
691 | | * @exception DOMException A DOM exception as per DOM spec. |
692 | | */ |
693 | | virtual Grammar* loadGrammar(const XMLCh* const systemId, |
694 | | const Grammar::GrammarType grammarType, |
695 | | const bool toCache = false) = 0; |
696 | | |
697 | | /** |
698 | | * Preparse schema grammar (XML Schema, DTD, etc.) via a file path or URL |
699 | | * |
700 | | * This method invokes the preparsing process on a schema grammar XML |
701 | | * file specified by the file path parameter. If the 'toCache' flag is |
702 | | * enabled, the parser will cache the grammars for re-use. If a grammar |
703 | | * key is found in the pool, no caching of any grammar will take place. |
704 | | * |
705 | | * @param systemId A const char pointer to a native string which contains |
706 | | * the path to the XML grammar file to be preparsed. |
707 | | * @param grammarType The grammar type (Schema or DTD). |
708 | | * @param toCache If <code>true</code>, we cache the preparsed grammar, |
709 | | * otherwise, no chaching. Default is <code>false</code>. |
710 | | * @return The preparsed schema grammar object (SchemaGrammar or |
711 | | * DTDGrammar). That grammar object is owned by the parser. |
712 | | * |
713 | | * |
714 | | * @exception SAXException Any SAX exception, possibly |
715 | | * wrapping another exception. |
716 | | * @exception XMLException An exception from the parser or client |
717 | | * handler code. |
718 | | * @exception DOMException A DOM exception as per DOM spec. |
719 | | */ |
720 | | virtual Grammar* loadGrammar(const char* const systemId, |
721 | | const Grammar::GrammarType grammarType, |
722 | | const bool toCache = false) = 0; |
723 | | |
724 | | /** |
725 | | * Retrieve the grammar that is associated with the specified namespace key |
726 | | * |
727 | | * @param nameSpaceKey Namespace key |
728 | | * @return Grammar associated with the Namespace key. |
729 | | */ |
730 | | virtual Grammar* getGrammar(const XMLCh* const nameSpaceKey) const = 0; |
731 | | |
732 | | /** |
733 | | * Retrieve the grammar where the root element is declared. |
734 | | * |
735 | | * @return Grammar where root element declared |
736 | | */ |
737 | | virtual Grammar* getRootGrammar() const = 0; |
738 | | |
739 | | /** |
740 | | * Returns the string corresponding to a URI id from the URI string pool. |
741 | | * |
742 | | * @param uriId id of the string in the URI string pool. |
743 | | * @return URI string corresponding to the URI id. |
744 | | */ |
745 | | virtual const XMLCh* getURIText(unsigned int uriId) const = 0; |
746 | | |
747 | | /** |
748 | | * Clear the cached grammar pool |
749 | | */ |
750 | | virtual void resetCachedGrammarPool() = 0; |
751 | | |
752 | | /** |
753 | | * Returns the current src offset within the input source. |
754 | | * |
755 | | * @return offset within the input source |
756 | | */ |
757 | | virtual XMLFilePos getSrcOffset() const = 0; |
758 | | |
759 | | //@} |
760 | | |
761 | | }; |
762 | | |
763 | | |
764 | | XERCES_CPP_NAMESPACE_END |
765 | | |
766 | | #endif |