source: NonGTP/Xerces/xercesc/dom/DOMNode.hpp @ 188

Revision 188, 43.9 KB checked in by mattausch, 19 years ago (diff)

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