| <!doctype HTML public "-//W3C//DTD HTML 4.0 Frameset//EN"> |
| |
| <html> |
| <head> |
| <!-- InstanceBeginEditable name="doctitle" --> |
| <title>Selecting XML with XQuery and XPath</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> Selecting XML with XPath</h1> |
| <div id="topictext"> |
| <p>You can use XPath to retrieve specific pieces of XML XPath provide a syntax for specifying |
| which elements and attributes you're interested in. |
| <h2>Using the selectPath Method</h2> |
| </div> |
| <div> |
| <p>When you use XPath with the <span class="langinline">selectPath</span> |
| method, the value returned is an array of values from the <em>current document</em>.</p> |
| <h3>Calling from XmlObject</h3> |
| <p>When called from <span class="langinline">XmlObject</span> (or a type that |
| inherits from it), this method returns an array of objects. If the expression |
| is executed against types generated from schema, then the type for the returned |
| array is one of the Java types corresponding to the schema. </p> |
| <p>For example, imagine you have the following XML containing employee information. |
| You've compiled the schema describing this XML and the types generated from |
| schema are available to your code.</p> |
| <pre> |
| <xq:employees xmlns:xq="http://openuri.org/selectPath"> |
| <xq:employee> |
| <xq:name>Fred Jones</xq:name> |
| <xq:address location="home"> |
| <xq:street>900 Aurora Ave.</xq:street> |
| <xq:city>Seattle</xq:city> |
| <xq:state>WA</xq:state> |
| <xq:zip>98115</xq:zip> |
| </xq:address> |
| <xq:address location="work"> |
| <xq:street>2011 152nd Avenue NE</xq:street> |
| <xq:city>Redmond</xq:city> |
| <xq:state>WA</xq:state> |
| <xq:zip>98052</xq:zip> |
| </xq:address> |
| <xq:phone location="work">(425)555-5665</xq:phone> |
| <xq:phone location="home">(206)555-5555</xq:phone> |
| <xq:phone location="mobile">(206)555-4321</xq:phone> |
| </xq:employee> |
| </xq:employees> |
| </pre> |
| If you wanted to find the phone numbers whose area code was 206, you could capture |
| the XPath expression in this way: |
| <pre> |
| String queryExpression = |
| "declare namespace xq='http://openuri.org/selectPath'" + |
| "$this/xq:employees/xq:employee/xq:phone[contains(., '(206)')]" |
| </pre> |
| <p>Notice in the query expression that the variable <span class="langinline">$this</span> |
| represents the current context node (the <span class="langinline">XmlObject</span> |
| that you are querying from). In this example you are querying from the document |
| level <span class="langinline">XmlObject</span>.</p> |
| <p>You could then print the results with code such as the following:</p> |
| <pre> |
| /* |
| * 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()); |
| } </pre> |
| |
| <h3>Calling from XmlCursor</h3> |
| <p>When called from an <span class="langinline">XmlCursor</span> instance, the |
| <span class="langinline">selectPath</span> method retrieves a list of selections, |
| or locations in the XML. The selections are remembered by the cursor instance. |
| You can use methods such as <span class="langinline">toNextSelection</span> |
| to navigate among them.</p> |
| <div> |
| <p>The <span class="langinline">selectPath</span> method takes an XPath expression. |
| If the expression returns any results, each of those results is added as |
| a selection to the cursor's list of selections. You can move through these |
| selections in the way you might use <span class="langinline">java.util.Iterator</span> |
| methods to move through a collection.</p> |
| <p> For example, for a path such as <span class="langinline">$this/employees/employee</span>, |
| the results would include a selection for each employee element found by |
| the expression. Note that the variable <span class="langinline">$this</span> |
| is always bound to the current context node, which in this example is the |
| document. After calling the <span class="langinline">selectPath</span> method, |
| you would use various "selection"-related methods to work with |
| the results. These methods include:</p> |
| </div> |
| <ul> |
| <li> |
| <div><span class="langinline">getSelectionCount() </span>to retrieve the |
| number of selections resulting from the query.</div> |
| </li> |
| <li> |
| <div> <span class="langinline">toNextSelection()</span> to move the cursor |
| to the next selection in the list (such as to the one pointing at the |
| next employee element found).</div> |
| </li> |
| <li> |
| <div> <span class="langinline">toSelection(int)</span> to move the cursor |
| to the selection at the specified index (such as to the third employee |
| element in the selection).</div> |
| </li> |
| <li> |
| <div> <span class="langinline">hasNextSelection()</span> to find out if |
| there are more selections after the cursor's current position.</div> |
| </li> |
| <li> |
| <div><span class="langinline"> clearSelections()</span> clears the selections |
| from the current cursor. This doesn't modify the document (in other words, |
| it doesn't delete the selected XML); it merely clears the selection list |
| so that the cursor is no longer keeping track of those positions.</div> |
| </li> |
| </ul> |
| <div> |
| <p>The following example shows how you might use <span class="langinline">selectPath</span>, |
| in combination with the <span class="langinline">push</span> and <span class="langinline">pop</span> |
| methods, to maneuver through XML, retrieving specific values. </p> |
| <pre> |
| 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(); |
| } |
| </pre> |
| <p>Using selections is somewhat like tracking the locations of multiple cursors |
| with a single cursor. This becomes especially clear when you remove the |
| XML associated with a selection. When you do so the selection itself remains |
| at the location where the removed XML was, but now the selection's location |
| is immediately before the XML that was after the XML you removed. In other |
| words, removing XML created a kind of vacuum that was filled by the XML |
| after it, which shifted up into the space — up into position immediately |
| after the selection location. This is exactly the same as if the selection |
| had been another cursor.</p> |
| <p>Finally, when using selections keep in mind that the list of selections |
| is in a sense "live". The cursor you're working with is keeping |
| track of the selections in the list. In other words, be sure to call the |
| <span class="langinline">clearSelections</span> method when you're finished |
| with the selections, just as you should call the <span class="langinline">XmlCursor.dispose()</span> |
| method when you're finished using the cursor.</p> |
| </div> |
| <h2>Related Topics</h2> |
| </div> |
| <p><a href="conGettingStartedwithXMLBeans.html">Getting Started with XMLBeans</a></p> |
| <!-- InstanceEndEditable --> |
| <script language="JavaScript"> |
| |
| </script> |
| </body> |
| </html> |