|
1 <?xml version="1.0" encoding="UTF-8"?> |
|
2 <!-- |
|
3 Copyright 2003-2005 Sun Microsystems, Inc. All Rights Reserved. |
|
4 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
5 |
|
6 This code is free software; you can redistribute it and/or modify it |
|
7 under the terms of the GNU General Public License version 2 only, as |
|
8 published by the Free Software Foundation. Sun designates this |
|
9 particular file as subject to the "Classpath" exception as provided |
|
10 by Sun in the LICENSE file that accompanied this code. |
|
11 |
|
12 This code is distributed in the hope that it will be useful, but WITHOUT |
|
13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
15 version 2 for more details (a copy is included in the LICENSE file that |
|
16 accompanied this code). |
|
17 |
|
18 You should have received a copy of the GNU General Public License version |
|
19 2 along with this work; if not, write to the Free Software Foundation, |
|
20 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
21 |
|
22 Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
23 CA 95054 USA or visit www.sun.com if you need additional information or |
|
24 have any questions. |
|
25 --> |
|
26 |
|
27 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
|
28 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
|
29 <html xmlns="http://www.w3.org/1999/xhtml"> |
|
30 <head> |
|
31 <title>javax.xml.xpath</title> |
|
32 <meta name="@author" content="mailto:Ben@galbraiths.org" /> |
|
33 <meta name="@author" content="mailto:Norman.Walsh@Sun.com" /> |
|
34 <meta name="@author" content="mailto:Jeff.Suttor@Sun.com" /> |
|
35 <meta name="@version" content="$Revision: 1.3 $, $Date: 2005/11/03 19:34:17 $" /> |
|
36 <meta name="@see" content="http://www.w3.org/TR/xpath" /> |
|
37 <meta name="@since" content="1.5" /> |
|
38 </head> |
|
39 |
|
40 <body> |
|
41 |
|
42 <p>This package provides an <em>object-model neutral</em> API for the |
|
43 evaluation of XPath expressions and access to the evaluation |
|
44 environment. |
|
45 </p> |
|
46 |
|
47 <p>The following XML standards apply:</p> |
|
48 |
|
49 <ul> |
|
50 <li><a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li> |
|
51 </ul> |
|
52 |
|
53 <hr /> |
|
54 |
|
55 <h2>XPath Overview</h2> |
|
56 |
|
57 <p>The XPath language provides a simple, concise syntax for selecting |
|
58 nodes from an XML document. XPath also provides rules for converting a |
|
59 node in an XML document object model (DOM) tree to a boolean, double, |
|
60 or string value. XPath is a W3C-defined language and an official W3C |
|
61 recommendation; the W3C hosts the XML Path Language (XPath) Version |
|
62 1.0 specification. |
|
63 </p> |
|
64 |
|
65 <p>XPath started in life in 1999 as a supplement to the XSLT and |
|
66 XPointer languages, but has more recently become popular as a |
|
67 stand-alone language, as a single XPath expression can be used to |
|
68 replace many lines of DOM API code. |
|
69 </p> |
|
70 |
|
71 <h3>XPath Expressions</h3> |
|
72 |
|
73 <p>An XPath <em>expression</em> is composed of a <em>location |
|
74 path</em> and one or more optional <em>predicates</em>. Expressions |
|
75 may also include XPath variables. |
|
76 </p> |
|
77 |
|
78 <p>The following is an example of a simple XPath expression:</p> |
|
79 |
|
80 <pre> |
|
81 /foo/bar |
|
82 </pre> |
|
83 |
|
84 <p>This example would select the <code><bar></code> element in |
|
85 an XML document such as the following:</p> |
|
86 |
|
87 <pre> |
|
88 <foo> |
|
89 <bar/> |
|
90 </foo> |
|
91 </pre> |
|
92 |
|
93 <p>The expression <code>/foo/bar</code> is an example of a location |
|
94 path. While XPath location paths resemble Unix-style file system |
|
95 paths, an important distinction is that XPath expressions return |
|
96 <em>all</em> nodes that match the expression. Thus, all three |
|
97 <code><bar></code> elements in the following document would be |
|
98 selected by the <code>/foo/bar</code> expression:</p> |
|
99 |
|
100 <pre> |
|
101 <foo> |
|
102 <bar/> |
|
103 <bar/> |
|
104 <bar/> |
|
105 </foo> |
|
106 </pre> |
|
107 |
|
108 <p>A special location path operator, <code>//</code>, selects nodes at |
|
109 any depth in an XML document. The following example selects all |
|
110 <code><bar></code> elements regardless of their location in a |
|
111 document:</p> |
|
112 |
|
113 <pre> |
|
114 //bar |
|
115 </pre> |
|
116 |
|
117 <p>A wildcard operator, *, causes all element nodes to be selected. |
|
118 The following example selects all children elements of a |
|
119 <code><foo></code> element:</p> |
|
120 |
|
121 <pre> |
|
122 /foo/* |
|
123 </pre> |
|
124 |
|
125 <p>In addition to element nodes, XPath location paths may also address |
|
126 attribute nodes, text nodes, comment nodes, and processing instruction |
|
127 nodes. The following table gives examples of location paths for each |
|
128 of these node types:</p> |
|
129 |
|
130 <table border="1"> |
|
131 <tr> |
|
132 <td>Location Path</td> |
|
133 <td>Description</td> |
|
134 </tr> |
|
135 <tr> |
|
136 <td> |
|
137 <code>/foo/bar/<strong>@id</strong></code> |
|
138 </td> |
|
139 <td>Selects the attribute <code>id</code> of the <code><bar></code> element |
|
140 </td> |
|
141 </tr> |
|
142 <tr> |
|
143 <td><code>/foo/bar/<strong>text()</strong></code> |
|
144 </td> |
|
145 <td>Selects the text nodes of the <code><bar></code> element. No |
|
146 distinction is made between escaped and non-escaped character data. |
|
147 </td> |
|
148 </tr> |
|
149 <tr> |
|
150 <td><code>/foo/bar/<strong>comment()</strong></code> |
|
151 </td> |
|
152 <td>Selects all comment nodes contained in the <code><bar></code> element. |
|
153 </td> |
|
154 </tr> |
|
155 <tr> |
|
156 <td><code>/foo/bar/<strong>processing-instruction()</strong></code> |
|
157 </td> |
|
158 <td>Selects all processing-instruction nodes contained in the |
|
159 <code><bar></code> element. |
|
160 </td> |
|
161 </tr> |
|
162 </table> |
|
163 |
|
164 <p>Predicates allow for refining the nodes selected by an XPath |
|
165 location path. Predicates are of the form |
|
166 <code>[<em>expression</em>]</code>. The following example selects all |
|
167 <code><foo></code> elements that contain an <code>include</code> |
|
168 attribute with the value of <code>true</code>:</p> |
|
169 |
|
170 <pre> |
|
171 //foo[@include='true'] |
|
172 </pre> |
|
173 |
|
174 <p>Predicates may be appended to each other to further refine an |
|
175 expression, such as:</p> |
|
176 |
|
177 <pre> |
|
178 //foo[@include='true'][@mode='bar'] |
|
179 </pre> |
|
180 |
|
181 <h3>Using the XPath API</h3> |
|
182 |
|
183 <p> |
|
184 The following example demonstrates using the XPath API to select one |
|
185 or more nodes from an XML document:</p> |
|
186 |
|
187 <pre> |
|
188 XPath xpath = XPathFactory.newInstance().newXPath(); |
|
189 String expression = "/widgets/widget"; |
|
190 InputSource inputSource = new InputSource("widgets.xml"); |
|
191 NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET); |
|
192 </pre> |
|
193 |
|
194 <h3>XPath Expressions and Types</h3> |
|
195 |
|
196 <p>While XPath expressions select nodes in the XML document, the XPath |
|
197 API allows the selected nodes to be coalesced into one of the |
|
198 following other data types:</p> |
|
199 |
|
200 <ul> |
|
201 <li><code>Boolean</code></li> |
|
202 <li><code>Number</code></li> |
|
203 <li><code>String</code></li> |
|
204 </ul> |
|
205 |
|
206 <p>The desired return type is specified by a {@link |
|
207 javax.xml.namespace.QName} parameter in method call used to evaluate |
|
208 the expression, which is either a call to |
|
209 <code>XPathExpression.evalute(...)</code> or to one of the |
|
210 <code>XPath.evaluate(...)</code> convenience methods. The allowed |
|
211 QName values are specified as constants in the {@link |
|
212 javax.xml.xpath.XPathConstants} class; they are:</p> |
|
213 |
|
214 <ul> |
|
215 <li>{@link javax.xml.xpath.XPathConstants#NODESET}</li> |
|
216 <li>{@link javax.xml.xpath.XPathConstants#NODE}</li> |
|
217 <li>{@link javax.xml.xpath.XPathConstants#STRING}</li> |
|
218 <li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li> |
|
219 <li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li> |
|
220 </ul> |
|
221 |
|
222 <p>When a <code>Boolean</code> return type is requested, |
|
223 <code>Boolean.TRUE</code> is returned if one or more nodes were |
|
224 selected; otherwise, <code>Boolean.FALSE</code> is returned.</p> |
|
225 |
|
226 <p>The <code>String</code> return type is a convenience for retrieving |
|
227 the character data from a text node, attribute node, comment node, or |
|
228 processing-instruction node. When used on an element node, the value |
|
229 of the child text nodes is returned. |
|
230 </p> |
|
231 |
|
232 <p>The <code>Number</code> return type attempts to coalesce the text |
|
233 of a node to a <code>double</code> data type. |
|
234 </p> |
|
235 |
|
236 <h3>XPath Context</h3> |
|
237 |
|
238 <p>XPath location paths may be relative to a particular node in the |
|
239 document, known as the <code>context</code>. Consider the following |
|
240 XML document:</p> |
|
241 |
|
242 <pre> |
|
243 <widgets> |
|
244 <widget> |
|
245 <manufacturer/> |
|
246 <dimensions/> |
|
247 </widget> |
|
248 </widgets> |
|
249 </pre> |
|
250 |
|
251 <p>The <code><widget></code> element can be selected with the |
|
252 following XPath API code:</p> |
|
253 |
|
254 <pre> |
|
255 // parse the XML as a W3C Document |
|
256 DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder(); |
|
257 Document document = builder.parse(new File("/widgets.xml")); |
|
258 |
|
259 XPath xpath = XPathFactory.newInstance().newXPath(); |
|
260 String expression = "/widgets/widget"; |
|
261 Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE); |
|
262 </pre> |
|
263 |
|
264 <p>With a reference to the <code><widget></code> element, a |
|
265 relative XPath expression can now written to select the |
|
266 <code><manufacturer></code> child element:</p> |
|
267 |
|
268 <pre> |
|
269 XPath xpath = XPathFactory.newInstance().newXPath(); |
|
270 <strong>String expression = "manufacturer";</strong> |
|
271 Node manufacturerNode = (Node) xpath.evaluate(expression, <strong>widgetNode</strong>, XPathConstants.NODE); |
|
272 </pre> |
|
273 |
|
274 <ul> |
|
275 <li>Author <a href="mailto:Ben@galbraiths.org">Ben Galbraith</a></li> |
|
276 <li>Author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a></li> |
|
277 <li>Author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a></li> |
|
278 <li>See <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li> |
|
279 <li>Since 1.5</li> |
|
280 </ul> |
|
281 </body> |
|
282 </html> |