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

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

xerces added
Line 
1#ifndef DOMNode_HEADER_GUARD_
2#define DOMNode_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: DOMNode.hpp,v 1.17 2004/09/08 13:55:39 peiyongz Exp $
22 */
23
24#include <xercesc/util/XercesDefs.hpp>
25
26XERCES_CPP_NAMESPACE_BEGIN
27
28
29class DOMDocument;
30class DOMNamedNodeMap;
31class DOMNodeList;
32class DOMUserDataHandler;
33
34/**
35 * The <code>DOMNode</code> interface is the primary datatype for the entire
36 * Document Object Model. It represents a single node in the document tree.
37 * While all objects implementing the <code>DOMNode</code> interface expose
38 * methods for dealing with children, not all objects implementing the
39 * <code>DOMNode</code> interface may have children. For example,
40 * <code>DOMText</code> nodes may not have children, and adding children to
41 * such nodes results in a <code>DOMException</code> being raised.
42 * <p>The attributes <code>nodeName</code>, <code>nodeValue</code> and
43 * <code>attributes</code> are included as a mechanism to get at node
44 * information without casting down to the specific derived interface. In
45 * cases where there is no obvious mapping of these attributes for a
46 * specific <code>nodeType</code> (e.g., <code>nodeValue</code> for an
47 * <code>DOMElement</code> or <code>attributes</code> for a <code>DOMComment</code>
48 * ), this returns <code>null</code>. Note that the specialized interfaces
49 * may contain additional and more convenient mechanisms to get and set the
50 * relevant information.
51 * <p>The values of <code>nodeName</code>,
52 * <code>nodeValue</code>, and <code>attributes</code> vary according to the
53 * node type as follows:
54 * <table border='1'>
55 * <tr>
56 * <td>Interface</td>
57 * <td>nodeName</td>
58 * <td>nodeValue</td>
59 * <td>attributes</td>
60 * </tr>
61 * <tr>
62 * <td valign='top' rowspan='1' colspan='1'>DOMAttr</td>
63 * <td valign='top' rowspan='1' colspan='1'>name of
64 * attribute</td>
65 * <td valign='top' rowspan='1' colspan='1'>value of attribute</td>
66 * <td valign='top' rowspan='1' colspan='1'>null</td>
67 * </tr>
68 * <tr>
69 * <td valign='top' rowspan='1' colspan='1'>DOMCDATASection</td>
70 * <td valign='top' rowspan='1' colspan='1'><code>"#cdata-section"</code></td>
71 * <td valign='top' rowspan='1' colspan='1'>
72 * content of the CDATA Section</td>
73 * <td valign='top' rowspan='1' colspan='1'>null</td>
74 * </tr>
75 * <tr>
76 * <td valign='top' rowspan='1' colspan='1'>DOMComment</td>
77 * <td valign='top' rowspan='1' colspan='1'><code>"#comment"</code></td>
78 * <td valign='top' rowspan='1' colspan='1'>content of
79 * the comment</td>
80 * <td valign='top' rowspan='1' colspan='1'>null</td>
81 * </tr>
82 * <tr>
83 * <td valign='top' rowspan='1' colspan='1'>DOMDocument</td>
84 * <td valign='top' rowspan='1' colspan='1'><code>"#document"</code></td>
85 * <td valign='top' rowspan='1' colspan='1'>null</td>
86 * <td valign='top' rowspan='1' colspan='1'>null</td>
87 * </tr>
88 * <tr>
89 * <td valign='top' rowspan='1' colspan='1'>DOMDocumentFragment</td>
90 * <td valign='top' rowspan='1' colspan='1'>
91 * <code>"#document-fragment"</code></td>
92 * <td valign='top' rowspan='1' colspan='1'>null</td>
93 * <td valign='top' rowspan='1' colspan='1'>null</td>
94 * </tr>
95 * <tr>
96 * <td valign='top' rowspan='1' colspan='1'>DOMDocumentType</td>
97 * <td valign='top' rowspan='1' colspan='1'>document type name</td>
98 * <td valign='top' rowspan='1' colspan='1'>
99 * null</td>
100 * <td valign='top' rowspan='1' colspan='1'>null</td>
101 * </tr>
102 * <tr>
103 * <td valign='top' rowspan='1' colspan='1'>DOMElement</td>
104 * <td valign='top' rowspan='1' colspan='1'>tag name</td>
105 * <td valign='top' rowspan='1' colspan='1'>null</td>
106 * <td valign='top' rowspan='1' colspan='1'>NamedNodeMap</td>
107 * </tr>
108 * <tr>
109 * <td valign='top' rowspan='1' colspan='1'>DOMEntity</td>
110 * <td valign='top' rowspan='1' colspan='1'>entity name</td>
111 * <td valign='top' rowspan='1' colspan='1'>null</td>
112 * <td valign='top' rowspan='1' colspan='1'>null</td>
113 * </tr>
114 * <tr>
115 * <td valign='top' rowspan='1' colspan='1'>DOMEntityReference</td>
116 * <td valign='top' rowspan='1' colspan='1'>name of entity referenced</td>
117 * <td valign='top' rowspan='1' colspan='1'>null</td>
118 * <td valign='top' rowspan='1' colspan='1'>null</td>
119 * </tr>
120 * <tr>
121 * <td valign='top' rowspan='1' colspan='1'>DOMNotation</td>
122 * <td valign='top' rowspan='1' colspan='1'>notation name</td>
123 * <td valign='top' rowspan='1' colspan='1'>null</td>
124 * <td valign='top' rowspan='1' colspan='1'>
125 * null</td>
126 * </tr>
127 * <tr>
128 * <td valign='top' rowspan='1' colspan='1'>DOMProcessingInstruction</td>
129 * <td valign='top' rowspan='1' colspan='1'>target</td>
130 * <td valign='top' rowspan='1' colspan='1'>entire content excluding the target</td>
131 * <td valign='top' rowspan='1' colspan='1'>null</td>
132 * </tr>
133 * <tr>
134 * <td valign='top' rowspan='1' colspan='1'>DOMText</td>
135 * <td valign='top' rowspan='1' colspan='1'>
136 * <code>"#text"</code></td>
137 * <td valign='top' rowspan='1' colspan='1'>content of the text node</td>
138 * <td valign='top' rowspan='1' colspan='1'>null</td>
139 * </tr>
140 * </table>
141 * <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>.
142 *
143 * @since DOM Level 1
144 */
145class  CDOM_EXPORT DOMNode {
146protected:
147    // -----------------------------------------------------------------------
148    //  Hidden constructors
149    // -----------------------------------------------------------------------
150    /** @name Hidden constructors */
151    //@{   
152    DOMNode() {};
153    //@}
154
155private:   
156    // -----------------------------------------------------------------------
157    // Unimplemented constructors and operators
158    // -----------------------------------------------------------------------
159    /** @name Unimplemented constructors and operators */
160    //@{
161    DOMNode(const DOMNode &);
162    DOMNode & operator = (const DOMNode &);
163    //@}
164
165public:
166    // -----------------------------------------------------------------------
167    //  All constructors are hidden, just the destructor is available
168    // -----------------------------------------------------------------------
169    /** @name Destructor */
170    //@{
171    /**
172     * Destructor
173     *
174     */
175    virtual ~DOMNode() {};
176    //@}
177
178    // -----------------------------------------------------------------------
179    //  Class Types
180    // -----------------------------------------------------------------------
181    /** @name Public Contants */
182    //@{
183    /**
184     * NodeType
185     *
186     * @since DOM Level 1
187     */
188    enum NodeType {
189        ELEMENT_NODE                = 1,
190        ATTRIBUTE_NODE              = 2,
191        TEXT_NODE                   = 3,
192        CDATA_SECTION_NODE          = 4,
193        ENTITY_REFERENCE_NODE       = 5,
194        ENTITY_NODE                 = 6,
195        PROCESSING_INSTRUCTION_NODE = 7,
196        COMMENT_NODE                = 8,
197        DOCUMENT_NODE               = 9,
198        DOCUMENT_TYPE_NODE          = 10,
199        DOCUMENT_FRAGMENT_NODE      = 11,
200        NOTATION_NODE               = 12
201    };
202
203    /**
204     * TreePosition:
205     *
206     * <p><b>"Experimental - subject to change"</b></p>
207     *
208     * <p><code>TREE_POSITION_PRECEDING:</code>
209     * The node precedes the reference node.</p>
210     * <p><code>TREE_POSITION_FOLLOWING:</code>
211     * The node follows the reference node.</p>
212     * <p><code>TREE_POSITION_ANCESTOR:</code>
213     * The node is an ancestor of the reference node.</p>
214     * <p><code>TREE_POSITION_DESCENDANT:</code>
215     * The node is a descendant of the reference node.</p>
216     * <p><code>TREE_POSITION_EQUIVALENT:</code>
217     * The two nodes have an equivalent position. This is the case of two
218     * attributes that have the same <code>ownerElement</code>, and two
219     * nodes that are the same.</p>
220     * <p><code>TREE_POSITION_SAME_NODE:</code>
221     * The two nodes are the same. Two nodes that are the same have an
222     * equivalent position, though the reverse may not be true.</p>
223     * <p><code>TREE_POSITION_DISCONNECTED:</code>
224     * The two nodes are disconnected, they do not have any common ancestor.
225     * This is the case of two nodes that are not in the same document.</p>
226     *
227     * @since DOM Level 3
228     */
229    enum DOMTreePosition {
230        TREE_POSITION_PRECEDING   = 0x01,
231        TREE_POSITION_FOLLOWING   = 0x02,
232        TREE_POSITION_ANCESTOR    = 0x04,
233        TREE_POSITION_DESCENDANT  = 0x08,
234        TREE_POSITION_EQUIVALENT  = 0x10,
235        TREE_POSITION_SAME_NODE   = 0x20,
236        TREE_POSITION_DISCONNECTED = 0x00
237    };
238    //@}
239
240    // -----------------------------------------------------------------------
241    //  Virtual DOMNode interface
242    // -----------------------------------------------------------------------
243    /** @name Functions introduced in DOM Level 1 */
244    //@{
245    // -----------------------------------------------------------------------
246    //  Getter methods
247    // -----------------------------------------------------------------------
248    /**
249     * The name of this node, depending on its type; see the table above.
250     * @since DOM Level 1
251     */
252    virtual const XMLCh *   getNodeName() const = 0;
253
254    /**
255     * Gets the value of this node, depending on its type.
256     *
257     * @exception DOMException
258     *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
259     * @since DOM Level 1
260     */
261    virtual const XMLCh *       getNodeValue() const = 0;
262
263    /**
264     * An enum value representing the type of the underlying object.
265     * @since DOM Level 1
266     */
267    virtual short           getNodeType() const = 0;
268
269    /**
270     * Gets the parent of this node.
271     *
272     * All nodes, except <code>DOMDocument</code>,
273     * <code>DOMDocumentFragment</code>, and <code>DOMAttr</code> may have a parent.
274     * However, if a node has just been created and not yet added to the tree,
275     * or if it has been removed from the tree, a <code>null</code> DOMNode
276     * is returned.
277     * @since DOM Level 1
278     */
279    virtual DOMNode        *getParentNode() const = 0;
280
281    /**
282     * Gets a <code>DOMNodeList</code> that contains all children of this node.
283     *
284     * If there
285     * are no children, this is a <code>DOMNodeList</code> containing no nodes.
286     * The content of the returned <code>DOMNodeList</code> is "live" in the sense
287     * that, for instance, changes to the children of the node object that
288     * it was created from are immediately reflected in the nodes returned by
289     * the <code>DOMNodeList</code> accessors; it is not a static snapshot of the
290     * content of the node. This is true for every <code>DOMNodeList</code>,
291     * including the ones returned by the <code>getElementsByTagName</code>
292     * method.
293     * @since DOM Level 1
294     */
295    virtual DOMNodeList    *getChildNodes() const = 0;
296    /**
297     * Gets the first child of this node.
298     *
299     * If there is no such node, this returns <code>null</code>.
300     * @since DOM Level 1
301     */
302    virtual DOMNode        *getFirstChild() const = 0;
303
304    /**
305     * Gets the last child of this node.
306     *
307     * If there is no such node, this returns <code>null</code>.
308     * @since DOM Level 1
309     */
310    virtual DOMNode        *getLastChild() const = 0;
311
312    /**
313     * Gets the node immediately preceding this node.
314     *
315     * If there is no such node, this returns <code>null</code>.
316     * @since DOM Level 1
317     */
318    virtual DOMNode        *getPreviousSibling() const = 0;
319
320    /**
321     * Gets the node immediately following this node.
322     *
323     * If there is no such node, this returns <code>null</code>.
324     * @since DOM Level 1
325     */
326    virtual DOMNode        *getNextSibling() const = 0;
327
328    /**
329     * Gets a <code>DOMNamedNodeMap</code> containing the attributes of this node (if it
330     * is an <code>DOMElement</code>) or <code>null</code> otherwise.
331     * @since DOM Level 1
332     */
333    virtual DOMNamedNodeMap  *getAttributes() const = 0;
334
335    /**
336     * Gets the <code>DOMDocument</code> object associated with this node.
337     *
338     * This is also
339     * the <code>DOMDocument</code> object used to create new nodes. When this
340     * node is a <code>DOMDocument</code> or a <code>DOMDocumentType</code>
341     * which is not used with any <code>DOMDocument</code> yet, this is
342     * <code>null</code>.
343     *
344     * @since DOM Level 1
345     */
346    virtual DOMDocument      *getOwnerDocument() const = 0;
347
348    // -----------------------------------------------------------------------
349    //  Node methods
350    // -----------------------------------------------------------------------
351    /**
352     * Returns a duplicate of this node.
353     *
354     * This function serves as a generic copy constructor for nodes.
355     *
356     * The duplicate node has no parent (
357     * <code>parentNode</code> returns <code>null</code>.).
358     * <br>Cloning an <code>DOMElement</code> copies all attributes and their
359     * values, including those generated by the  XML processor to represent
360     * defaulted attributes, but this method does not copy any text it contains
361     * unless it is a deep clone, since the text is contained in a child
362     * <code>DOMText</code> node. Cloning any other type of node simply returns a
363     * copy of this node.
364     * @param deep If <code>true</code>, recursively clone the subtree under the
365     *   specified node; if <code>false</code>, clone only the node itself (and
366     *   its attributes, if it is an <code>DOMElement</code>).
367     * @return The duplicate node.
368     * @since DOM Level 1
369     */
370    virtual DOMNode        * cloneNode(bool deep) const = 0;
371
372    /**
373     * Inserts the node <code>newChild</code> before the existing child node
374     * <code>refChild</code>.
375     *
376     * If <code>refChild</code> is <code>null</code>,
377     * insert <code>newChild</code> at the end of the list of children.
378     * <br>If <code>newChild</code> is a <code>DOMDocumentFragment</code> object,
379     * all of its children are inserted, in the same order, before
380     * <code>refChild</code>. If the <code>newChild</code> is already in the
381     * tree, it is first removed.  Note that a <code>DOMNode</code> that
382     * has never been assigned to refer to an actual node is == null.
383     * @param newChild The node to insert.
384     * @param refChild The reference node, i.e., the node before which the new
385     *   node must be inserted.
386     * @return The node being inserted.
387     * @exception DOMException
388     *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
389     *   allow children of the type of the <code>newChild</code> node, or if
390     *   the node to insert is one of this node's ancestors.
391     *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created
392     *   from a different document than the one that created this node.
393     *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the node being
394     *   inserted is readonly.
395     *   <br>NOT_FOUND_ERR: Raised if <code>refChild</code> is not a child of
396     *   this node.
397     * @since DOM Level 1
398     */
399    virtual DOMNode       *insertBefore(DOMNode *newChild,
400                                          DOMNode *refChild) = 0;
401
402
403    /**
404     * Replaces the child node <code>oldChild</code> with <code>newChild</code>
405     * in the list of children, and returns the <code>oldChild</code> node.
406     *
407     * If <CODE>newChild</CODE> is a <CODE>DOMDocumentFragment</CODE> object,
408     * <CODE>oldChild</CODE> is replaced by all of the <CODE>DOMDocumentFragment</CODE>
409     * children, which are inserted in the same order.
410     *
411     * If the <code>newChild</code> is already in the tree, it is first removed.
412     * @param newChild The new node to put in the child list.
413     * @param oldChild The node being replaced in the list.
414     * @return The node replaced.
415     * @exception DOMException
416     *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
417     *   allow children of the type of the <code>newChild</code> node, or it
418     *   the node to put in is one of this node's ancestors.
419     *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created
420     *   from a different document than the one that created this node.
421     *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the new node is readonly.
422     *   <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of
423     *   this node.
424     * @since DOM Level 1
425     */
426    virtual DOMNode  *replaceChild(DOMNode *newChild,
427                                     DOMNode *oldChild) = 0;
428    /**
429     * Removes the child node indicated by <code>oldChild</code> from the list
430     * of children, and returns it.
431     *
432     * @param oldChild The node being removed.
433     * @return The node removed.
434     * @exception DOMException
435     *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
436     *   <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of
437     *   this node.
438     * @since DOM Level 1
439     */
440    virtual DOMNode        *removeChild(DOMNode *oldChild) = 0;
441
442    /**
443     * Adds the node <code>newChild</code> to the end of the list of children of
444     * this node.
445     *
446     * If the <code>newChild</code> is already in the tree, it is
447     * first removed.
448     * @param newChild The node to add.If it is a  <code>DOMDocumentFragment</code>
449     *   object, the entire contents of the document fragment are moved into
450     *   the child list of this node
451     * @return The node added.
452     * @exception DOMException
453     *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
454     *   allow children of the type of the <code>newChild</code> node, or if
455     *   the node to append is one of this node's ancestors.
456     *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created
457     *   from a different document than the one that created this node.
458     *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the node being
459     *   appended is readonly.
460     * @since DOM Level 1
461     */
462    virtual DOMNode        *appendChild(DOMNode *newChild) = 0;
463
464    // -----------------------------------------------------------------------
465    //  Query methods
466    // -----------------------------------------------------------------------
467    /**
468     *  This is a convenience method to allow easy determination of whether a
469     * node has any children.
470     *
471     * @return  <code>true</code> if the node has any children,
472     *   <code>false</code> if the node has no children.
473     * @since DOM Level 1
474     */
475    virtual bool             hasChildNodes() const = 0;
476
477    // -----------------------------------------------------------------------
478    //  Setter methods
479    // -----------------------------------------------------------------------
480    /**
481     * Sets the value of the node.
482     *
483     * Any node which can have a nodeValue (@see getNodeValue) will
484     * also accept requests to set it to a string. The exact response to
485     * this varies from node to node -- Attribute, for example, stores
486     * its values in its children and has to replace them with a new Text
487     * holding the replacement value.
488     *
489     * For most types of Node, value is null and attempting to set it
490     * will throw DOMException(NO_MODIFICATION_ALLOWED_ERR). This will
491     * also be thrown if the node is read-only.
492     * @since DOM Level 1
493     */
494    virtual void              setNodeValue(const XMLCh  *nodeValue) = 0;
495    //@}
496
497    /** @name Functions introduced in DOM Level 2. */
498    //@{
499    /**
500     * Puts all <CODE>DOMText</CODE>
501     * nodes in the full depth of the sub-tree underneath this <CODE>DOMNode</CODE>,
502     * including attribute nodes, into a "normal" form where only markup (e.g.,
503     * tags, comments, processing instructions, CDATA sections, and entity
504     * references) separates <CODE>DOMText</CODE>
505     * nodes, i.e., there are neither adjacent <CODE>DOMText</CODE>
506     * nodes nor empty <CODE>DOMText</CODE>
507     * nodes. This can be used to ensure that the DOM view of a document is the
508     * same as if it were saved and re-loaded, and is useful when operations
509     * (such as XPointer lookups) that depend on a particular document tree
510     * structure are to be used.
511     * <P><B>Note:</B> In cases where the document contains <CODE>DOMCDATASections</CODE>,
512     * the normalize operation alone may not be sufficient, since XPointers do
513     * not differentiate between <CODE>DOMText</CODE>
514     * nodes and <CODE>DOMCDATASection</CODE>
515     * nodes.</P>
516     *
517     * @since DOM Level 2
518     */
519    virtual void              normalize() = 0;
520
521    /**
522     * Tests whether the DOM implementation implements a specific
523     * feature and that feature is supported by this node.
524     *
525     * @param feature The string of the feature to test. This is the same
526     * name as what can be passed to the method <code>hasFeature</code> on
527     * <code>DOMImplementation</code>.
528     * @param version This is the version number of the feature to test. In
529     * Level 2, version 1, this is the string "2.0". If the version is not
530     * specified, supporting any version of the feature will cause the
531     * method to return <code>true</code>.
532     * @return Returns <code>true</code> if the specified feature is supported
533     * on this node, <code>false</code> otherwise.
534     * @since DOM Level 2
535     */
536    virtual bool              isSupported(const XMLCh *feature,
537                                               const XMLCh *version) const = 0;
538
539    /**
540     * Get the <em>namespace URI</em> of
541     * this node, or <code>null</code> if it is unspecified.
542     * <p>
543     * This is not a computed value that is the result of a namespace lookup
544     * based on an examination of the namespace declarations in scope. It is
545     * merely the namespace URI given at creation time.
546     * <p>
547     * For nodes of any type other than <CODE>ELEMENT_NODE</CODE> and
548     * <CODE>ATTRIBUTE_NODE</CODE> and nodes created with a DOM Level 1 method,
549     * such as <CODE>createElement</CODE> from the <CODE>DOMDocument</CODE>
550     * interface, this is always <CODE>null</CODE>.
551     *
552     * @since DOM Level 2
553     */
554    virtual const XMLCh *         getNamespaceURI() const = 0;
555
556    /**
557     * Get the <em>namespace prefix</em>
558     * of this node, or <code>null</code> if it is unspecified.
559     *
560     * @since DOM Level 2
561     */
562    virtual const XMLCh *          getPrefix() const = 0;
563
564    /**
565     * Returns the local part of the <em>qualified name</em> of this node.
566     * <p>
567     * For nodes created with a DOM Level 1 method, such as
568     * <code>createElement</code> from the <code>DOMDocument</code> interface,
569     * it is null.
570     *
571     * @since DOM Level 2
572     */
573    virtual const XMLCh *          getLocalName() const = 0;
574
575    /**
576     * Set the <em>namespace prefix</em> of this node.
577     * <p>
578     * Note that setting this attribute, when permitted, changes
579     * the <CODE>nodeName</CODE> attribute, which holds the <EM>qualified
580     * name</EM>, as well as the <CODE>tagName</CODE> and <CODE>name</CODE>
581     * attributes of the <CODE>DOMElement</CODE> and <CODE>DOMAttr</CODE>
582     * interfaces, when applicable.
583     * <p>
584     * Note also that changing the prefix of an
585     * attribute, that is known to have a default value, does not make a new
586     * attribute with the default value and the original prefix appear, since the
587     * <CODE>namespaceURI</CODE> and <CODE>localName</CODE> do not change.
588     *
589     *
590     * @param prefix The prefix of this node.
591     * @exception DOMException
592     *   INVALID_CHARACTER_ERR: Raised if the specified prefix contains
593     *                          an illegal character.
594     * <br>
595     *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
596     * <br>
597     *   NAMESPACE_ERR: Raised if the specified <CODE>prefix</CODE> is
598     *      malformed, if the <CODE>namespaceURI</CODE> of this node is
599     *      <CODE>null</CODE>, if the specified prefix is "xml" and the
600     *      <CODE>namespaceURI</CODE> of this node is different from
601     *      "http://www.w3.org/XML/1998/namespace", if this node is an attribute
602     *      and the specified prefix is "xmlns" and the
603     *      <CODE>namespaceURI</CODE> of this node is different from
604     *      "http://www.w3.org/2000/xmlns/", or if this node is an attribute and
605     *      the <CODE>qualifiedName</CODE> of this node is "xmlns".
606     * @since DOM Level 2
607     */
608    virtual void              setPrefix(const XMLCh * prefix) = 0;
609
610    /**
611     *  Returns whether this node (if it is an element) has any attributes.
612     * @return <code>true</code> if this node has any attributes,
613     *   <code>false</code> otherwise.
614     * @since DOM Level 2
615     */
616    virtual bool              hasAttributes() const = 0;
617    //@}
618
619    /** @name Functions introduced in DOM Level 3. */
620    //@{
621    /**
622     * Returns whether this node is the same node as the given one.
623     * <br>This method provides a way to determine whether two
624     * <code>DOMNode</code> references returned by the implementation reference
625     * the same object. When two <code>DOMNode</code> references are references
626     * to the same object, even if through a proxy, the references may be
627     * used completely interchangeably, such that all attributes have the
628     * same values and calling the same DOM method on either reference
629     * always has exactly the same effect.
630     *
631     * <p><b>"Experimental - subject to change"</b></p>
632     *
633     * @param other The node to test against.
634     * @return Returns <code>true</code> if the nodes are the same,
635     *   <code>false</code> otherwise.
636     * @since DOM Level 3
637     */
638    virtual bool              isSameNode(const DOMNode* other) const = 0;
639
640    /**
641     * Tests whether two nodes are equal.
642     * <br>This method tests for equality of nodes, not sameness (i.e.,
643     * whether the two nodes are pointers to the same object) which can be
644     * tested with <code>DOMNode::isSameNode</code>. All nodes that are the same
645     * will also be equal, though the reverse may not be true.
646     * <br>Two nodes are equal if and only if the following conditions are
647     * satisfied: The two nodes are of the same type.The following string
648     * attributes are equal: <code>nodeName</code>, <code>localName</code>,
649     * <code>namespaceURI</code>, <code>prefix</code>, <code>nodeValue</code>
650     * , <code>baseURI</code>. This is: they are both <code>null</code>, or
651     * they have the same length and are character for character identical.
652     * The <code>attributes</code> <code>DOMNamedNodeMaps</code> are equal.
653     * This is: they are both <code>null</code>, or they have the same
654     * length and for each node that exists in one map there is a node that
655     * exists in the other map and is equal, although not necessarily at the
656     * same index.The <code>childNodes</code> <code>DOMNodeLists</code> are
657     * equal. This is: they are both <code>null</code>, or they have the
658     * same length and contain equal nodes at the same index. This is true
659     * for <code>DOMAttr</code> nodes as for any other type of node. Note that
660     * normalization can affect equality; to avoid this, nodes should be
661     * normalized before being compared.
662     * <br>For two <code>DOMDocumentType</code> nodes to be equal, the following
663     * conditions must also be satisfied: The following string attributes
664     * are equal: <code>publicId</code>, <code>systemId</code>,
665     * <code>internalSubset</code>.The <code>entities</code>
666     * <code>DOMNamedNodeMaps</code> are equal.The <code>notations</code>
667     * <code>DOMNamedNodeMaps</code> are equal.
668     * <br>On the other hand, the following do not affect equality: the
669     * <code>ownerDocument</code> attribute, the <code>specified</code>
670     * attribute for <code>DOMAttr</code> nodes, the
671     * <code>isWhitespaceInElementContent</code> attribute for
672     * <code>DOMText</code> nodes, as well as any user data or event listeners
673     * registered on the nodes.
674     *
675     * <p><b>"Experimental - subject to change"</b></p>
676     *
677     * @param arg The node to compare equality with.
678     * @return If the nodes, and possibly subtrees are equal,
679     *   <code>true</code> otherwise <code>false</code>.
680     * @since DOM Level 3
681     */
682    virtual bool              isEqualNode(const DOMNode* arg) const = 0;
683
684
685    /**
686     * Associate an object to a key on this node. The object can later be
687     * retrieved from this node by calling <code>getUserData</code> with the
688     * same key.
689     *
690     * Deletion of the user data remains the responsibility of the
691     * application program; it will not be automatically deleted when
692     * the nodes themselves are reclaimed.
693     *
694     * Both the parameter <code>data</code> and the returned object are
695     * void pointer, it is applications' responsibility to keep track of
696     * their original type.  Casting them to the wrong type may result
697     * unexpected behavior.
698     *
699     * <p><b>"Experimental - subject to change"</b></p>
700     *
701     * @param key The key to associate the object to.
702     * @param data The object to associate to the given key, or
703     *   <code>null</code> to remove any existing association to that key.
704     * @param handler The handler to associate to that key, or
705     *   <code>null</code>.
706     * @return Returns the void* object previously associated to
707     *   the given key on this node, or <code>null</code> if there was none.
708     * @see getUserData
709     *
710     * @since DOM Level 3
711     */
712    virtual void*             setUserData(const XMLCh* key,
713                                          void* data,
714                                          DOMUserDataHandler* handler) = 0;
715
716    /**
717     * Retrieves the object associated to a key on a this node. The object
718     * must first have been set to this node by calling
719     * <code>setUserData</code> with the same key.
720     *
721     * <p><b>"Experimental - subject to change"</b></p>
722     *
723     * @param key The key the object is associated to.
724     * @return Returns the <code>void*</code> associated to the given key
725     *   on this node, or <code>null</code> if there was none.
726     * @see setUserData
727     * @since DOM Level 3
728     */
729    virtual void*             getUserData(const XMLCh* key) const = 0;
730
731
732    /**
733     * The absolute base URI of this node or <code>null</code> if undefined.
734     * This value is computed according to . However, when the
735     * <code>DOMDocument</code> supports the feature "HTML" , the base URI is
736     * computed using first the value of the href attribute of the HTML BASE
737     * element if any, and the value of the <code>documentURI</code>
738     * attribute from the <code>DOMDocument</code> interface otherwise.
739     *
740     * <p><b>"Experimental - subject to change"</b></p>
741     *
742     * <br> When the node is an <code>DOMElement</code>, a <code>DOMDocument</code>
743     * or a a <code>DOMProcessingInstruction</code>, this attribute represents
744     * the properties [base URI] defined in . When the node is a
745     * <code>DOMNotation</code>, an <code>DOMEntity</code>, or an
746     * <code>DOMEntityReference</code>, this attribute represents the
747     * properties [declaration base URI].
748     * @since DOM Level 3
749     */
750    virtual const XMLCh*           getBaseURI() const = 0;
751
752    /**
753     * Compares a node with this node with regard to their position in the
754     * tree and according to the document order. This order can be extended
755     * by module that define additional types of nodes.
756     *
757     * <p><b>"Experimental - subject to change"</b></p>
758     *
759     * @param other The node to compare against this node.
760     * @return Returns how the given node is positioned relatively to this
761     *   node.
762     * @since DOM Level 3
763     */
764    virtual short                  compareTreePosition(const DOMNode* other) const = 0;
765
766    /**
767     * This attribute returns the text content of this node and its
768     * descendants. When it is defined to be null, setting it has no effect.
769     * When set, any possible children this node may have are removed and
770     * replaced by a single <code>DOMText</code> node containing the string
771     * this attribute is set to. On getting, no serialization is performed,
772     * the returned string does not contain any markup. No whitespace
773     * normalization is performed, the returned string does not contain the
774     * element content whitespaces . Similarly, on setting, no parsing is
775     * performed either, the input string is taken as pure textual content.
776     *
777     * <p><b>"Experimental - subject to change"</b></p>
778     *
779     * <br>The string returned is made of the text content of this node
780     * depending on its type, as defined below:
781     * <table border='1'>
782     * <tr>
783     * <th>Node type</th>
784     * <th>Content</th>
785     * </tr>
786     * <tr>
787     * <td valign='top' rowspan='1' colspan='1'>
788     * ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE,
789     * DOCUMENT_FRAGMENT_NODE</td>
790     * <td valign='top' rowspan='1' colspan='1'>concatenation of the <code>textContent</code>
791     * attribute value of every child node, excluding COMMENT_NODE and
792     * PROCESSING_INSTRUCTION_NODE nodes</td>
793     * </tr>
794     * <tr>
795     * <td valign='top' rowspan='1' colspan='1'>ATTRIBUTE_NODE, TEXT_NODE,
796     * CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE</td>
797     * <td valign='top' rowspan='1' colspan='1'>
798     * <code>nodeValue</code></td>
799     * </tr>
800     * <tr>
801     * <td valign='top' rowspan='1' colspan='1'>DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
802     * <td valign='top' rowspan='1' colspan='1'>
803     * null</td>
804     * </tr>
805     * </table>
806     * @exception DOMException
807     *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
808     * @exception DOMException
809     *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than
810     *   fit in a <code>DOMString</code> variable on the implementation
811     *   platform.
812     * @since DOM Level 3
813     */
814    virtual const XMLCh*           getTextContent() const = 0;
815
816    /**
817     * This attribute returns the text content of this node and its
818     * descendants. When it is defined to be null, setting it has no effect.
819     * When set, any possible children this node may have are removed and
820     * replaced by a single <code>DOMText</code> node containing the string
821     * this attribute is set to. On getting, no serialization is performed,
822     * the returned string does not contain any markup. No whitespace
823     * normalization is performed, the returned string does not contain the
824     * element content whitespaces . Similarly, on setting, no parsing is
825     * performed either, the input string is taken as pure textual content.
826     *
827     * <p><b>"Experimental - subject to change"</b></p>
828     *
829     * <br>The string returned is made of the text content of this node
830     * depending on its type, as defined below:
831     * <table border='1'>
832     * <tr>
833     * <th>Node type</th>
834     * <th>Content</th>
835     * </tr>
836     * <tr>
837     * <td valign='top' rowspan='1' colspan='1'>
838     * ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE,
839     * DOCUMENT_FRAGMENT_NODE</td>
840     * <td valign='top' rowspan='1' colspan='1'>concatenation of the <code>textContent</code>
841     * attribute value of every child node, excluding COMMENT_NODE and
842     * PROCESSING_INSTRUCTION_NODE nodes</td>
843     * </tr>
844     * <tr>
845     * <td valign='top' rowspan='1' colspan='1'>ATTRIBUTE_NODE, TEXT_NODE,
846     * CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE</td>
847     * <td valign='top' rowspan='1' colspan='1'>
848     * <code>nodeValue</code></td>
849     * </tr>
850     * <tr>
851     * <td valign='top' rowspan='1' colspan='1'>DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
852     * <td valign='top' rowspan='1' colspan='1'>
853     * null</td>
854     * </tr>
855     * </table>
856     * @exception DOMException
857     *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
858     * @exception DOMException
859     *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than
860     *   fit in a <code>DOMString</code> variable on the implementation
861     *   platform.
862     * @since DOM Level 3
863     */
864    virtual void                   setTextContent(const XMLCh* textContent) = 0;
865
866    /**
867     * Look up the prefix associated to the given namespace URI, starting from
868     * this node.
869     *
870     * <p><b>"Experimental - subject to change"</b></p>
871     *
872     * @param namespaceURI The namespace URI to look for.
873     * @param useDefault  Indicates if the lookup mechanism should take into
874     *   account the default namespace or not.
875     * @return Returns an associated namespace prefix if found,
876     *   <code>null</code> if none is found and <code>useDefault</code> is
877     *   false, or <code>null</code> if not found or it is the default
878     *   namespace and <code>useDefault</code> is <code>true</code>. If more
879     *   than one prefix are associated to the namespace prefix, the
880     *   returned namespace prefix is implementation dependent.
881     * @since DOM Level 3
882     */
883    virtual const XMLCh*           lookupNamespacePrefix(const XMLCh* namespaceURI,
884                                                         bool useDefault) const = 0;
885
886    /**
887     * This method checks if the specified <code>namespaceURI</code> is the
888     * default namespace or not.
889     *
890     * <p><b>"Experimental - subject to change"</b></p>
891     *
892     * @param namespaceURI The namespace URI to look for.
893     * @return  <code>true</code> if the specified <code>namespaceURI</code>
894     *   is the default namespace, <code>false</code> otherwise.
895     * @since DOM Level 3
896     */
897    virtual bool                   isDefaultNamespace(const XMLCh* namespaceURI) const = 0;
898
899    /**
900     * Look up the namespace URI associated to the given prefix, starting from
901     * this node.
902     *
903     * <p><b>"Experimental - subject to change"</b></p>
904     *
905     * @param prefix The prefix to look for. If this parameter is
906     *   <code>null</code>, the method will return the default namespace URI
907     *   if any.
908     * @return Returns the associated namespace URI or <code>null</code> if
909     *   none is found.
910     * @since DOM Level 3
911     */
912    virtual const XMLCh*           lookupNamespaceURI(const XMLCh* prefix) const  = 0;
913
914    /**
915     * This method makes available a <code>DOMNode</code>'s specialized interface
916     *
917     * <p><b>"Experimental - subject to change"</b></p>
918     *
919     * @param feature The name of the feature requested (case-insensitive).
920     * @return Returns an alternate <code>DOMNode</code> which implements the
921     *   specialized APIs of the specified feature, if any, or
922     *   <code>null</code> if there is no alternate <code>DOMNode</code> which
923     *   implements interfaces associated with that feature. Any alternate
924     *   <code>DOMNode</code> returned by this method must delegate to the
925     *   primary core <code>DOMNode</code> and not return results inconsistent
926     *   with the primary core <code>DOMNode</code> such as <code>key</code>,
927     *   <code>attributes</code>, <code>childNodes</code>, etc.
928     * @since DOM Level 3
929     */
930    virtual DOMNode*               getInterface(const XMLCh* feature) = 0;
931    //@}
932
933    // -----------------------------------------------------------------------
934    //  Non-standard Extension
935    // -----------------------------------------------------------------------
936    /** @name Non-standard Extension */
937    //@{
938    /**
939     * Called to indicate that this Node (and its associated children) is no longer in use
940     * and that the implementation may relinquish any resources associated with it and
941     * its associated children.
942     *
943     * If this is a document, any nodes it owns (created by DOMDocument::createXXXX())
944     * are also released.
945     *
946     * Access to a released object will lead to unexpected result.
947     *
948     * @exception DOMException
949     *   INVALID_ACCESS_ERR: Raised if this Node has a parent and thus should not be released yet.
950     */
951    virtual void              release() = 0;
952    //@}     
953#if defined(XML_DOMREFCOUNT_EXPERIMENTAL)
954    // -----------------------------------------------------------------------
955    //  Non-standard Extension
956    // -----------------------------------------------------------------------
957    /** @name Non-standard Extension */
958    //@{
959    /**
960         * This is custom function which can be implemented by classes deriving
961         * from DOMNode for implementing reference counting on DOMNodes. Any
962         * implementation which has memory management model which involves
963         * disposing of nodes immediately after being used can override this
964         * function to do that job.
965     */
966    virtual void decRefCount() {}
967    //@}
968
969    // -----------------------------------------------------------------------
970    //  Non-standard Extension
971    // -----------------------------------------------------------------------
972    /** @name Non-standard Extension */
973    //@{
974    /**
975         * This is custom function which can be implemented by classes deriving
976         * from DOMNode for implementing reference counting on DOMNodes.
977     */
978    virtual void incRefCount() {}
979    //@}
980#endif
981};
982
983/***
984 * Utilities macros for getting memory manager within DOM
985***/
986#define GET_OWNER_DOCUMENT(ptr)      \
987        ((DOMDocumentImpl*)(ptr->getOwnerDocument()))
988
989#define GET_DIRECT_MM(ptr)           \
990        ptr ? ((DOMDocumentImpl*)ptr)->getMemoryManager() : XMLPlatformUtils::fgMemoryManager       
991
992#define GET_INDIRECT_MM(ptr)                                                    \
993        !ptr ? XMLPlatformUtils::fgMemoryManager :                              \
994        GET_OWNER_DOCUMENT(ptr) ? GET_OWNER_DOCUMENT(ptr)->getMemoryManager() : \
995        XMLPlatformUtils::fgMemoryManager
996
997/***
998 * For DOMNode and its derivatives
999***/
1000#define GetDOMNodeMemoryManager GET_INDIRECT_MM(this)
1001
1002XERCES_CPP_NAMESPACE_END
1003
1004#endif
1005
Note: See TracBrowser for help on using the repository browser.