The Dom Node class

Summary:

Syntax
Methods
Examples
- Counting the number of nodes in an XML document

Syntax

The DomNode class provides methods to manipulate a node of a DomDocument object. You can create a DomNode object using creation methods in the DomDocument class. Notice that status is set to zero after a successful method call.

Syntax

xml.DomNode

Navigation methods

Object Methods
Name	Description
`getParentNode() RETURNING xml.DomNode`	Returns the parent DomNode object for this DomNode object, or NULL. In the case of a DomDocument node, this method will return NULL (parent is not a DomNode object) but `isAttached()` will return TRUE.
`getFirstChild() RETURNING xml.DomNode`	Returns the first child DomNode object for this XML Element DomNode object, or NULL.
`getFirstChildElement() RETURNING xml.DomNode`	Returns the first XML Element child DomNode object for this DomNode object, or NULL. (Not part of W3C API).
`getLastChild() RETURNING xml.DomNode`	Returns the last child DomNode object for this XML Element DomNode object, or NULL.
`getLastChildElement() RETURNING xml.DomNode`	Returns the last child XML element DomNode object for this DomNode object, or NULL. (Not part of W3C API).
`getNextSibling() RETURNING xml.DomNode`	Returns the DomNode object immediately following this DomNode object, or NULL.
`getNextSiblingElement() RETURNING xml.DomNode`	Returns the XML Element DomNode object immediately following this DomNode object, or NULL. (Not part of W3C API).
`getPreviousSibling() RETURNING xml.DomNode`	Returns the DomNode object immediately preceding this DomNode object, or NULL.
`getPreviousSiblingElement() RETURNING xml.DomNode`	Returns the XML Element DomNode object immediately preceding this DomNode object, or NULL. (Not part of W3C API).
`getOwnerDocument() RETURNING xml.DomDocument`	Returns the DomDocument object containing this DomNode object, or NULL.
`hasChildNodes() RETURNING INTEGER`	Returns TRUE if this node has child nodes; otherwise, returns FALSE.
`getChildrenCount() RETURNING INTEGER`	Returns the number of child DomNode objects for this DomNode object.
`getChildNodeItem(pos INTEGER) RETURNING xml.DomNode`	Returns the child DomNode object at a given position for this DomNode object. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Manipulation methods

