source: icXML/icXML-devel/src/xercesc/dom/DOMDocument.hpp @ 2722

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

Original Xerces files with import mods for icxercesc

File size: 35.4 KB
Line 
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/*
19 * $Id: DOMDocument.hpp 932887 2010-04-11 13:04:59Z borisk $
20*/
21
22#if !defined(XERCESC_INCLUDE_GUARD_DOMDOCUMENT_HPP)
23#define XERCESC_INCLUDE_GUARD_DOMDOCUMENT_HPP
24
25#include <xercesc/util/XercesDefs.hpp>
26#include <xercesc/dom/DOMNode.hpp>
27#include <xercesc/dom/DOMDocumentRange.hpp>
28#include <xercesc/dom/DOMDocumentTraversal.hpp>
29#include <xercesc/dom/DOMXPathEvaluator.hpp>
30
31XERCES_CPP_NAMESPACE_BEGIN
32
33class DOMConfiguration;
34class DOMDocumentType;
35class DOMElement;
36class DOMDocumentFragment;
37class DOMComment;
38class DOMCDATASection;
39class DOMProcessingInstruction;
40class DOMAttr;
41class DOMEntity;
42class DOMEntityReference;
43class DOMImplementation;
44class DOMNodeFilter;
45class DOMNodeList;
46class DOMNotation;
47class DOMText;
48class DOMNode;
49
50
51/**
52 * The <code>DOMDocument</code> interface represents the entire XML
53 * document. Conceptually, it is the root of the document tree, and provides
54 * the primary access to the document's data.
55 * <p>Since elements, text nodes, comments, processing instructions, etc.
56 * cannot exist outside the context of a <code>DOMDocument</code>, the
57 * <code>DOMDocument</code> interface also contains the factory methods needed
58 * to create these objects. The <code>DOMNode</code> objects created have a
59 * <code>ownerDocument</code> attribute which associates them with the
60 * <code>DOMDocument</code> within whose context they were created.
61 * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
62 */
63
64class CDOM_EXPORT DOMDocument: public DOMDocumentRange,
65 public DOMXPathEvaluator,
66 public DOMDocumentTraversal,
67 public DOMNode {
68
69
70protected:
71    // -----------------------------------------------------------------------
72    //  Hidden constructors
73    // -----------------------------------------------------------------------
74    /** @name Hidden constructors */
75    //@{
76    DOMDocument() {};
77    //@}
78
79private:
80    // -----------------------------------------------------------------------
81    // Unimplemented constructors and operators
82    // -----------------------------------------------------------------------
83    /** @name Unimplemented constructors and operators */
84    //@{
85    DOMDocument(const DOMDocument &);
86    DOMDocument & operator = (const DOMDocument &);
87    //@}
88
89public:
90    // -----------------------------------------------------------------------
91    //  All constructors are hidden, just the destructor is available
92    // -----------------------------------------------------------------------
93    /** @name Destructor */
94    //@{
95    /**
96     * Destructor
97     *
98     */
99    virtual ~DOMDocument() {};
100    //@}
101
102    // -----------------------------------------------------------------------
103    // Virtual DOMDocument interface
104    // -----------------------------------------------------------------------
105    /** @name Functions introduced in DOM Level 1 */
106    //@{
107    /**
108     * Creates an element of the type specified. Note that the instance
109     * returned implements the <code>DOMElement</code> interface, so attributes
110     * can be specified directly on the returned object.
111     * <br>In addition, if there are known attributes with default values,
112     * <code>DOMAttr</code> nodes representing them are automatically created
113     * and attached to the element.
114     * <br>To create an element with a qualified name and namespace URI, use
115     * the <code>createElementNS</code> method.
116     * @param tagName The name of the element type to instantiate. For XML,
117     *   this is case-sensitive.
118     * @return A new <code>DOMElement</code> object with the
119     *   <code>nodeName</code> attribute set to <code>tagName</code>, and
120     *   <code>localName</code>, <code>prefix</code>, and
121     *   <code>namespaceURI</code> set to <code>null</code>.
122     * @exception DOMException
123     *   INVALID_CHARACTER_ERR: Raised if the specified name contains an
124     *   illegal character.
125     * @since DOM Level 1
126     */
127    virtual DOMElement     *createElement(const XMLCh *tagName) = 0;
128
129    /**
130     * Creates an empty <code>DOMDocumentFragment</code> object.
131     * @return A new <code>DOMDocumentFragment</code>.
132     * @since DOM Level 1
133     */
134    virtual DOMDocumentFragment   *createDocumentFragment() = 0;
135
136    /**
137     * Creates a <code>DOMText</code> node given the specified string.
138     * @param data The data for the node.
139     * @return The new <code>DOMText</code> object.
140     * @since DOM Level 1
141     */
142    virtual DOMText         *createTextNode(const XMLCh *data) = 0;
143
144    /**
145     * Creates a <code>DOMComment</code> node given the specified string.
146     * @param data The data for the node.
147     * @return The new <code>DOMComment</code> object.
148     * @since DOM Level 1
149     */
150    virtual DOMComment      *createComment(const XMLCh *data) = 0;
151
152    /**
153     * Creates a <code>DOMCDATASection</code> node whose value is the specified
154     * string.
155     * @param data The data for the <code>DOMCDATASection</code> contents.
156     * @return The new <code>DOMCDATASection</code> object.
157     * @since DOM Level 1
158     */
159    virtual DOMCDATASection   *createCDATASection(const XMLCh *data) = 0;
160
161    /**
162     * Creates a <code>DOMProcessingInstruction</code> node given the specified
163     * name and data strings.
164     * @param target The target part of the processing instruction.
165     * @param data The data for the node.
166     * @return The new <code>DOMProcessingInstruction</code> object.
167     * @exception DOMException
168     *   INVALID_CHARACTER_ERR: Raised if the specified target contains an
169     *   illegal character.
170     * @since DOM Level 1
171     */
172    virtual DOMProcessingInstruction *createProcessingInstruction(const XMLCh *target,
173        const XMLCh *data) = 0;
174
175
176    /**
177     * Creates an <code>DOMAttr</code> of the given name. Note that the
178     * <code>DOMAttr</code> instance can then be set on an <code>DOMElement</code>
179     * using the <code>setAttributeNode</code> method.
180     * <br>To create an attribute with a qualified name and namespace URI, use
181     * the <code>createAttributeNS</code> method.
182     * @param name The name of the attribute.
183     * @return A new <code>DOMAttr</code> object with the <code>nodeName</code>
184     *   attribute set to <code>name</code>, and <code>localName</code>,
185     *   <code>prefix</code>, and <code>namespaceURI</code> set to
186     *   <code>null</code>. The value of the attribute is the empty string.
187     * @exception DOMException
188     *   INVALID_CHARACTER_ERR: Raised if the specified name contains an
189     *   illegal character.
190     * @since DOM Level 1
191     */
192    virtual DOMAttr     *createAttribute(const XMLCh *name) = 0;
193
194
195    /**
196     * Creates an <code>DOMEntityReference</code> object. In addition, if the
197     * referenced entity is known, the child list of the
198     * <code>DOMEntityReference</code> node is made the same as that of the
199     * corresponding <code>DOMEntity</code> node.If any descendant of the
200     * <code>DOMEntity</code> node has an unbound namespace prefix, the
201     * corresponding descendant of the created <code>DOMEntityReference</code>
202     * node is also unbound; (its <code>namespaceURI</code> is
203     * <code>null</code>). The DOM Level 2 does not support any mechanism to
204     * resolve namespace prefixes.
205     * @param name The name of the entity to reference.
206     * @return The new <code>DOMEntityReference</code> object.
207     * @exception DOMException
208     *   INVALID_CHARACTER_ERR: Raised if the specified name contains an
209     *   illegal character.
210     * @since DOM Level 1
211     */
212    virtual DOMEntityReference    *createEntityReference(const XMLCh *name) = 0;
213
214    /**
215     * The Document Type Declaration (see <code>DOMDocumentType</code>)
216     * associated with this document. For XML
217     * documents without a document type declaration this returns
218     * <code>null</code>. The DOM Level 2 does not support editing the
219     * Document Type Declaration. <code>docType</code> cannot be altered in
220     * any way, including through the use of methods inherited from the
221     * <code>DOMNode</code> interface, such as <code>insertNode</code> or
222     * <code>removeNode</code>.
223     * @since DOM Level 1
224     */
225    virtual DOMDocumentType       *getDoctype() const = 0;
226
227    /**
228     * The <code>DOMImplementation</code> object that handles this document. A
229     * DOM application may use objects from multiple implementations.
230     * @since DOM Level 1
231     */
232    virtual DOMImplementation  *getImplementation() const = 0;
233
234    /**
235     * This is a convenience attribute that allows direct access to the child
236     * node that is the root element of the document.
237     * @since DOM Level 1
238     */
239    virtual DOMElement     *getDocumentElement() const = 0;
240
241    /**
242     * Returns a <code>DOMNodeList</code> of all the <code>DOMElement(s)</code> with a
243     * given tag name in the order in which they are encountered in a
244     * preorder traversal of the <code>DOMDocument</code> tree.
245     *
246     * The returned node list is "live", in that changes
247     * to the document tree made after a nodelist was initially
248     * returned will be immediately reflected in the node list.
249     * @param tagname The name of the tag to match on. The special value "*"
250     *   matches all tags.
251     * @return A new <code>DOMNodeList</code> object containing all the matched
252     *   <code>DOMElement(s)</code>.
253     * @since DOM Level 1
254     */
255    virtual DOMNodeList      *getElementsByTagName(const XMLCh *tagname) const = 0;
256
257    //@}
258
259    /** @name Functions introduced in DOM Level 2. */
260    //@{
261
262    /**
263     * Imports a node from another document to this document. The returned
264     * node has no parent; (<code>parentNode</code> is <code>null</code>).
265     * The source node is not altered or removed from the original document;
266     * this method creates a new copy of the source node.
267     * <br>For all nodes, importing a node creates a node object owned by the
268     * importing document, with attribute values identical to the source
269     * node's <code>nodeName</code> and <code>nodeType</code>, plus the
270     * attributes related to namespaces (<code>prefix</code>,
271     * <code>localName</code>, and <code>namespaceURI</code>). As in the
272     * <code>cloneNode</code> operation on a <code>DOMNode</code>, the source
273     * node is not altered.
274     * <br>Additional information is copied as appropriate to the
275     * <code>nodeType</code>, attempting to mirror the behavior expected if
276     * a fragment of XML source was copied from one document to
277     * another, recognizing that the two documents may have different DTDs
278     * in the XML case. The following list describes the specifics for each
279     * type of node.
280     * <dl>
281     * <dt>ATTRIBUTE_NODE</dt>
282     * <dd>The <code>ownerElement</code> attribute
283     * is set to <code>null</code> and the <code>specified</code> flag is
284     * set to <code>true</code> on the generated <code>DOMAttr</code>. The
285     * descendants of the source <code>DOMAttr</code> are recursively imported
286     * and the resulting nodes reassembled to form the corresponding subtree.
287     * Note that the <code>deep</code> parameter has no effect on
288     * <code>DOMAttr</code> nodes; they always carry their children with them
289     * when imported.</dd>
290     * <dt>DOCUMENT_FRAGMENT_NODE</dt>
291     * <dd>If the <code>deep</code> option
292     * was set to <code>true</code>, the descendants of the source element
293     * are recursively imported and the resulting nodes reassembled to form
294     * the corresponding subtree. Otherwise, this simply generates an empty
295     * <code>DOMDocumentFragment</code>.</dd>
296     * <dt>DOCUMENT_NODE</dt>
297     * <dd><code>DOMDocument</code>
298     * nodes cannot be imported.</dd>
299     * <dt>DOCUMENT_TYPE_NODE</dt>
300     * <dd><code>DOMDocumentType</code>
301     * nodes cannot be imported.</dd>
302     * <dt>ELEMENT_NODE</dt>
303     * <dd>Specified attribute nodes of the
304     * source element are imported, and the generated <code>DOMAttr</code>
305     * nodes are attached to the generated <code>DOMElement</code>. Default
306     * attributes are not copied, though if the document being imported into
307     * defines default attributes for this element name, those are assigned.
308     * If the <code>importNode</code> <code>deep</code> parameter was set to
309     * <code>true</code>, the descendants of the source element are
310     * recursively imported and the resulting nodes reassembled to form the
311     * corresponding subtree.</dd>
312     * <dt>ENTITY_NODE</dt>
313     * <dd><code>DOMEntity</code> nodes can be
314     * imported, however in the current release of the DOM the
315     * <code>DOMDocumentType</code> is readonly. Ability to add these imported
316     * nodes to a <code>DOMDocumentType</code> will be considered for addition
317     * to a future release of the DOM.On import, the <code>publicId</code>,
318     * <code>systemId</code>, and <code>notationName</code> attributes are
319     * copied. If a <code>deep</code> import is requested, the descendants
320     * of the the source <code>DOMEntity</code> are recursively imported and
321     * the resulting nodes reassembled to form the corresponding subtree.</dd>
322     * <dt>
323     * ENTITY_REFERENCE_NODE</dt>
324     * <dd>Only the <code>DOMEntityReference</code> itself is
325     * copied, even if a <code>deep</code> import is requested, since the
326     * source and destination documents might have defined the entity
327     * differently. If the document being imported into provides a
328     * definition for this entity name, its value is assigned.</dd>
329     * <dt>NOTATION_NODE</dt>
330     * <dd>
331     * <code>DOMNotation</code> nodes can be imported, however in the current
332     * release of the DOM the <code>DOMDocumentType</code> is readonly. Ability
333     * to add these imported nodes to a <code>DOMDocumentType</code> will be
334     * considered for addition to a future release of the DOM.On import, the
335     * <code>publicId</code> and <code>systemId</code> attributes are copied.
336     * Note that the <code>deep</code> parameter has no effect on
337     * <code>DOMNotation</code> nodes since they never have any children.</dd>
338     * <dt>
339     * PROCESSING_INSTRUCTION_NODE</dt>
340     * <dd>The imported node copies its
341     * <code>target</code> and <code>data</code> values from those of the
342     * source node.</dd>
343     * <dt>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE</dt>
344     * <dd>These three
345     * types of nodes inheriting from <code>DOMCharacterData</code> copy their
346     * <code>data</code> and <code>length</code> attributes from those of
347     * the source node.</dd>
348     * </dl>
349     * @param importedNode The node to import.
350     * @param deep If <code>true</code>, recursively import the subtree under
351     *   the specified node; if <code>false</code>, import only the node
352     *   itself, as explained above. This has no effect on <code>DOMAttr</code>
353     *   , <code>DOMEntityReference</code>, and <code>DOMNotation</code> nodes.
354     * @return The imported node that belongs to this <code>DOMDocument</code>.
355     * @exception DOMException
356     *   NOT_SUPPORTED_ERR: Raised if the type of node being imported is not
357     *   supported.
358     * @since DOM Level 2
359     */
360    virtual DOMNode        *importNode(const DOMNode *importedNode, bool deep) = 0;
361
362    /**
363     * Creates an element of the given qualified name and namespace URI.
364     * @param namespaceURI The namespace URI of the element to create.
365     * @param qualifiedName The qualified name of the element type to
366     *   instantiate.
367     * @return A new <code>DOMElement</code> object with the following
368     *   attributes:
369     * <table border='1'>
370     * <tr>
371     * <td valign='top' rowspan='1' colspan='1'><code>Attribute</code></td>
372     * <td valign='top' rowspan='1' colspan='1'>
373     *   <code>Value</code></td>
374     * </tr>
375     * <tr>
376     * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.nodeName</code></td>
377     * <td valign='top' rowspan='1' colspan='1'>
378     *   <code>qualifiedName</code></td>
379     * </tr>
380     * <tr>
381     * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.namespaceURI</code></td>
382     * <td valign='top' rowspan='1' colspan='1'>
383     *   <code>namespaceURI</code></td>
384     * </tr>
385     * <tr>
386     * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.prefix</code></td>
387     * <td valign='top' rowspan='1' colspan='1'>prefix, extracted
388     *   from <code>qualifiedName</code>, or <code>null</code> if there is
389     *   no prefix</td>
390     * </tr>
391     * <tr>
392     * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.localName</code></td>
393     * <td valign='top' rowspan='1' colspan='1'>local name, extracted from
394     *   <code>qualifiedName</code></td>
395     * </tr>
396     * <tr>
397     * <td valign='top' rowspan='1' colspan='1'><code>DOMElement.tagName</code></td>
398     * <td valign='top' rowspan='1' colspan='1'>
399     *   <code>qualifiedName</code></td>
400     * </tr>
401     * </table>
402     * @exception DOMException
403     *   INVALID_CHARACTER_ERR: Raised if the specified qualified name
404     *   contains an illegal character, per the XML 1.0 specification .
405     *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
406     *   malformed per the Namespaces in XML specification, if the
407     *   <code>qualifiedName</code> has a prefix and the
408     *   <code>namespaceURI</code> is <code>null</code>, or if the
409     *   <code>qualifiedName</code> has a prefix that is "xml" and the
410     *   <code>namespaceURI</code> is different from "
411     *   http://www.w3.org/XML/1998/namespace" .
412     *   <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
413     *   support the <code>"XML"</code> feature, since namespaces were
414     *   defined by XML.
415     * @since DOM Level 2
416     */
417    virtual DOMElement         *createElementNS(const XMLCh *namespaceURI,
418                                                      const XMLCh *qualifiedName) = 0;
419
420    /**
421     * Creates an attribute of the given qualified name and namespace URI.
422     * @param namespaceURI The namespace URI of the attribute to create.
423     * @param qualifiedName The qualified name of the attribute to
424     *   instantiate.
425     * @return A new <code>DOMAttr</code> object with the following attributes:
426     * <table border='1'>
427     * <tr>
428     * <td valign='top' rowspan='1' colspan='1'><code>Attribute</code></td>
429     * <td valign='top' rowspan='1' colspan='1'>
430     *   <code>Value</code></td>
431     * </tr>
432     * <tr>
433     * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.nodeName</code></td>
434     * <td valign='top' rowspan='1' colspan='1'>qualifiedName</td>
435     * </tr>
436     * <tr>
437     * <td valign='top' rowspan='1' colspan='1'>
438     *   <code>DOMNode.namespaceURI</code></td>
439     * <td valign='top' rowspan='1' colspan='1'><code>namespaceURI</code></td>
440     * </tr>
441     * <tr>
442     * <td valign='top' rowspan='1' colspan='1'>
443     *   <code>DOMNode.prefix</code></td>
444     * <td valign='top' rowspan='1' colspan='1'>prefix, extracted from
445     *   <code>qualifiedName</code>, or <code>null</code> if there is no
446     *   prefix</td>
447     * </tr>
448     * <tr>
449     * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.localName</code></td>
450     * <td valign='top' rowspan='1' colspan='1'>local name, extracted from
451     *   <code>qualifiedName</code></td>
452     * </tr>
453     * <tr>
454     * <td valign='top' rowspan='1' colspan='1'><code>DOMAttr.name</code></td>
455     * <td valign='top' rowspan='1' colspan='1'>
456     *   <code>qualifiedName</code></td>
457     * </tr>
458     * <tr>
459     * <td valign='top' rowspan='1' colspan='1'><code>DOMNode.nodeValue</code></td>
460     * <td valign='top' rowspan='1' colspan='1'>the empty
461     *   string</td>
462     * </tr>
463     * </table>
464     * @exception DOMException
465     *   INVALID_CHARACTER_ERR: Raised if the specified qualified name
466     *   contains an illegal character, per the XML 1.0 specification .
467     *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
468     *   malformed per the Namespaces in XML specification, if the
469     *   <code>qualifiedName</code> has a prefix and the
470     *   <code>namespaceURI</code> is <code>null</code>, if the
471     *   <code>qualifiedName</code> has a prefix that is "xml" and the
472     *   <code>namespaceURI</code> is different from "
473     *   http://www.w3.org/XML/1998/namespace", or if the
474     *   <code>qualifiedName</code>, or its prefix, is "xmlns" and the
475     *   <code>namespaceURI</code> is different from "
476     *   http://www.w3.org/2000/xmlns/".
477     *   <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
478     *   support the <code>"XML"</code> feature, since namespaces were
479     *   defined by XML.
480     * @since DOM Level 2
481     */
482    virtual DOMAttr        *createAttributeNS(const XMLCh *namespaceURI,
483                                                    const XMLCh *qualifiedName) = 0;
484
485    /**
486     * Returns a <code>DOMNodeList</code> of all the <code>DOMElement(s)</code> with a
487     * given local name and namespace URI in the order in which they are
488     * encountered in a preorder traversal of the <code>DOMDocument</code> tree.
489     * @param namespaceURI The namespace URI of the elements to match on. The
490     *   special value "*" matches all namespaces.
491     * @param localName The local name of the elements to match on. The
492     *   special value "*" matches all local names.
493     * @return A new <code>DOMNodeList</code> object containing all the matched
494     *   <code>DOMElement(s)</code>.
495     * @since DOM Level 2
496     */
497    virtual DOMNodeList        *getElementsByTagNameNS(const XMLCh *namespaceURI,
498                                                             const XMLCh *localName) const = 0;
499
500    /**
501     * Returns the <code>DOMElement</code> whose <code>ID</code> is given by
502     * <code>elementId</code>. If no such element exists, returns
503     * <code>null</code>. Behavior is not defined if more than one element
504     * has this <code>ID</code>. The DOM implementation must have
505     * information that says which attributes are of type ID. Attributes
506     * with the name "ID" are not of type ID unless so defined.
507     * Implementations that do not know whether attributes are of type ID or
508     * not are expected to return <code>null</code>.
509     * @param elementId The unique <code>id</code> value for an element.
510     * @return The matching element.
511     * @since DOM Level 2
512     */
513    virtual  DOMElement        * getElementById(const XMLCh *elementId) const = 0;
514    //@}
515
516    /** @name Functions introduced in DOM Level 3. */
517    //@{
518
519    /**
520     * An attribute specifying the encoding used for this document at the time of the parsing.
521     * This is <code>null</code> when it is not known, such as when the DOMDocument was created in memory.
522     *
523     * @since DOM Level 3
524     */
525    virtual const XMLCh*           getInputEncoding() const = 0;
526
527    /**
528     * An attribute specifying, as part of the XML declaration, the encoding of this document.
529     * This is <code>null</code> when unspecified or when it is not known, such as when the
530     * DOMDocument was created in memory.
531     *
532     * @since DOM Level 3
533     */
534    virtual const XMLCh*           getXmlEncoding() const = 0;
535
536    /**
537     * An attribute specifying, as part of the XML declaration, whether this document is standalone.
538     * This is <code>false</code> when unspecified.
539     *
540     * @since DOM Level 3
541     */
542    virtual bool                   getXmlStandalone() const = 0;
543
544    /**
545     * An attribute specifying, as part of the XML declaration, whether this
546     * document is standalone.
547     * <br> This attribute represents the property [standalone] defined in .
548     *
549     * @since DOM Level 3
550     */
551    virtual void                   setXmlStandalone(bool standalone) = 0;
552
553    /**
554     * An attribute specifying, as part of the XML declaration, the version
555     * number of this document. This is <code>null</code> when unspecified.
556     * <br> This attribute represents the property [version] defined in .
557     *
558     * @since DOM Level 3
559     */
560    virtual const XMLCh*           getXmlVersion() const = 0;
561
562    /**
563     * An attribute specifying, as part of the XML declaration, the version
564     * number of this document. This is <code>null</code> when unspecified.
565     * <br> This attribute represents the property [version] defined in .
566     *
567     * @since DOM Level 3
568     */
569    virtual void                   setXmlVersion(const XMLCh* version) = 0;
570
571    /**
572     * The location of the document or <code>null</code> if undefined.
573     * <br>Beware that when the <code>DOMDocument</code> supports the feature
574     * "HTML" , the href attribute of the HTML BASE element takes precedence
575     * over this attribute.
576     *
577     * @since DOM Level 3
578     */
579    virtual const XMLCh*           getDocumentURI() const = 0;
580    /**
581     * The location of the document or <code>null</code> if undefined.
582     * <br>Beware that when the <code>DOMDocument</code> supports the feature
583     * "HTML" , the href attribute of the HTML BASE element takes precedence
584     * over this attribute.
585     *
586     * @since DOM Level 3
587     */
588    virtual void                   setDocumentURI(const XMLCh* documentURI) = 0;
589
590    /**
591     * An attribute specifying whether errors checking is enforced or not.
592     * When set to <code>false</code>, the implementation is free to not
593     * test every possible error case normally defined on DOM operations,
594     * and not raise any <code>DOMException</code>. In case of error, the
595     * behavior is undefined. This attribute is <code>true</code> by
596     * defaults.
597     *
598     * @since DOM Level 3
599     */
600    virtual bool                   getStrictErrorChecking() const = 0;
601    /**
602     * An attribute specifying whether errors checking is enforced or not.
603     * When set to <code>false</code>, the implementation is free to not
604     * test every possible error case normally defined on DOM operations,
605     * and not raise any <code>DOMException</code>. In case of error, the
606     * behavior is undefined. This attribute is <code>true</code> by
607     * defaults.
608     *
609     * @since DOM Level 3
610     */
611    virtual void                   setStrictErrorChecking(bool strictErrorChecking) = 0;
612
613    /**
614     * Rename an existing node. When possible this simply changes the name of
615     * the given node, otherwise this creates a new node with the specified
616     * name and replaces the existing node with the new node as described
617     * below. This only applies to nodes of type <code>ELEMENT_NODE</code>
618     * and <code>ATTRIBUTE_NODE</code>.
619     * <br>When a new node is created, the following operations are performed:
620     * the new node is created, any registered event listener is registered
621     * on the new node, any user data attached to the old node is removed
622     * from that node, the old node is removed from its parent if it has
623     * one, the children are moved to the new node, if the renamed node is
624     * an <code>DOMElement</code> its attributes are moved to the new node, the
625     * new node is inserted at the position the old node used to have in its
626     * parent's child nodes list if it has one, the user data that was
627     * attached to the old node is attach to the new node, the user data
628     * event <code>NODE_RENAMED</code> is fired.
629     * <br>When the node being renamed is an <code>DOMAttr</code> that is
630     * attached to an <code>DOMElement</code>, the node is first removed from
631     * the <code>DOMElement</code> attributes map. Then, once renamed, either
632     * by modifying the existing node or creating a new one as described
633     * above, it is put back.
634     *
635     * @param n The node to rename.
636     * @param namespaceURI The new namespaceURI.
637     * @param qualifiedName The new qualified name.
638     * @return The renamed node. This is either the specified node or the new
639     *   node that was created to replace the specified node.
640     * @exception DOMException
641     *   NOT_SUPPORTED_ERR: Raised when the type of the specified node is
642     *   neither <code>ELEMENT_NODE</code> nor <code>ATTRIBUTE_NODE</code>.
643     *   <br>WRONG_DOCUMENT_ERR: Raised when the specified node was created
644     *   from a different document than this document.
645     *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
646     *   malformed per the Namespaces in XML specification, if the
647     *   <code>qualifiedName</code> has a prefix and the
648     *   <code>namespaceURI</code> is <code>null</code>, or if the
649     *   <code>qualifiedName</code> has a prefix that is "xml" and the
650     *   <code>namespaceURI</code> is different from "
651     *   http://www.w3.org/XML/1998/namespace" . Also raised, when the node
652     *   being renamed is an attribute, if the <code>qualifiedName</code>,
653     *   or its prefix, is "xmlns" and the <code>namespaceURI</code> is
654     *   different from "http://www.w3.org/2000/xmlns/".
655     * @since DOM Level 3
656     */
657    virtual DOMNode* renameNode(DOMNode* n, const XMLCh* namespaceURI, const XMLCh* qualifiedName) = 0;
658
659
660    /**
661     * Changes the <code>ownerDocument</code> of a node, its children, as well
662     * as the attached attribute nodes if there are any. If the node has a
663     * parent it is first removed from its parent child list. This
664     * effectively allows moving a subtree from one document to another. The
665     * following list describes the specifics for each type of node.
666     *
667     * <dl>
668     * <dt>
669     * ATTRIBUTE_NODE</dt>
670     * <dd>The <code>ownerElement</code> attribute is set to
671     * <code>null</code> and the <code>specified</code> flag is set to
672     * <code>true</code> on the adopted <code>DOMAttr</code>. The descendants
673     * of the source <code>DOMAttr</code> are recursively adopted.</dd>
674     * <dt>
675     * DOCUMENT_FRAGMENT_NODE</dt>
676     * <dd>The descendants of the source node are
677     * recursively adopted.</dd>
678     * <dt>DOCUMENT_NODE</dt>
679     * <dd><code>DOMDocument</code> nodes cannot
680     * be adopted.</dd>
681     * <dt>DOCUMENT_TYPE_NODE</dt>
682     * <dd><code>DOMDocumentType</code> nodes cannot
683     * be adopted.</dd>
684     * <dt>ELEMENT_NODE</dt>
685     * <dd>Specified attribute nodes of the source
686     * element are adopted, and the generated <code>DOMAttr</code> nodes.
687     * Default attributes are discarded, though if the document being
688     * adopted into defines default attributes for this element name, those
689     * are assigned. The descendants of the source element are recursively
690     * adopted.</dd>
691     * <dt>ENTITY_NODE</dt>
692     * <dd><code>DOMEntity</code> nodes cannot be adopted.</dd>
693     * <dt>
694     * ENTITY_REFERENCE_NODE</dt>
695     * <dd>Only the <code>DOMEntityReference</code> node
696     * itself is adopted, the descendants are discarded, since the source
697     * and destination documents might have defined the entity differently.
698     * If the document being imported into provides a definition for this
699     * entity name, its value is assigned.</dd>
700     * <dt>NOTATION_NODE</dt>
701     * <dd><code>DOMNotation</code>
702     * nodes cannot be adopted.</dd>
703     * <dt>PROCESSING_INSTRUCTION_NODE, TEXT_NODE,
704     * CDATA_SECTION_NODE, COMMENT_NODE</dt>
705     * <dd>These nodes can all be adopted. No
706     * specifics.</dd>
707     * </dl>
708     * @param source The node to move into this document.
709     * @return The adopted node, or <code>null</code> if this operation
710     *   fails, such as when the source node comes from a different
711     *   implementation.
712     * @exception DOMException
713     *   NOT_SUPPORTED_ERR: Raised if the source node is of type
714     *   <code>DOCUMENT</code>, <code>DOCUMENT_TYPE</code>.
715     *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised when the source node is
716     *   readonly.
717     * @since DOM Level 3
718     */
719    virtual DOMNode*               adoptNode(DOMNode* source) = 0;
720
721    /**
722     * This method acts as if the document was going through a save and load
723     * cycle, putting the document in a "normal" form. The actual result
724     * depends on the features being set. See <code>DOMConfiguration</code> for
725     * details.
726     *
727     * <br>Noticeably this method normalizes <code>DOMText</code> nodes, makes
728     * the document "namespace wellformed", according to the algorithm
729     * described below in pseudo code, by adding missing namespace
730     * declaration attributes and adding or changing namespace prefixes,
731     * updates the replacement tree of <code>DOMEntityReference</code> nodes,
732     * normalizes attribute values, etc.
733     * <br>Mutation events, when supported, are generated to reflect the
734     * changes occurring on the document.
735     * Note that this is a partial implementation. Not all the required features are implemented.
736     * Currently <code>DOMAttr</code> and <code>DOMText</code> nodes are normalized.
737     * Features to remove <code>DOMComment</code> and <code>DOMCDATASection</code> work.
738     * @since DOM Level 3
739     *
740     */
741    virtual void                   normalizeDocument() = 0;
742
743
744    /**
745     * The configuration used when DOMDocument::normalizeDocument is invoked.
746     *
747     * @return The <code>DOMConfiguration</code> from this <code>DOMDocument</code>
748     *
749     * @since DOM Level 3
750     */
751    virtual DOMConfiguration*      getDOMConfig() const = 0;
752
753    //@}
754
755    // -----------------------------------------------------------------------
756    // Non-standard extension
757    // -----------------------------------------------------------------------
758    /** @name Non-standard extension */
759    //@{
760    /**
761     * Non-standard extension
762     *
763     * Create a new entity.
764     * @param name The name of the entity to instantiate
765     *
766     */
767    virtual DOMEntity     *createEntity(const XMLCh *name) = 0;
768
769    /**
770     * Non-standard extension
771     *
772     * Create a DOMDocumentType node.
773     * @return A <code>DOMDocumentType</code> that references the newly
774     *  created DOMDocumentType node.
775     *
776     */
777    virtual DOMDocumentType *createDocumentType(const XMLCh *name) = 0;
778
779    /***
780     * Provide default implementation to maintain source code compatibility
781     ***/
782    virtual DOMDocumentType* createDocumentType(const XMLCh *qName,
783                                                const XMLCh*,  //publicId,
784                                                const XMLCh*   //systemId
785                                               )
786    {
787        return createDocumentType(qName);
788    }
789
790    /**
791     * Non-standard extension.
792     *
793     * Create a Notation.
794     * @param name The name of the notation to instantiate
795     * @return A <code>DOMNotation</code> that references the newly
796     *  created DOMNotation node.
797     */
798    virtual DOMNotation *createNotation(const XMLCh *name) = 0;
799
800    /**
801     * Non-standard extension.
802     *
803     * Creates an element of the given qualified name and
804     * namespace URI, and also stores line/column number info.
805     * Used by internally XSDXercesDOMParser during schema traversal.
806     *
807     * @see createElementNS(const XMLCh *namespaceURI, const XMLCh *qualifiedName)
808     */
809    virtual DOMElement *createElementNS(const XMLCh *namespaceURI,
810                                        const XMLCh *qualifiedName,
811                                        const XMLFileLoc lineNum,
812                                        const XMLFileLoc columnNum) = 0;
813    //@}
814
815};
816
817XERCES_CPP_NAMESPACE_END
818
819#endif
Note: See TracBrowser for help on using the repository browser.