Navigating with XTreeCursor

Use the XTreeCursor interface to view the data.

Suppose the sequence that results from evaluating an XPath or XQuery expression or an XSLT stylesheet contains nodes. You will find it very convenient to access the contents of those nodes by applying further XPath or XQuery expressions to those nodes. However, we might also choose to navigate through the tree structure associated with a node directly through the XML API.

Tasks

• If the result of calling the XItemView.isAtomic() method is false-that is, the context item is a node-the application can call the XItemView.getXTreeCursor() method to gain direct access to the tree containing the node.

  The XSequenceCursor interface extends XItemView, so calling the XSequenceCursor.getXTreeCursor() method returns an instance of the XTreeCursor interface that we can use to access the node on which the instance of the XSequenceCursor interface is positioned.

• The XTreeCursor interface also extends the XItemView interface; therefore, we can use the methods inherited from the XItemView interface to access information about the node on which your instance of the XTreeCursor interface is currently positioned.

  In particular, we can use the XTreeCursor.getXTreeCursor() method to create another instance of the XTreeCursor interface we can use to navigate through the tree independently of the instance of the XTreeCursor interface from which it was created.

Example

The following example shows how we can use the methods on the XTreeCursor interface to navigate through the tree containing your XML data.

/* Contents of library.xml

<library>
  <book title='Ulysses'><author><first>James</first><last>Joyce</last></author></book>
  <book title='Ada'><author><first>Vladimir</first><last>Nabokov</last></author></book>
</library>
*/

XItemFactory factory = XFactory.newInstance().getItemFactory();
XItemView item = factory.item(new StreamSource("library.xml"));

// 'tree' is initially positioned at the same node as
// 'item' - that is, the document node of the input
XTreeCursor tree = item.getTreeCursor();

// Position tree cursor to "library" element
tree.toFirstChild();

// Position tree cursor to white-space text node
tree.toFirstChild();

// Position to first "book" element
tree.toNextSibling();

// Position to white-space text node
tree.toNextSibling();

// Position to second "book" element
tree.toNextSibling();

// Create a second instance of XTreeCursor initially
// positioned at the same node as 'tree' - that is, the
// second "book" element
XTreeCursor secondBook = tree.getTreeCursor();

// Position 'tree' to "library" element
tree.toParent();

// Position 'secondBook' to "title" attribute
secondBook.toFirstAttribute();

The following example navigates through all the nodes in a tree in a depth-first fashion.

XItemFactory factory = XFactory.newInstance().getItemFactory();
XItemView item = factory.item(new StreamSource("library.xml"));

XTreeCursor tree = item.getTreeCursor();
boolean hasMoreNodes = true;

do {
    // Process current node

    if (tree.toFirstAttribute()) {
        do {
            // Process attributes
        } while (tree.toNextAttribute());
        tree.toParent();
    }

    if (tree.toFirstNamespace()) {
        do {
            // Process namespaces
        } while (tree.toFirstNamespace());
        tree.toParent();
    }

    boolean foundNext = false;

    // If the current node has a child, visit it next
    // If there's no child, go to the next sibling
    if (tree.toFirstChild() || tree.toNextSibling()) {
        foundNext = true;

    // If there's no child and no sibling, find an
    // ancestor's sibling instead.
    } else {
        do {
            hasMoreNodes = tree.toParent();
            if (hasMoreNodes) {
                foundNext = tree.toNextSibling();
            }
        } while (hasMoreNodes && !foundNext);
    }
} while (hasMoreNodes);