Object Methods
Name	Description
`prependChildElement(name STRING) RETURNING xml.DomNode`	Creates and adds a child XML Element node to the beginning of the list of child nodes for this XML Element DomNode object (Not part of W3C API); name is the name of the XML element to add. Returns the XML Element DomNode object, or NULL. Throws an exception in case of errors, and updates status with an error code.
`prependChildElementNS(prefix STRING,name STRING, ns STRING) RETURNING xml.DomNode`	Creates and adds a child namespace-qualified XML Element node to the beginning of the list of child nodes for this XML Element DomNode object (Not part of W3C API); name is the name of the XML Element to add; ns is the namespace URI of the XML Element to add. Returns the XML Element DomNode object, or NULL. Throws an exception in case of errors, and updates status with an error code.
`addPreviousSibling(node xml.DomNode)`	Adds a DomNode object as the previous sibling of this DomNode object (Not part of W3C API); node is the node to add. Note: The DomNode object node must be the child of an element or document node; otherwise, the operation fails. Throws an exception in case of errors, and updates status with an error code.
`addNextSibling(node xml.DomNode)`	Adds a DomNode object as the next sibling of this DomNode object (Not part of W3C API); node is the node to add. Note: The DomNode object node must be the child of an element or document node; otherwise, the operation fails. Throws an exception in case of errors, and updates status with an error code.
`prependChild(node xml.DomNode)`	Adds a child DomNode object to the beginning of the child list for this DomNode object (Not part of W3C API); node is the node to add. Note: The DomNode object node must be the child of an element or document node; otherwise, the operation fails. Throws an exception in case of errors, and updates status with an error code.
`appendChild(node xml.DomNode)`	Adds a child DomNode object to the end of the child list for this DomNode object; node is the node to add. Note: The DomNode object node must be the child of an element or document node; otherwise, the operation fails. Throws an exception in case of errors, and updates status with an error code.
`insertBeforeChild(node xml.DomNode,ref xml.DomNode)`	Inserts a DomNode object before an existing child DomNode object; node is the node to insert, ref is the reference node - the node before which the new node must be inserted. Throws an exception in case of errors, and updates status with an error code.
`insertAfterChild(node xml.DomNode,ref xml.DomNode)`	Inserts a DomNode object after an existing child DomNode object (Not part of W3C API); node is the node to insert, ref is the reference node - the node after which the new node must be inserted. Throws an exception in case of errors, and updates status with an error code.
`removeChild(node xml.DomNode)`	Removes a child DomNode object from the list of child DomNode objects, where node is the node to remove. Throws an exception in case of errors, and updates status with an error code.
`removeAllChildren()`	Removes all child DomNode objects from this DomNode object Throws an exception in case of errors, and updates status with an error code.
`replaceChild(new xml.DomNode,old xml.DomNode)`	Replaces an existing child DomNode with another child DomNode object, where old is the child to be replaced and new is the replacement child. Throws an exception in case of errors, and updates status with an error code.
`appendChildElement(name STRING) RETURNING xml.DomNode`	Creates and adds a child XML Element node to the end of the list of child nodes for this XML Element DomNode object (Not part of W3C API); name is the XML Element name. Returns the XML Element DomNode object, or NULL. Throws an exception in case of errors, and updates status with an error code.
`appendChildElementNS(prefix STRING,name STRING, ns STRING) RETURNING xml.DomNode`	Creates and adds a child namespace qualified XML Element node to the end of the list of child nodes for this XML Element DomNode object (Not part of W3C API); prefix is the prefix of the XML Element to add; name is the name of the XML Element to add; ns is the namespace URI of the XML Element to add. Returns the XML Element DomNode object, or NULL. Throws an exception in case of errors, and updates status with an error code.
`clone(deep INTEGER) RETURNING xml.DomNode`	Returns a duplicate DomNode object of this node. If deep is TRUE, child DomNode objects are cloned too; otherwise, only the DomNode itself is cloned. Returns a copy of this DomNode object, or NULL.* Throws an exception in case of errors, and updates status with an error code.

Back to the top

Access methods

Object Methods
Name	Description
`getNodeType() RETURNING STRING`	Gets the XML type for this DomNode object; returns one of the XML DomNode types, or NULL.
`getLocalName() RETURNING STRING`	Gets the local name for this DomNode object. If DomNode has a qualified name, only the local part is returned.
`getNodeName() RETURNING STRING`	Gets the name for this DomNode object; returns the qualified name of this DomNode object, or NULL. If DomNode does not have a qualified name, the local part is returned.
`getNamespaceURI()RETURNING STRING`	Returns the namespace URI for this DomNode object, or NULL.
`getNodeValue() RETURNING STRING`	Returns the value for this DomNode object, or NULL.
`getPrefix() RETURNING STRING`	Returns the prefix for this DomNode object, or NULL.
`isAttached() RETURNING INTEGER`	Returns whether the node is attached to the XML document (Not part of W3C API). Returns TRUE if this DomNode object is attached to a DomDocument object as a child and was not removed later on; otherwise it returns FALSE.

Back to the top

Modifier methods

Object Methods
Name	Description
`setNodeValue(val STRING)`	Sets the node value for this DomNode object, where val is the node value. Throws an exception in case of errors, and updates status with an error code.
`setPrefix(prefix STRING)`	Sets the prefix for this DomNode object. Note: This method is only valid on namespace qualified Element or Attribute nodes. Throws an exception in case of errors, and updates status with an error code.
`toString() RETURNING STRING`	Returns a string representation of this DomNode object, or NULL (Not part of W3C API). Throws an exception in case of errors, and updates status with an error code.

