source: NonGTP/Xerces/xerces/include/xercesc/dom/DOMDocument.hpp @ 358

Revision 358, 38.2 KB checked in by bittner, 19 years ago (diff)

xerces added

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