XDNode

An XDNode is a single element of an XML tree. A complete document is a tree of XDNodes. The XDNode class and tree are designed for fast parsing and searching, and for easy manipulation in an application. Methods are available to convert between XDNode trees and standard JDOM trees. All server operations are performed on trees of XDNodes.

Each XDNode represents one "element" of the XML document, including the attributes, comments, and processing instructions that apply to it. Method calls are provided to get and set this information, along with the node's name, value, relationships with other nodes in the tree, and so on.

A document of type XML encapsulates a tree of XDNodes. Each XDNode is the root of a subtree or is a leaf. The usual task of a business agent is to create one or more output XML documents in the form of XDNode trees, and add each to an XDDocument. The base output XDDocument is provided to the business agent, and the business agent can create one or more siblings if multiple output documents are to be emitted.

The XDNode class provides a set of standard tree manipulation methods, all of which are explained in the associated Javadoc. Key methods are listed in the tables below. When considering a node, the XML has three parts: name, value, and attributes.

Important: Do not allow a node to be in two trees at the same time, or a tree to be in two documents at the same time.

The standard search of nodes is down-right recursive. Some search calls have the appendix "AsRoot", such as, findByNameAsRoot(). These methods treat the nodes in which they are called as a subtree, and do not search to the right on their root node.

Method	Returns
getParent()	Node A
getFirstChild()	Node E
getName	"C"
getRight	Node D
getValue()	"Cvalue"
getAttribute("ATR")	"iWay"
getAttribute("x")	Null

Method	Description
findByFullNameAsRoot	Locates a node by the child name below the current node.
findByName findByNameAsRoot	Locates a descendent (following) node of a specified name.
findByNameEnd findByNameEndAsRoot	Locates a node with a name that ends with the given sequence.
findByNameIC findByNameICAsRoot	Locates a node by name, case insensitive.
findByValue findByValueAsRoot	Locates a descendent (following) node with a specified value.
findChild	Locates a node by name that is a direct descendent of this node.
getFirstChild/getLastChild	Returns the associated child of the node.
getParent/getLeft/getRight	Returns an associated node.
setLastChild	Adds a node as the last child of a parent node.
snipNode	Eliminates the node from the tree. Optionally, this method can replace the snipped node with a new node. The nodes may be the roots of trees.
swap	Swaps two nodes in the tree.
XDNode.newNode	Static constructor for a node. Faster than creating a new XDNode.

Method	Description
appendValue	Appends the passed sequence to the current value of the node.
getAttribute	Returns the value of the attribute associated with the key. If there is no such attribute, null is returned.
getName	Returns the name associated with the node.
getValue	Returns the value associated with the node. If no value can be found, null is returned. If a mapped value points into another part of the document, the XPATH is followed to the value.
setAttribute	Adds an attribute to the node or deletes an attribute.
setProcessingInstruction	Adds one processing instruction to the node.
setValue/setName	Sets the appropriate name or value data.
toflat	Flattens this node and its children to a string.
toString	Flattens the node in the document to a string.

Method	Description
findAllByAttributeValue	Locates all nodes with a specific attribute of a specific value.
findAllByFullName	Locates all nodes meeting a path specification.
findAllByName	Locates all nodes with the passed name.
findAllChildrenByName	Locates all nodes of the given name that are children of a specific node.
getAllChildren	Returns all children of the node.
getComments	Returns a list of any comments that apply to this node.
getProcessingInstructions	Returns a list of processing instructions applicable to this node.

Namespace Support

The XDNode API has been augmented with namespace support. The old constructor creates an element without a namespace or prefix.

XDNode level1Element = new XDNode("elemName");
	// level1Element.getNamespaceURI() returns null
	// level1Element.getLocalName() return null
	// level1Element.getName() returns "elemName"

A new constructor creates a namespace-aware element. The application is responsible to create the XML namespace declaration explicitly on the node or on one of its ancestors.

XDNode level2Element = new XDNode("http://ibi.com", "elemName", "ns:elemName");
              		level2Element.setAttribute("http://www.w3.org/2000/xmlns/", "ns", "xmlns:ns", "http://ibi.com");
	// level2Element.getNamespaceURI() returns "http://ibi.com"
	// level2Element.getLocalName() return "elemName"
	// level2Element.getName() returns "ns:elemName"

The second and third argument of the constructor overlap somewhat, but they were chosen to match the arguments provided by a SAX2 parser. Notice there is no verification of the namespace prefix "ns". As you can see from the example, the XDNode is allowed to be inconsistent momentarily. An xmlns declaration must exist for the prefix on this node or an ancestor, otherwise the node will serialize to an invalid XML document. An xmlns declaration is just a regular attribute with the required namespace and qualified name. The DOM handles namespaces exactly same way.

The numerous finder methods in XDNode are not all namespace-aware, although many have been augmented for this use. Fortunately, XPATHContainer, the handler of xpath within the server, fully supports namespaces right away.

Functions using namespaces refer to them through a namespace provider, which maintains maps of alias to URI.

Use of namespaces in the XPATH function is described in the Runtime Functions documentation.