Back to the top

Attributes methods

Object Methods
Name	Description
`hasAttribute(name STRING) RETURNING INTEGER`	Checks whether this XML Element DomNode object has the XML Attribute specified by name. Returns TRUE if an XML Attribute with the given name is carried by this XML Element DomNode object; otherwise, returns FALSE. Throws an exception in case of errors, and updates status with an error code.
`hasAttributeNS(name STRING,ns STRING) RETURNING INTEGER`	Checks whether a namespace qualified XML Attribute of a given name is carried by this XML Element DomNode object, where name the name of the XML Attribute to check ns: the namespace URI of the XML Attribute to check Returns TRUE if an XML Attribute with the given name and namespace URI is carried by this XML Element DomNode object, FALSE otherwise. Throws an exception in case of errors, and updates status with an error code.
`getAttributeNode(name STRING) RETURNING xml.DomNode`	Returns an XML Attribute DomNode object for this XML Element DomNode object, or NULL; name is the name of the attribute to retrieve. Throws an exception in case of errors, and updates status with an error code.
`getAttributeNodeNS(name STRING,ns STRING) RETURNING xml.DomNode`	Returns a namespace-qualified XML Attribute DomNode object for this XML Element DomNode object, or NULL; name is the name of the XML Attribute to retrieve and ns is the namespace URI of the XML Attribute to retrieve. Throws an exception in case of errors, and updates status with an error code.
`setAttributeNode(node xml.DomNode)`	Sets (or resets) an XML Attribute DomNode object to an XML Element DomNode object, , where node is the XML Attribute DomNode object to set. Throws an exception in case of errors, and updates status with an error code.
`setAttributeNodeNS(node xml.DomNode)`	Sets (or resets) a namespace-qualified XML Attribute DomNode object to an XML Element DomNode object, where node is the XML Attribute DomNode object to set. Throws an exception in case of errors, and updates status with an error code.
`getAttribute(name STRING) RETURNING STRING`	Returns the value of an XML Attribute for this XML Element DomNode object, where name is the name of the XML attribute to retrieve; returns the XML Attribute value, or NULL. Throws an exception in case of errors, and updates status with an error code.
`getAttributeNS(name STRING,ns STRING) RETURNING STRING`	Returns the value of a namespace qualified XML Attribute for this XML Element DomNode object, where name is the name and ns is the namespace URI of the XML Attribute to retrieve; returns the XML Attribute value, or NULL. Throws an exception in case of errors, and updates status with an error code.
`setAttribute(name STRING,value STRING)`	Sets (or resets) an XML Attribute for this XML Element DomNode object, where name is the name of the XML Attribute and val is the value of the XML Attribute. Throws an exception in case of errors, and updates status with an error code.
`setAttributeNS(prefix STRING,name STRING, ns STRING,value STRING)`	Sets (or resets) a namespace-qualified XML Attribute for this XML Element DomNode object, where prefix is the prefix of the XML Attribute, name is the name of the XML Attribute, ns is the namespace URI of the XML Attribute, and val is the value of the XML Attribute. Throws an exception in case of errors, and updates status with an error code.
`setIdAttribute(name STRING,isID INTEGER)`	Declare (or undeclare) the XML Attribute of given name to be of type ID. Use the value TRUE for the parameter isID to declare that attribute for being a user-determined ID attribute, false otherwise. Note: This affects the behavior of getElementById. Throws an exception in case of errors, and updates status with an error code.
`setIdAttributeNS(name STRING, ns STRING,isID INTEGER)`	Declare (or undeclare) the namespace-qualified XML Attribute of given name and namespace to be of type ID. Use the value TRUE for the parameter isID to declare that attribute for being a user-determined ID attribute, false otherwise. Note: This affects the behavior of getElementById. Throws an exception in case of errors, and updates status with an error code.
`removeAttribute(name STRING)`	Removes an XML Attribute for this XML Element DomNode object, where name is the name of the XML attribute to remove. Status is updated with an error code. Throws an exception in case of errors, and updates status with an error code.
`removeAttributeNS(name STRING,ns STRING)`	Removes a namespace qualified XML Attribute for this XML Element DomNode object, where name is the name and ns is the namespace URI of the XML Attribute to remove. Throws an exception in case of errors, and updates status with an error code.
`hasAttributes() RETURNING INTEGER`	Returns TRUE if this node has XML Attribute nodes; otherwise, returns FALSE.
`getAttributesCount() RETURNING INTEGER`	Returns the number of XML Attribute DomNode objects on this XML Element DomNode object. Throws an exception in case of errors, and updates status with an error code.
`getAttributeNodeItem(pos INTEGER) RETURNING xml.DomNode`	Returns the XML Attribute DomNode object at a given position on this XML Element DomNode object, where pos is the position of the node to return (Index starts at 1). Returns the XML Attribute DomNode object at the given position, or NULL. Throws an exception in case of errors, and updates status with an error code.

