Coverage Report

Created: 2025-06-13 07:02

/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