XML cursors are a way to navigate through an XML instance document. Once you load an XML document, you can create a cursor to represent a specific place in the XML. Because you can use a cursor with or without a schema corresponding to the XML, cursors are an ideal way to handle XML without a schema.
With an XML cursor, you can:
When you're finished using a cursor, your code should call its dispose method.
With an XML instance document bound to XmlObject (or a type inheriting from it), you create a new cursor by calling the newCursor method. The XmlCursor interface represents a cursor. From a cursor standpoint, an XML document is a collection of tokens that represent the kinds of things that can appear in XML. These include attributes, the start and end of elements, comments, and so on. Each piece of information in XML is represented by a token type.
Note: For a more complete description of XML tokens, see Understanding XML Tokens.
For example, the following code loads the XML instance described above from a File object, then creates a new cursor. The toFirstChild takes the cursor to the start tag of the batchWidgetOrder document element. The code then prints the type for the token at the cursor's location, along with the XML the cursor represents—in other words, Token type: START / and the batchWidgetOrderElement and its contents.
public static void insertCursor(File orderFile) throws Exception
{
BatchWidgetOrderDocument xmlDoc = BatchWidgetOrderDocument.Factory.parse(orderFile);
XmlCursor orderCursor = xmlDoc.newCursor();
orderCursor.toFirstChild();
System.out.println("Token type: " + orderCursor.currentTokenType() +
" / " + orderCursor.xmlText());
}
Note: The XmlCursor interface provides many methods you can use to put a cursor where you want it. For a list of those methods, see XmlCursor Interface.
The XmlCursor interface provides several methods you can use to add elements and attributes to XML.
One way to add new XML is with the beginElement method. This method is designed to insert a new element at the cursor's location, and do it so the cursor ends up between the new element's START and END tokens. From this position, you can insert attributes (they're automatically placed in the start tag, where they belong) and insert a value. Here's an example:
// Create a new chunk of XML.
XmlObject newXml = XmlObject.Factory.newInstance();
/*
* Insert a new cursor and move it to the first START token (where the
* XML actually begins.
*/
XmlCursor cursor = newXml.newCursor();
cursor.toNextToken();
// Begin a new item element whose namespace URI is "http://openuri.org".
cursor.beginElement("item", "http://openuri.org/");
// Insert an ID attribute on the item element, along with an attribute value.
cursor.insertAttributeWithValue("id", "4056404");
// Insert "bicycle" as an element value.
cursor.insertChars("bicycle");
cursor.dispose();
This example results in something like the following:
<ns1:item id="4056404" xmlns:ns1="http://openuri.org/">bicycle</ns1:item>
When you want to move a cursor around, but want to keep track of a former location, you can use the XmlCursor interface's push and pop methods. The push method pushes the cursor's current location onto a stack of locations maintained for that particular cursor; the pop method removes the location from the top of the stack and moves the cursor to that location.
For example, consider the following <employee> element, used in the example below.
<employee> <name>Gladys Kravitz</name> <address location="home"> <street>1313 Mockingbird Lane</street> <city>Seattle</city> <state>WA</state> <zip>98115</zip> </address> <address location="work"> <street>2011 152nd Avenue NE</street> <city>Redmond</city> <state>WA</state> <zip>98052</zip> </address> <phone location="work">(425) 555-6897</phone> <phone location="home">(206) 555-6594</phone> <phone location="mobile">(206) 555-7894</phone> </employee>
The following Java code illustrates how you can use push and pop to put the cursor back to a saved location after a bit of traveling.
/**
* Pass to the trySelectPath method an XmlObject instance that contains
* the XML above.
*/
public void trySelectPath(XmlObject xml)
{
/*
* Inserts the cursor at the STARTDOC token (the very beginning,
* before any elements).
*/
XmlCursor cursor = xml.newCursor();
// Moves the cursor to just before <employee>
cursor.toFirstChild();
// Pushes the cursor's current location onto the stack.
cursor.push();
// Moves the cursor to just before the "work" <phone> element.
cursor.toChild(2);
// Moves the cursor to just before the "home" <phone> element.
cursor.toNextSibling();
// Moves the cursor back to just before <employee>
cursor.pop();
}
Of course, you can call push and pop multiple times. Each new call to the push method pushes the current location onto the stack. As you call the pop method, you're always getting what's on top of the stack. So if you called push three times before calling pop — 1, 2, 3 — calling pop three times would get those locations in reverse order — 3, 2, 1.
The push and pop methods can be handy as an alternative to creating new cursors that are designed simply to mark a particular location while you move another cursor around. The resources required to maintain a location stack through push and pop are far less than those needed by cursors.
When you're through with a cursor, your code should call its dispose method to indicate that it's no longer needed.