Back to the top

Search methods

Object Methods
Name	Description
`selectByXPath(expr STRING, NamespacesList ...) RETURNING xml.DomNodeList`	Returns a DomNodeList object containing all DomNode objects matching an XPath 1.0 expression (Not part of W3C API); expr is the XPath 1.0 expression, NamespacesList is a list of prefixes bounded to namespaces in order to resolve qualified names in the XPath expression. This list must be filled with an even number of arguments, representing the prefix and it corresponding namespace. Examples : `selectByXPath("../../d:Record/[last()]", "d", "http://defaultnamespace")` `selectByXPath("ns:Record", NULL)` `selectByXPath("ns1:Records/ns2:Record", "ns1", "http://namespace1", "ns2", "http://namespace2")` `selectByXPath("ns1:Record", "ns1")` is invalid because the namespace definition is missing. Note:* If the namespaces list is NULL, the prefixes and namespaces defined in the document itself are used if available. Note: A namespace must be an absolute URI (ex 'http://', 'file://'). Throws an exception in case of errors, and updates status with an error code.
`getElementsByTagName(name STRING) RETURNING xml.DomNodeList`	Returns a DomNodeList object containing all XML Element DomNode objects with the same tag name, or NULL; name is the name of the XML Element tag to match, or "*" to match all tags. Throws an exception in case of errors, and updates status with an error code.
`getElementsByTagNameNS(name STRING,ns STRING) RETURNING xml.DomNodeList`	Returns a DomNodeList object containing all namespace-qualified XML Element DomNode objects with the same tag name and namespace, OR NULL. name is the name of the XML Element tag to match, or "" to match all tags; ns is the namespace URI of the XML Element tag to match, or "" to match any namespace. Throws an exception in case of errors, and updates status with an error code.
`isDefaultNamespace(ns STRING) RETURNING INTEGER`	Checks whether the specified namespace URI is the default namespace, where ns is the namespace URI to look for. Returns TRUE if the given namespace is the default namespace, FALSE otherwise. Throws an exception in case of errors, and updates status with an error code.
`lookupNamespaceURI(prefix STRING) RETURNING STRING`	Looks up the namespace URI associated to a prefix, starting from this node, where prefix is the prefix to look for; if NULL, the default namespace URI will be returned. Returns a namespace URI, or NULL. Throws an exception in case of errors, and updates status with an error code.
`lookupPrefix(ns STRING) RETURNING STRING`	Looks up the prefix associated to a namespace URI, starting from this node, where ns is the namespace URI to look for. Returns the prefix associated to this namespace URI, or NULL. Throws an exception in case of errors, and updates status with an error code.

Usage

The getElementsByTagName and getElementsByTagNameNS methods return a DomNodeList object, unlike the other methods that return a DomNode object. The DomNodeList is restricted to contain objects with the same tag name and/or namespace.

Back to the top

DomNode types

