223 lines
11 KiB
HTML
223 lines
11 KiB
HTML
|
<!doctype HTML public "-//W3C//DTD HTML 4.0 Frameset//EN">
|
|||
|
|
|
|||
|
|
<!-- Copyright 2004 The Apache Software Foundation
|
|||
|
|
|
|||
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|||
|
|
you may not use this file except in compliance with the License.
|
|||
|
|
You may obtain a copy of the License at
|
|||
|
|
|
|||
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|||
|
|
|
|||
|
|
Unless required by applicable law or agreed to in writing, software
|
|||
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|||
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|||
|
|
See the License for the specific language governing permissions and
|
|||
|
|
limitations under the License. -->
|
|||
|
|
<html>
|
|||
|
|
<head>
|
|||
|
|
<!-- InstanceBeginEditable name="doctitle" -->
|
|||
|
|
<title>Navigating XML with Cursors</title>
|
|||
|
|
<!-- InstanceEndEditable -->
|
|||
|
|
<!--(Meta)==========================================================-->
|
|||
|
|
|
|||
|
|
<meta http-equiv=Content-Type content="text/html; charset=$CHARSET;">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<!-- InstanceBeginEditable name="metatags" -->
|
|||
|
|
|
|||
|
|
<meta content="your name" name="author">
|
|||
|
|
<meta content="A description of the topic contents." name="description">
|
|||
|
|
<meta content="keywords to help in searches" name="keywords">
|
|||
|
|
<meta content="10/25/02" name="date last modified">
|
|||
|
|
<!-- InstanceEndEditable -->
|
|||
|
|
|
|||
|
|
<!--(Links)=========================================================-->
|
|||
|
|
<!-- InstanceBeginEditable name="head" -->
|
|||
|
|
<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
|
|||
|
|
<!-- InstanceEndEditable -->
|
|||
|
|
<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
|
|||
|
|
<a href="../../../core/index.html" id="index"></a>
|
|||
|
|
<script language="JavaScript" src="../../../core/topicInfo.js"></script>
|
|||
|
|
<script language="JavaScript" src="../../../core/CookieClass.js"></script>
|
|||
|
|
<script language="JavaScript" src="../../../core/displayContent.js"></script>
|
|||
|
|
</head>
|
|||
|
|
|
|||
|
|
<!--(Body)==========================================================-->
|
|||
|
|
<body>
|
|||
|
|
<script language="JavaScript">
|
|||
|
|
|
|||
|
|
</script>
|
|||
|
|
<!-- InstanceBeginEditable name="body" -->
|
|||
|
|
<h1> Navigating XML with Cursors </h1>
|
|||
|
|
<div id="topictext">
|
|||
|
|
<p>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.</p>
|
|||
|
|
<p>With an XML cursor, you can:</p>
|
|||
|
|
</div>
|
|||
|
|
<UL>
|
|||
|
|
<li>
|
|||
|
|
<div><a href="conUnderstandingXMLTokens.html">Use the token model</a> to move
|
|||
|
|
through XML in small increments, or in a manner similar to using a DOM-based
|
|||
|
|
model.</div>
|
|||
|
|
<LI>
|
|||
|
|
<DIV>Get and set values within the XML.</DIV>
|
|||
|
|
<LI>
|
|||
|
|
<DIV><a href="#adding_elements_attributes">Change the structure</a> of an
|
|||
|
|
XML document by inserting, removing, and moving elements and attributes.</DIV>
|
|||
|
|
<LI>
|
|||
|
|
<DIV><a href="conSelectingXMLwithXQueryPathXPath.html">Execute XQuery expressions</a>
|
|||
|
|
against the XML represented by the cursor.</DIV>
|
|||
|
|
<LI>
|
|||
|
|
<DIV><a href="conUsingBookmarksToAnnotateXML.html">Insert bookmarks</a> to
|
|||
|
|
mark locations in XML.</DIV>
|
|||
|
|
</UL>
|
|||
|
|
<P>When you're finished using a cursor, your code should call its <span class="langinline">dispose</span>
|
|||
|
|
method.</P>
|
|||
|
|
<h2>Creating and Moving a Cursor</h2>
|
|||
|
|
<P>With an XML instance document bound to <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlObject.html">XmlObject</a></span>
|
|||
|
|
(or a type inheriting from it), you create a new cursor by calling the <span class="langinline">newCursor</span>
|
|||
|
|
method. The <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlCursor.html">XmlCursor</a></span>
|
|||
|
|
interface represents a cursor. From a cursor standpoint, an XML document is
|
|||
|
|
a collection of <EM>tokens</EM> 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 <em>token type</em>.</P>
|
|||
|
|
<P class="notepara"><strong>Note:</strong> For a more complete description of
|
|||
|
|
XML tokens, see <a href="conUnderstandingXMLTokens.html">Understanding XML Tokens</a>.</P>
|
|||
|
|
<P>For example, the following code loads the XML instance described above
|
|||
|
|
from a <span class="langinline">File</span> object, then creates a new cursor.
|
|||
|
|
The <span class="langinline">toFirstChild</span> takes the cursor to the start
|
|||
|
|
tag of the <span class="langinline">batchWidgetOrder</span> document element.
|
|||
|
|
The code then prints the type for the token at the cursor's location, along
|
|||
|
|
with the XML the cursor represents<74>in other words, <span class="filepath">Token
|
|||
|
|
type: START /</span> and the <span class="filepath">batchWidgetOrderElement</span>
|
|||
|
|
and its contents.</P>
|
|||
|
|
<pre>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());
|
|||
|
|
}
|
|||
|
|
</pre>
|
|||
|
|
<p class="notepara"><STRONG>Note</STRONG>: The <span class="langinline">XmlCursor</span>
|
|||
|
|
interface provides many methods you can use to put a cursor where you want it.
|
|||
|
|
For a list of those methods, see <a href="../reference/org/apache/xmlbeans/XmlCursor.html">XmlCursor
|
|||
|
|
Interface</a>.</p>
|
|||
|
|
<h2><a name="adding_elements_attributes" id="adding_elements_attributes"></a>Adding
|
|||
|
|
Elements and Attributes</h2>
|
|||
|
|
<p>The <span class="langinline">XmlCursor</span> interface provides several methods
|
|||
|
|
you can use to add elements and attributes to XML. </p>
|
|||
|
|
<p>One way to add new XML is with the <span class="langinline">beginElement</span>
|
|||
|
|
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:</p>
|
|||
|
|
<pre>
|
|||
|
|
// 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();
|
|||
|
|
</pre>
|
|||
|
|
<p>This example results in something like the following:</p>
|
|||
|
|
<pre><ns1:item id="4056404" xmlns:ns1="http://openuri.org/">bicycle</ns1:item>
|
|||
|
|
</pre>
|
|||
|
|
<h2> Using Stored Cursor Locations with push() and pop()</h2>
|
|||
|
|
<div id="topictext">
|
|||
|
|
<p>When you want to move a cursor around, but want to keep track of a former
|
|||
|
|
location, you can use the <span class="langinline">XmlCursor</span> interface's
|
|||
|
|
<span class="langinline">push</span> and <span class="langinline">pop</span>
|
|||
|
|
methods. The <span class="langinline">push</span> method pushes the cursor's
|
|||
|
|
current location onto a stack of locations maintained for that particular
|
|||
|
|
cursor; the <span class="langinline">pop</span> method removes the location
|
|||
|
|
from the top of the stack and moves the cursor to that location.</p>
|
|||
|
|
<p>For example, consider the following <employee> element, used in the
|
|||
|
|
example below.</p>
|
|||
|
|
<pre>
|
|||
|
|
<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>
|
|||
|
|
</pre>
|
|||
|
|
<p>The following Java code illustrates how you can use <span class="langinline">push</span>
|
|||
|
|
and <span class="langinline">pop</span> to put the cursor back to a saved
|
|||
|
|
location after a bit of traveling.</p>
|
|||
|
|
<pre>
|
|||
|
|
/**
|
|||
|
|
* 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();
|
|||
|
|
}
|
|||
|
|
</pre>
|
|||
|
|
<p>Of course, you can call <span class="langinline">push</span> and <span class="langinline">pop</span>
|
|||
|
|
multiple times. Each new call to the <span class="langinline">push</span>
|
|||
|
|
method pushes the current location onto the stack. As you call the <span class="langinline">pop</span>
|
|||
|
|
method, you're always getting what's on top of the stack. So if you called
|
|||
|
|
<span class="langinline">push</span> three times before calling <span class="langinline">pop</span>
|
|||
|
|
— 1, 2, 3 — calling <span class="langinline">pop</span> three
|
|||
|
|
times would get those locations in reverse order — 3, 2, 1.</p>
|
|||
|
|
<p>The <span class="langinline">push</span> and <span class="langinline">pop</span>
|
|||
|
|
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 <span class="langinline">push</span>
|
|||
|
|
and <span class="langinline">pop</span> are far less than those needed by
|
|||
|
|
cursors. </p>
|
|||
|
|
<H1>Disposing of a Cursor</H1>
|
|||
|
|
<p>When you're through with a cursor, your code should call its <span class="langinline">dispose</span>
|
|||
|
|
method to indicate that it's no longer needed.</p>
|
|||
|
|
<p class="relatedtopics">Related Topics</p>
|
|||
|
|
<p><a href="conUnderstandingXMLTokens.html">Understanding XML Tokens</a></p>
|
|||
|
|
<p><a href="conGettingStartedwithXMLBeans.html">Getting Started with XMLBeans</a></p>
|
|||
|
|
</div>
|
|||
|
|
<!-- InstanceEndEditable -->
|
|||
|
|
<script language="JavaScript">
|
|||
|
|
|
|||
|
|
</script>
|
|||
|
|
</body>
|
|||
|
|
</html>
|