DOMNode interface is the primary datatype for the entire
* Document Object Model. It represents a single node in the document tree.
* While all objects implementing the DOMNode interface expose
* methods for dealing with children, not all objects implementing the
* DOMNode interface may have children. For example,
* DOMText nodes may not have children, and adding children to
* such nodes results in a DOMException being raised.
* The attributes nodeName, nodeValue and
* attributes are included as a mechanism to get at node
* information without casting down to the specific derived interface. In
* cases where there is no obvious mapping of these attributes for a
* specific nodeType (e.g., nodeValue for an
* DOMElement or attributes for a DOMComment
* ), this returns null. Note that the specialized interfaces
* may contain additional and more convenient mechanisms to get and set the
* relevant information.
*
The values of nodeName,
* nodeValue, and attributes vary according to the
* node type as follows:
*
| Interface | *nodeName | *nodeValue | *attributes | *
| DOMAttr | *name of * attribute | *value of attribute | *null | *
| DOMCDATASection | *"#cdata-section" |
* * content of the CDATA Section | *null | *
| DOMComment | *"#comment" |
* content of * the comment | *null | *
| DOMDocument | *"#document" |
* null | *null | *
| DOMDocumentFragment | *
* "#document-fragment" |
* null | *null | *
| DOMDocumentType | *document type name | ** null | *null | *
| DOMElement | *tag name | *null | *NamedNodeMap | *
| DOMEntity | *entity name | *null | *null | *
| DOMEntityReference | *name of entity referenced | *null | *null | *
| DOMNotation | *notation name | *null | ** null | *
| DOMProcessingInstruction | *target | *entire content excluding the target | *null | *
| DOMText | *
* "#text" |
* content of the text node | *null | *
See also the Document Object Model (DOM) Level 2 Core Specification. * * @since DOM Level 1 */ class CDOM_EXPORT DOMNode { protected: // ----------------------------------------------------------------------- // Hidden constructors // ----------------------------------------------------------------------- /** @name Hidden constructors */ //@{ DOMNode() {}; //@} private: // ----------------------------------------------------------------------- // Unimplemented constructors and operators // ----------------------------------------------------------------------- /** @name Unimplemented constructors and operators */ //@{ DOMNode(const DOMNode &); DOMNode & operator = (const DOMNode &); //@} public: // ----------------------------------------------------------------------- // All constructors are hidden, just the destructor is available // ----------------------------------------------------------------------- /** @name Destructor */ //@{ /** * Destructor * */ virtual ~DOMNode() {}; //@} // ----------------------------------------------------------------------- // Class Types // ----------------------------------------------------------------------- /** @name Public Contants */ //@{ /** * NodeType * * @since DOM Level 1 */ enum NodeType { ELEMENT_NODE = 1, ATTRIBUTE_NODE = 2, TEXT_NODE = 3, CDATA_SECTION_NODE = 4, ENTITY_REFERENCE_NODE = 5, ENTITY_NODE = 6, PROCESSING_INSTRUCTION_NODE = 7, COMMENT_NODE = 8, DOCUMENT_NODE = 9, DOCUMENT_TYPE_NODE = 10, DOCUMENT_FRAGMENT_NODE = 11, NOTATION_NODE = 12 }; /** * TreePosition: * *
"Experimental - subject to change"
* *TREE_POSITION_PRECEDING:
* The node precedes the reference node.
TREE_POSITION_FOLLOWING:
* The node follows the reference node.
TREE_POSITION_ANCESTOR:
* The node is an ancestor of the reference node.
TREE_POSITION_DESCENDANT:
* The node is a descendant of the reference node.
TREE_POSITION_EQUIVALENT:
* The two nodes have an equivalent position. This is the case of two
* attributes that have the same ownerElement, and two
* nodes that are the same.
TREE_POSITION_SAME_NODE:
* The two nodes are the same. Two nodes that are the same have an
* equivalent position, though the reverse may not be true.
TREE_POSITION_DISCONNECTED:
* The two nodes are disconnected, they do not have any common ancestor.
* This is the case of two nodes that are not in the same document.
DOMDocument,
* DOMDocumentFragment, and DOMAttr may have a parent.
* However, if a node has just been created and not yet added to the tree,
* or if it has been removed from the tree, a null DOMNode
* is returned.
* @since DOM Level 1
*/
virtual DOMNode *getParentNode() const = 0;
/**
* Gets a DOMNodeList that contains all children of this node.
*
* If there
* are no children, this is a DOMNodeList containing no nodes.
* The content of the returned DOMNodeList is "live" in the sense
* that, for instance, changes to the children of the node object that
* it was created from are immediately reflected in the nodes returned by
* the DOMNodeList accessors; it is not a static snapshot of the
* content of the node. This is true for every DOMNodeList,
* including the ones returned by the getElementsByTagName
* method.
* @since DOM Level 1
*/
virtual DOMNodeList *getChildNodes() const = 0;
/**
* Gets the first child of this node.
*
* If there is no such node, this returns null.
* @since DOM Level 1
*/
virtual DOMNode *getFirstChild() const = 0;
/**
* Gets the last child of this node.
*
* If there is no such node, this returns null.
* @since DOM Level 1
*/
virtual DOMNode *getLastChild() const = 0;
/**
* Gets the node immediately preceding this node.
*
* If there is no such node, this returns null.
* @since DOM Level 1
*/
virtual DOMNode *getPreviousSibling() const = 0;
/**
* Gets the node immediately following this node.
*
* If there is no such node, this returns null.
* @since DOM Level 1
*/
virtual DOMNode *getNextSibling() const = 0;
/**
* Gets a DOMNamedNodeMap containing the attributes of this node (if it
* is an DOMElement) or null otherwise.
* @since DOM Level 1
*/
virtual DOMNamedNodeMap *getAttributes() const = 0;
/**
* Gets the DOMDocument object associated with this node.
*
* This is also
* the DOMDocument object used to create new nodes. When this
* node is a DOMDocument or a DOMDocumentType
* which is not used with any DOMDocument yet, this is
* null.
*
* @since DOM Level 1
*/
virtual DOMDocument *getOwnerDocument() const = 0;
// -----------------------------------------------------------------------
// Node methods
// -----------------------------------------------------------------------
/**
* Returns a duplicate of this node.
*
* This function serves as a generic copy constructor for nodes.
*
* The duplicate node has no parent (
* parentNode returns null.).
* DOMElement copies all attributes and their
* values, including those generated by the XML processor to represent
* defaulted attributes, but this method does not copy any text it contains
* unless it is a deep clone, since the text is contained in a child
* DOMText node. Cloning any other type of node simply returns a
* copy of this node.
* @param deep If true, recursively clone the subtree under the
* specified node; if false, clone only the node itself (and
* its attributes, if it is an DOMElement).
* @return The duplicate node.
* @since DOM Level 1
*/
virtual DOMNode * cloneNode(bool deep) const = 0;
/**
* Inserts the node newChild before the existing child node
* refChild.
*
* If refChild is null,
* insert newChild at the end of the list of children.
* newChild is a DOMDocumentFragment object,
* all of its children are inserted, in the same order, before
* refChild. If the newChild is already in the
* tree, it is first removed. Note that a DOMNode that
* has never been assigned to refer to an actual node is == null.
* @param newChild The node to insert.
* @param refChild The reference node, i.e., the node before which the new
* node must be inserted.
* @return The node being inserted.
* @exception DOMException
* HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
* allow children of the type of the newChild node, or if
* the node to insert is one of this node's ancestors.
* newChild was created
* from a different document than the one that created this node.
* refChild is not a child of
* this node.
* @since DOM Level 1
*/
virtual DOMNode *insertBefore(DOMNode *newChild,
DOMNode *refChild) = 0;
/**
* Replaces the child node oldChild with newChild
* in the list of children, and returns the oldChild node.
*
* If newChild is a DOMDocumentFragment object,
* oldChild is replaced by all of the DOMDocumentFragment
* children, which are inserted in the same order.
*
* If the newChild is already in the tree, it is first removed.
* @param newChild The new node to put in the child list.
* @param oldChild The node being replaced in the list.
* @return The node replaced.
* @exception DOMException
* HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
* allow children of the type of the newChild node, or it
* the node to put in is one of this node's ancestors.
* newChild was created
* from a different document than the one that created this node.
* oldChild is not a child of
* this node.
* @since DOM Level 1
*/
virtual DOMNode *replaceChild(DOMNode *newChild,
DOMNode *oldChild) = 0;
/**
* Removes the child node indicated by oldChild from the list
* of children, and returns it.
*
* @param oldChild The node being removed.
* @return The node removed.
* @exception DOMException
* NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
* oldChild is not a child of
* this node.
* @since DOM Level 1
*/
virtual DOMNode *removeChild(DOMNode *oldChild) = 0;
/**
* Adds the node newChild to the end of the list of children of
* this node.
*
* If the newChild is already in the tree, it is
* first removed.
* @param newChild The node to add.If it is a DOMDocumentFragment
* object, the entire contents of the document fragment are moved into
* the child list of this node
* @return The node added.
* @exception DOMException
* HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
* allow children of the type of the newChild node, or if
* the node to append is one of this node's ancestors.
* newChild was created
* from a different document than the one that created this node.
* true if the node has any children,
* false if the node has no children.
* @since DOM Level 1
*/
virtual bool hasChildNodes() const = 0;
// -----------------------------------------------------------------------
// Setter methods
// -----------------------------------------------------------------------
/**
* Sets the value of the node.
*
* Any node which can have a nodeValue (@see getNodeValue) will
* also accept requests to set it to a string. The exact response to
* this varies from node to node -- Attribute, for example, stores
* its values in its children and has to replace them with a new Text
* holding the replacement value.
*
* For most types of Node, value is null and attempting to set it
* will throw DOMException(NO_MODIFICATION_ALLOWED_ERR). This will
* also be thrown if the node is read-only.
* @since DOM Level 1
*/
virtual void setNodeValue(const XMLCh *nodeValue) = 0;
//@}
/** @name Functions introduced in DOM Level 2. */
//@{
/**
* Puts all DOMText
* nodes in the full depth of the sub-tree underneath this DOMNode,
* including attribute nodes, into a "normal" form where only markup (e.g.,
* tags, comments, processing instructions, CDATA sections, and entity
* references) separates DOMText
* nodes, i.e., there are neither adjacent DOMText
* nodes nor empty DOMText
* nodes. This can be used to ensure that the DOM view of a document is the
* same as if it were saved and re-loaded, and is useful when operations
* (such as XPointer lookups) that depend on a particular document tree
* structure are to be used.
* Note: In cases where the document contains DOMCDATASections,
* the normalize operation alone may not be sufficient, since XPointers do
* not differentiate between DOMText
* nodes and DOMCDATASection
* nodes.
hasFeature on
* DOMImplementation.
* @param version This is the version number of the feature to test. In
* Level 2, version 1, this is the string "2.0". If the version is not
* specified, supporting any version of the feature will cause the
* method to return true.
* @return Returns true if the specified feature is supported
* on this node, false otherwise.
* @since DOM Level 2
*/
virtual bool isSupported(const XMLCh *feature,
const XMLCh *version) const = 0;
/**
* Get the namespace URI of
* this node, or null if it is unspecified.
* * This is not a computed value that is the result of a namespace lookup * based on an examination of the namespace declarations in scope. It is * merely the namespace URI given at creation time. *
* For nodes of any type other than ELEMENT_NODE and
* ATTRIBUTE_NODE and nodes created with a DOM Level 1 method,
* such as createElement from the DOMDocument
* interface, this is always null.
*
* @since DOM Level 2
*/
virtual const XMLCh * getNamespaceURI() const = 0;
/**
* Get the namespace prefix
* of this node, or null if it is unspecified.
*
* @since DOM Level 2
*/
virtual const XMLCh * getPrefix() const = 0;
/**
* Returns the local part of the qualified name of this node.
*
* For nodes created with a DOM Level 1 method, such as
* createElement from the DOMDocument interface,
* it is null.
*
* @since DOM Level 2
*/
virtual const XMLCh * getLocalName() const = 0;
/**
* Set the namespace prefix of this node.
*
* Note that setting this attribute, when permitted, changes
* the nodeName attribute, which holds the qualified
* name, as well as the tagName and name
* attributes of the DOMElement and DOMAttr
* interfaces, when applicable.
*
* Note also that changing the prefix of an
* attribute, that is known to have a default value, does not make a new
* attribute with the default value and the original prefix appear, since the
* namespaceURI and localName do not change.
*
*
* @param prefix The prefix of this node.
* @exception DOMException
* INVALID_CHARACTER_ERR: Raised if the specified prefix contains
* an illegal character.
*
* NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
*
* NAMESPACE_ERR: Raised if the specified prefix is
* malformed, if the namespaceURI of this node is
* null, if the specified prefix is "xml" and the
* namespaceURI of this node is different from
* "http://www.w3.org/XML/1998/namespace", if this node is an attribute
* and the specified prefix is "xmlns" and the
* namespaceURI of this node is different from
* "http://www.w3.org/2000/xmlns/", or if this node is an attribute and
* the qualifiedName of this node is "xmlns".
* @since DOM Level 2
*/
virtual void setPrefix(const XMLCh * prefix) = 0;
/**
* Returns whether this node (if it is an element) has any attributes.
* @return true if this node has any attributes,
* false otherwise.
* @since DOM Level 2
*/
virtual bool hasAttributes() const = 0;
//@}
/** @name Functions introduced in DOM Level 3. */
//@{
/**
* Returns whether this node is the same node as the given one.
*
This method provides a way to determine whether two
* DOMNode references returned by the implementation reference
* the same object. When two DOMNode references are references
* to the same object, even if through a proxy, the references may be
* used completely interchangeably, such that all attributes have the
* same values and calling the same DOM method on either reference
* always has exactly the same effect.
*
*
"Experimental - subject to change"
* * @param other The node to test against. * @return Returnstrue if the nodes are the same,
* false otherwise.
* @since DOM Level 3
*/
virtual bool isSameNode(const DOMNode* other) const = 0;
/**
* Tests whether two nodes are equal.
* DOMNode::isSameNode. All nodes that are the same
* will also be equal, though the reverse may not be true.
* nodeName, localName,
* namespaceURI, prefix, nodeValue
* , baseURI. This is: they are both null, or
* they have the same length and are character for character identical.
* The attributes DOMNamedNodeMaps are equal.
* This is: they are both null, or they have the same
* length and for each node that exists in one map there is a node that
* exists in the other map and is equal, although not necessarily at the
* same index.The childNodes DOMNodeLists are
* equal. This is: they are both null, or they have the
* same length and contain equal nodes at the same index. This is true
* for DOMAttr nodes as for any other type of node. Note that
* normalization can affect equality; to avoid this, nodes should be
* normalized before being compared.
* DOMDocumentType nodes to be equal, the following
* conditions must also be satisfied: The following string attributes
* are equal: publicId, systemId,
* internalSubset.The entities
* DOMNamedNodeMaps are equal.The notations
* DOMNamedNodeMaps are equal.
* ownerDocument attribute, the specified
* attribute for DOMAttr nodes, the
* isWhitespaceInElementContent attribute for
* DOMText nodes, as well as any user data or event listeners
* registered on the nodes.
*
* "Experimental - subject to change"
* * @param arg The node to compare equality with. * @return If the nodes, and possibly subtrees are equal, *true otherwise false.
* @since DOM Level 3
*/
virtual bool isEqualNode(const DOMNode* arg) const = 0;
/**
* Associate an object to a key on this node. The object can later be
* retrieved from this node by calling getUserData with the
* same key.
*
* Deletion of the user data remains the responsibility of the
* application program; it will not be automatically deleted when
* the nodes themselves are reclaimed.
*
* Both the parameter data and the returned object are
* void pointer, it is applications' responsibility to keep track of
* their original type. Casting them to the wrong type may result
* unexpected behavior.
*
* "Experimental - subject to change"
* * @param key The key to associate the object to. * @param data The object to associate to the given key, or *null to remove any existing association to that key.
* @param handler The handler to associate to that key, or
* null.
* @return Returns the void* object previously associated to
* the given key on this node, or null if there was none.
* @see getUserData
*
* @since DOM Level 3
*/
virtual void* setUserData(const XMLCh* key,
void* data,
DOMUserDataHandler* handler) = 0;
/**
* Retrieves the object associated to a key on a this node. The object
* must first have been set to this node by calling
* setUserData with the same key.
*
* "Experimental - subject to change"
* * @param key The key the object is associated to. * @return Returns thevoid* associated to the given key
* on this node, or null if there was none.
* @see setUserData
* @since DOM Level 3
*/
virtual void* getUserData(const XMLCh* key) const = 0;
/**
* The absolute base URI of this node or null if undefined.
* This value is computed according to . However, when the
* DOMDocument supports the feature "HTML" , the base URI is
* computed using first the value of the href attribute of the HTML BASE
* element if any, and the value of the documentURI
* attribute from the DOMDocument interface otherwise.
*
* "Experimental - subject to change"
* *DOMElement, a DOMDocument
* or a a DOMProcessingInstruction, this attribute represents
* the properties [base URI] defined in . When the node is a
* DOMNotation, an DOMEntity, or an
* DOMEntityReference, this attribute represents the
* properties [declaration base URI].
* @since DOM Level 3
*/
virtual const XMLCh* getBaseURI() const = 0;
/**
* Compares a node with this node with regard to their position in the
* tree and according to the document order. This order can be extended
* by module that define additional types of nodes.
*
* "Experimental - subject to change"
* * @param other The node to compare against this node. * @return Returns how the given node is positioned relatively to this * node. * @since DOM Level 3 */ virtual short compareTreePosition(const DOMNode* other) const = 0; /** * This attribute returns the text content of this node and its * descendants. When it is defined to be null, setting it has no effect. * When set, any possible children this node may have are removed and * replaced by a singleDOMText node containing the string
* this attribute is set to. On getting, no serialization is performed,
* the returned string does not contain any markup. No whitespace
* normalization is performed, the returned string does not contain the
* element content whitespaces . Similarly, on setting, no parsing is
* performed either, the input string is taken as pure textual content.
*
* "Experimental - subject to change"
* *| Node type | *Content | *
|---|---|
| * ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, * DOCUMENT_FRAGMENT_NODE | *concatenation of the textContent
* attribute value of every child node, excluding COMMENT_NODE and
* PROCESSING_INSTRUCTION_NODE nodes |
*
| ATTRIBUTE_NODE, TEXT_NODE, * CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE | *
* nodeValue |
*
| DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE | ** null | *
DOMString variable on the implementation
* platform.
* @since DOM Level 3
*/
virtual const XMLCh* getTextContent() const = 0;
/**
* This attribute returns the text content of this node and its
* descendants. When it is defined to be null, setting it has no effect.
* When set, any possible children this node may have are removed and
* replaced by a single DOMText node containing the string
* this attribute is set to. On getting, no serialization is performed,
* the returned string does not contain any markup. No whitespace
* normalization is performed, the returned string does not contain the
* element content whitespaces . Similarly, on setting, no parsing is
* performed either, the input string is taken as pure textual content.
*
* "Experimental - subject to change"
* *| Node type | *Content | *
|---|---|
| * ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, * DOCUMENT_FRAGMENT_NODE | *concatenation of the textContent
* attribute value of every child node, excluding COMMENT_NODE and
* PROCESSING_INSTRUCTION_NODE nodes |
*
| ATTRIBUTE_NODE, TEXT_NODE, * CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE | *
* nodeValue |
*
| DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE | ** null | *
DOMString variable on the implementation
* platform.
* @since DOM Level 3
*/
virtual void setTextContent(const XMLCh* textContent) = 0;
/**
* Look up the prefix associated to the given namespace URI, starting from
* this node.
*
* "Experimental - subject to change"
* * @param namespaceURI The namespace URI to look for. * @param useDefault Indicates if the lookup mechanism should take into * account the default namespace or not. * @return Returns an associated namespace prefix if found, *null if none is found and useDefault is
* false, or null if not found or it is the default
* namespace and useDefault is true. If more
* than one prefix are associated to the namespace prefix, the
* returned namespace prefix is implementation dependent.
* @since DOM Level 3
*/
virtual const XMLCh* lookupNamespacePrefix(const XMLCh* namespaceURI,
bool useDefault) const = 0;
/**
* This method checks if the specified namespaceURI is the
* default namespace or not.
*
* "Experimental - subject to change"
* * @param namespaceURI The namespace URI to look for. * @returntrue if the specified namespaceURI
* is the default namespace, false otherwise.
* @since DOM Level 3
*/
virtual bool isDefaultNamespace(const XMLCh* namespaceURI) const = 0;
/**
* Look up the namespace URI associated to the given prefix, starting from
* this node.
*
* "Experimental - subject to change"
* * @param prefix The prefix to look for. If this parameter is *null, the method will return the default namespace URI
* if any.
* @return Returns the associated namespace URI or null if
* none is found.
* @since DOM Level 3
*/
virtual const XMLCh* lookupNamespaceURI(const XMLCh* prefix) const = 0;
/**
* This method makes available a DOMNode's specialized interface
*
* "Experimental - subject to change"
* * @param feature The name of the feature requested (case-insensitive). * @return Returns an alternateDOMNode which implements the
* specialized APIs of the specified feature, if any, or
* null if there is no alternate DOMNode which
* implements interfaces associated with that feature. Any alternate
* DOMNode returned by this method must delegate to the
* primary core DOMNode and not return results inconsistent
* with the primary core DOMNode such as key,
* attributes, childNodes, etc.
* @since DOM Level 3
*/
virtual DOMNode* getInterface(const XMLCh* feature) = 0;
//@}
// -----------------------------------------------------------------------
// Non-standard Extension
// -----------------------------------------------------------------------
/** @name Non-standard Extension */
//@{
/**
* Called to indicate that this Node (and its associated children) is no longer in use
* and that the implementation may relinquish any resources associated with it and
* its associated children.
*
* If this is a document, any nodes it owns (created by DOMDocument::createXXXX())
* are also released.
*
* Access to a released object will lead to unexpected result.
*
* @exception DOMException
* INVALID_ACCESS_ERR: Raised if this Node has a parent and thus should not be released yet.
*/
virtual void release() = 0;
//@}
#if defined(XML_DOMREFCOUNT_EXPERIMENTAL)
// -----------------------------------------------------------------------
// Non-standard Extension
// -----------------------------------------------------------------------
/** @name Non-standard Extension */
//@{
/**
* This is custom function which can be implemented by classes deriving
* from DOMNode for implementing reference counting on DOMNodes. Any
* implementation which has memory management model which involves
* disposing of nodes immediately after being used can override this
* function to do that job.
*/
virtual void decRefCount() {}
//@}
// -----------------------------------------------------------------------
// Non-standard Extension
// -----------------------------------------------------------------------
/** @name Non-standard Extension */
//@{
/**
* This is custom function which can be implemented by classes deriving
* from DOMNode for implementing reference counting on DOMNodes.
*/
virtual void incRefCount() {}
//@}
#endif
};
XERCES_CPP_NAMESPACE_END
#endif