Using XML Cursors

In the preceding example you may have noticed the XmlCursor interface. In addition to providing a way to execute XQuery expression, an XML cursors offers a fine-grained model for manipulating data. The XML cursor API, analogous to the DOM's object API, is simply a way to point at a particular piece of data. So, just like a cursor helps navigate through a word processing document, the XML cursor defines a location in XML where you can perform actions on the selected XML.

Cursors are ideal for moving through an XML document when there's no schema available. Once you've got the cursor at the location you're interested in, you can perform a variety of operations with it. For example, you can set and get values, insert and remove fragments of XML, copy fragments of XML to other parts of the document, and make other fine-grained changes to the XML document.

The following example uses an XML cursor to navigate to the customer element's name child element.

PurchaseOrderDocument doc = 
    PurchaseOrderDocument.Factory.parse(po);

XmlCursor cursor = doc.newCursor();
cursor.toFirstContentToken();
cursor.toFirstChildElement();
cursor.toFirstChildElement();
System.out.println(cursor.getText());

cursor.dispose();

What's happening here? As with the earlier example, the code loads the XML from a File object. After loading the document, the code creates a cursor at its beginning. Moving the cursor a few times takes it to the nested name element. Once there, the getText method retrieves the element's value.

This is just an introduction to XML cursors. For more information about using cursors, see Navigating XML with Cursors.

• XMLBeans provides intuitive ways to handle XML, particularly if you're starting with schema. If you're accessing XML that's based on a schema, you'll probably find it most efficient to access the XML through generated types specific to the schema. To do this, you begin by compiling the schema to generate interfaces. For more information on using XMLBeans types generated by compiling schema, see Java Types Generated From User-Derived Schema Types and Methods for Types Generated From Schema.
• You might be interested in reading more about the type system on which XMLBeans is based, particularly if you're using types generated from schema. XMLBeans provides a hierarchical system of types that mirror what you find in the XML schema specification itself. If you're working with schema, you might find it helps to understand how these types work. For more information, see XMLBeans Support for Built-In Schema Types and Introduction to Schema Type Signatures.
• XMLBeans provides access to XML through XQuery, which borrows path syntax from XPath. With XQuery, you can specify specific fragments of XML data with or without schema. To learn more about using XQuery and XPath in XMLBeans, see Selecting XML with XQuery and XPath.
• You can use the XmlCursor interface for fine-grained navigation and manipulation of XML. For more information, see Navigating XML with Cursors.

    
        Fred Jones
        
            900 Aurora Ave.
            Seattle
            WA
            98115
        
        
            2011 152nd Avenue NE
            Redmond
            WA
            98052
        
        (425)555-5665
        (206)555-5555
        (206)555-4321
    

String queryExpression =
    "declare namespace xq='http://openuri.org/selectPath'" +
    "$this/xq:employees/xq:employee/xq:phone[contains(., '(206)')]"

/* 
 * Retrieve the matching phone elements and assign the results to the corresponding
 * generated type.
 */
PhoneType[] phones = (PhoneType[])empDoc.selectPath(queryExpression);
/*
 * Loop through the results, printing the value of the phone element.
 */
for (int i = 0; i < phones.length; i++)
{
    System.out.println(phones[i].stringValue());
}  

public void printZipsAndWorkPhones(XmlObject xml)
{
    // Declare the namespace that will be used.
    String xqNamespace = 
        "declare namespace xq='http://openuri.org/selectPath'";

    // Insert a cursor and move it to the first element.
    XmlCursor cursor = xml.newCursor();
    cursor.toFirstChild();
    /* 
     * Save the cursor's current location by pushing it 
     * onto a stack of saved locations.
     */
    cursor.push();
    // Query for zip elements.
    cursor.selectPath(xqNamespace + "$this//xq:zip");
    /* 
     * Loop through the list of selections, getting the value of 
     * each element.
     */
    while (cursor.toNextSelection())
    {
        System.out.println(cursor.getTextValue());
    }
    // Pop the saved location off the stack.
    cursor.pop();
    // Query again from the top, this time for work phone numbers.
    cursor.selectPath(xqNamespace + "$this//xq:phone[@location='work']");
    /* 
     * Move the cursor to the first selection, them print that element's
     * value.
     */
    cursor.toNextSelection();
    System.out.println(cursor.getTextValue());
    // Dispose of the cursor.
    cursor.dispose();
}