Back to Contents

The DomNode class

Summary:

See also: The Genero Web Services XML Library

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

Methods

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.
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.
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.
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.
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.
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.
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.
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.

If the namespaces list is NULL, the prefixes and namespaces defined in the document itself are used if available.

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: 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