3. Document Object Model (XML) Level 1

3.2 Descriptions of the basic XML objects

This section describes the XML specialization of the Node objects. used throughout the DOM.

Interface XMLNode

The XML implementation of the Node interface adds some methods that are needed to manipulate specific features of XML documents

IDL Definition

interface XMLNode {
  Node                getParentXMLNode(in boolean expandEntities);
  NodeIterator        getChildXMLNodes(in boolean expandEntities);
  boolean             hasChildXMLNodes(in boolean expandEntities);
  Node                getFirstXMLChild(in boolean expandEntities);
  Node                getPreviousXMLSibling(in boolean expandEntities);
  Node                getNextXMLSibling(in boolean expandEntities);
  EntityReference     getEntityReference();
  EntityDeclaration   getEntityDeclaration();
};

Method getParentXMLNode()

Returns the parent of the given Node instance. If this node is the root of the document object tree, or if this node is not part of a document tree, null is returned.
Parameters
expandEntities

TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated


Return Values
Node

The parent of the node.


Exceptions
This method throws no exceptions.

Method getChildXMLNodes()

Returns a NodeIterator object that will enumerate all children of this node. If there are no children, an iterator that will return no nodes is returned. The content of the returned NodeIterator is "live" in the sense that changes to the children of the Node object that it was created from will be immediately reflected in the nodes returned by the iterator; it is not a static snapshot of the content of the Node. Similarly, changes made to the nodes returned by the iterator will be immediately reflected in the tree, including the set of children of the Node that the NodeIterator was created from.
Parameters
expandEntities

TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated


Return Values
NodeIterator

An iterator through the children of the node.


Exceptions
This method throws no exceptions.

Method hasChildXMLNodes()

Returns true if the node has any children, false if the node has no children at all. This method exists both for convenience as well as to allow implementations to be able to bypass object allocation, which may be required for implementing getChildNodes().
Parameters
expandEntities

TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated


Return Values
boolean

True if the node has children.


Exceptions
This method throws no exceptions.

Method getFirstXMLChild()

Returns the first child of a node. If there is no such node, null is returned.
Parameters
expandEntities

TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated


Return Values
Node

The first child of the node, or null.


Exceptions
This method throws no exceptions.

Method getPreviousXMLSibling()

Returns the node immediately preceding the current node in a breadth-first traversal of the tree. If there is no such node, null is returned.
Parameters
expandEntities

TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated


Return Values
Node

The the node immediately preceeding, or null.


Exceptions
This method throws no exceptions.

Method getNextXMLSibling()

Returns the node immediately following the current node in a breadth-first traversal of the tree. If there is no such node, null is returned.
Parameters
expandEntities

TRUE if the view of the tree with parsed entities expanded should be navigated, FALSE if the view without parsed entities expanded should be navigated


Return Values
Node

The node immediately following, or null.


Exceptions
This method throws no exceptions.

Method getEntityReference()

When navigating XML trees with expandedEntities set to TRUE, the DOM programmer will on occasion get Nodes returned that are part of the expansion of an entity rather than actual nodes in the tree. This method returns the entity reference that generated a particular node, or NULL if it was not part of an entity reference expansion.
Parameters
This method has no parameters.

Return Values
EntityReference

The entity reference whose expansion yields a given node, or NULL if the node is not part of an entity expansion.


Exceptions
This method throws no exceptions.

Method getEntityDeclaration()

When navigating XML trees with expandedEntities set to TRUE, the DOM programmer will on occasion get Nodes returned that are part of the expansion of an entity rather than actual nodes in the tree. This method returns the declaration for the entity reference that generated a particular node, or NULL if it was not part of an entity reference expansion.
Parameters
This method has no parameters.

Return Values
EntityDeclaration

The entity declaration for a reference whose expansion yields a given node, or NULL if the node is not part of an entity expansion.


Exceptions
This method throws no exceptions.