Type	Description
ELEMENT_NODE	The DomNode is an XML Element node.
ATTRIBUTE_NODE	The DomNode is an XML Attribute node.
TEXT_NODE	The DomNode is an XML Text node.
CDATA_SECTION_NODE	The DomNode is an XML CData Section node.
ENTITY_REFERENCE_NODE	The DomNode is an XML Entity Reference node.
PROCESSING_INSTRUCTION_NODE	The DomNode is an XML Processing Instruction node.
COMMENT_NODE	The DomNode is an XML Comment node.
DOCUMENT_TYPE_NODE	The DomNode is an XML DTD node.
DOCUMENT_FRAGMENT_NODE	The DomNode is an XML Document Fragment node.

Examples

Example 1 : Counting the number of nodes in an XML document

Following code counts the number of nodes of each type :

 
01 IMPORT XML
02 
03 DEFINE nbElt INTEGER
04 DEFINE nbAttr INTEGER
05 DEFINE nbComment INTEGER
06 DEFINE nbPI INTEGER
07 DEFINE nbTxt INTEGER
08 DEFINE nbCData INTEGER
09 MAIN
10  DEFINE document xml.DomDocument
11   DEFINE ind INTEGER
12   # Handle arguments   
13  IF num_args() !=1 THEN
14    CALL ExitHelp()
15   END IF 
16   # Create document, load it, and count the nodes 
17   LET document = xml.DomDocument.Create()
18   CALL document.load(arg_val(1)) 
19   CALL CountDoc(document) 
20   # Display result
21   DISPLAY "Results: "
22   DISPLAY " Elements: ",nbElt
23   DISPLAY " Attributes:",nbAttr
24   DISPLAY " Comments: ",nbComment
25   DISPLAY " PI: ",nbPI
26   DISPLAY " Texts: ",nbTxt
27   DISPLAY " CData: ",nbCData 
28 END MAIN
29
30 FUNCTION CountDoc(d)
31 DEFINE d xml.DomDocument
32   DEFINE n xml.DomNode
33   LET n = d.getFirstDocumentNode()
34   WHILE (n IS NOT NULL)
35    CALL Count(n)
36     LET n = n.getNextSibling()
37   END WHILE
38 END FUNCTION
39
40 FUNCTION Count(n)
41 DEFINE n xml.DomNode
42   DEFINE child xml.DomNode
43   DEFINE next xml.DomNode
44   DEFINE node xml.DomNode
45   DEFINE ind INTEGER
46   DEFINE name STRING
47   IF n IS NOT NULL THEN
48    IF n.getNodeType() == "COMMENT_NODE" THEN
49      LET nbComment = nbComment + 1
50     END IF 
51     IF n.getNodeType() == "ATTRIBUTE_NODE" THEN 
52       LET nbAttr = nbAttr + 1
53     END IF 
54     IF n.getNodeType() == "PROCESSING_INSTRUCTION_NODE " THEN
55      LET nbPI = nbPI + 1
56     END IF 
57     IF n.getNodeType() == "ELEMENT_NODE" THEN
58       LET nbElt = nbElt + 1
59     END IF 
60     IF n.getNodeType() == "TEXT_NODE" THEN
61       LET nbTxt = nbTxt +1
62     END IF
63     IF n.getNodeType() == "CDATA_SECTION_NODE" THEN
64     LET nbCData = nbCData + 1
65     END IF
66     IF n.hasChildNodes() THEN
67      LET name = n.getLocalName()
68       LET child = n.getFirstChild()
69       WHILE (child IS NOT NULL) 
70         CALL Count(child)
71         LET child = child.getNextSibling() 
72       END WHILE 
73     END IF
74     IF n.hasAttributes() THEN
75      FOR ind = 1 TO n.getAttributesCount()
76         LET node = n.getAttributeNodeItem(ind)
77         CALL Count(node)
78       END FOR
79     END IF
80   END IF
81 END FUNCTION
82
83 FUNCTION ExitHelp()
84   DISPLAY "DomCount <xml>"
85   EXIT PROGRAM
86 END FUNCTION

Back to the top