5543eb9de8
git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1824563 13f79535-47bb-0310-9956-ffa450edef68
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>
|