21 |
23 |
22 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
23 or visit www.oracle.com if you need additional information or have any |
25 or visit www.oracle.com if you need additional information or have any |
24 questions. |
26 questions. |
25 --> |
27 --> |
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="@see" content="http://www.w3.org/TR/xpath" /> |
|
36 <meta name="@since" content="1.5" /> |
|
37 </head> |
28 </head> |
38 |
29 <body bgcolor="white"> |
39 <body> |
30 |
40 |
31 This package provides an <em>object-model neutral</em> API for the |
41 <p>This package provides an <em>object-model neutral</em> API for the |
|
42 evaluation of XPath expressions and access to the evaluation |
32 evaluation of XPath expressions and access to the evaluation |
43 environment. |
33 environment. |
44 </p> |
34 |
45 |
35 <p> |
46 <p>The following XML standards apply:</p> |
36 The XPath API supports <a href="http://www.w3.org/TR/xpath"> |
47 |
37 XML Path Language (XPath) Version 1.0</a> |
48 <ul> |
|
49 <li><a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li> |
|
50 </ul> |
|
51 |
38 |
52 <hr /> |
39 <hr /> |
53 |
40 |
54 <h2>XPath Overview</h2> |
41 <ul> |
|
42 <li><a href='#XPath.Overview'>1. XPath Overview</a></li> |
|
43 <li><a href='#XPath.Expressions'>2. XPath Expressions</a></li> |
|
44 <li><a href='#XPath.Datatypes'>3. XPath Data Types</a> |
|
45 <ul> |
|
46 <li><a href='#XPath.Datatypes.QName'>3.1 QName Types</a> |
|
47 <li><a href='#XPath.Datatypes.Class'>3.2 Class Types</a> |
|
48 <li><a href='#XPath.Datatypes.Enum'>3.3 Enum Types</a> |
|
49 </ul> |
|
50 </li> |
|
51 <li><a href='#XPath.Context'>4. XPath Context</a></li> |
|
52 <li><a href='#XPath.Use'>5. Using the XPath API</a></li> |
|
53 </ul> |
|
54 <p> |
|
55 <a name="XPath.Overview"></a> |
|
56 <h3>1. XPath Overview</h3> |
55 |
57 |
56 <p>The XPath language provides a simple, concise syntax for selecting |
58 <p>The XPath language provides a simple, concise syntax for selecting |
57 nodes from an XML document. XPath also provides rules for converting a |
59 nodes from an XML document. XPath also provides rules for converting a |
58 node in an XML document object model (DOM) tree to a boolean, double, |
60 node in an XML document object model (DOM) tree to a boolean, double, |
59 or string value. XPath is a W3C-defined language and an official W3C |
61 or string value. XPath is a W3C-defined language and an official W3C |
65 XPointer languages, but has more recently become popular as a |
67 XPointer languages, but has more recently become popular as a |
66 stand-alone language, as a single XPath expression can be used to |
68 stand-alone language, as a single XPath expression can be used to |
67 replace many lines of DOM API code. |
69 replace many lines of DOM API code. |
68 </p> |
70 </p> |
69 |
71 |
70 <h3>XPath Expressions</h3> |
72 <a name="XPath.Expressions"></a> |
|
73 <h3>2. XPath Expressions</h3> |
71 |
74 |
72 <p>An XPath <em>expression</em> is composed of a <em>location |
75 <p>An XPath <em>expression</em> is composed of a <em>location |
73 path</em> and one or more optional <em>predicates</em>. Expressions |
76 path</em> and one or more optional <em>predicates</em>. Expressions |
74 may also include XPath variables. |
77 may also include XPath variables. |
75 </p> |
78 </p> |
76 |
79 |
77 <p>The following is an example of a simple XPath expression:</p> |
80 <p>The following is an example of a simple XPath expression:</p> |
78 |
81 |
|
82 <blockquote> |
79 <pre> |
83 <pre> |
80 /foo/bar |
84 /foo/bar |
81 </pre> |
85 </pre> |
|
86 </blockquote> |
82 |
87 |
83 <p>This example would select the <code><bar></code> element in |
88 <p>This example would select the <code><bar></code> element in |
84 an XML document such as the following:</p> |
89 an XML document such as the following:</p> |
85 |
90 |
|
91 <blockquote> |
86 <pre> |
92 <pre> |
87 <foo> |
93 <foo> |
88 <bar/> |
94 <bar/> |
89 </foo> |
95 </foo> |
90 </pre> |
96 </pre> |
|
97 </blockquote> |
91 |
98 |
92 <p>The expression <code>/foo/bar</code> is an example of a location |
99 <p>The expression <code>/foo/bar</code> is an example of a location |
93 path. While XPath location paths resemble Unix-style file system |
100 path. While XPath location paths resemble Unix-style file system |
94 paths, an important distinction is that XPath expressions return |
101 paths, an important distinction is that XPath expressions return |
95 <em>all</em> nodes that match the expression. Thus, all three |
102 <em>all</em> nodes that match the expression. Thus, all three |
96 <code><bar></code> elements in the following document would be |
103 <code><bar></code> elements in the following document would be |
97 selected by the <code>/foo/bar</code> expression:</p> |
104 selected by the <code>/foo/bar</code> expression:</p> |
98 |
105 |
|
106 <blockquote> |
99 <pre> |
107 <pre> |
100 <foo> |
108 <foo> |
101 <bar/> |
109 <bar/> |
102 <bar/> |
110 <bar/> |
103 <bar/> |
111 <bar/> |
104 </foo> |
112 </foo> |
105 </pre> |
113 </pre> |
|
114 </blockquote> |
106 |
115 |
107 <p>A special location path operator, <code>//</code>, selects nodes at |
116 <p>A special location path operator, <code>//</code>, selects nodes at |
108 any depth in an XML document. The following example selects all |
117 any depth in an XML document. The following example selects all |
109 <code><bar></code> elements regardless of their location in a |
118 <code><bar></code> elements regardless of their location in a |
110 document:</p> |
119 document:</p> |
111 |
120 |
|
121 <blockquote> |
112 <pre> |
122 <pre> |
113 //bar |
123 //bar |
114 </pre> |
124 </pre> |
|
125 </blockquote> |
115 |
126 |
116 <p>A wildcard operator, *, causes all element nodes to be selected. |
127 <p>A wildcard operator, *, causes all element nodes to be selected. |
117 The following example selects all children elements of a |
128 The following example selects all children elements of a |
118 <code><foo></code> element:</p> |
129 <code><foo></code> element: |
119 |
130 |
|
131 <blockquote> |
120 <pre> |
132 <pre> |
121 /foo/* |
133 /foo/* |
122 </pre> |
134 </pre> |
|
135 </blockquote> |
123 |
136 |
124 <p>In addition to element nodes, XPath location paths may also address |
137 <p>In addition to element nodes, XPath location paths may also address |
125 attribute nodes, text nodes, comment nodes, and processing instruction |
138 attribute nodes, text nodes, comment nodes, and processing instruction |
126 nodes. The following table gives examples of location paths for each |
139 nodes. The following table gives examples of location paths for each |
127 of these node types:</p> |
140 of these node types:</p> |
164 location path. Predicates are of the form |
177 location path. Predicates are of the form |
165 <code>[<em>expression</em>]</code>. The following example selects all |
178 <code>[<em>expression</em>]</code>. The following example selects all |
166 <code><foo></code> elements that contain an <code>include</code> |
179 <code><foo></code> elements that contain an <code>include</code> |
167 attribute with the value of <code>true</code>:</p> |
180 attribute with the value of <code>true</code>:</p> |
168 |
181 |
|
182 <blockquote> |
169 <pre> |
183 <pre> |
170 //foo[@include='true'] |
184 //foo[@include='true'] |
171 </pre> |
185 </pre> |
|
186 </blockquote> |
172 |
187 |
173 <p>Predicates may be appended to each other to further refine an |
188 <p>Predicates may be appended to each other to further refine an |
174 expression, such as:</p> |
189 expression, such as:</p> |
175 |
190 |
|
191 <blockquote> |
176 <pre> |
192 <pre> |
177 //foo[@include='true'][@mode='bar'] |
193 //foo[@include='true'][@mode='bar'] |
178 </pre> |
194 </pre> |
179 |
195 </blockquote> |
180 <h3>Using the XPath API</h3> |
196 |
181 |
197 <a name="XPath.Datatypes"></a> |
182 <p> |
198 <h3>3. XPath Data Types</h3> |
183 The following example demonstrates using the XPath API to select one |
|
184 or more nodes from an XML document:</p> |
|
185 |
|
186 <pre> |
|
187 XPath xpath = XPathFactory.newInstance().newXPath(); |
|
188 String expression = "/widgets/widget"; |
|
189 InputSource inputSource = new InputSource("widgets.xml"); |
|
190 NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET); |
|
191 </pre> |
|
192 |
|
193 <h3>XPath Expressions and Types</h3> |
|
194 |
199 |
195 <p>While XPath expressions select nodes in the XML document, the XPath |
200 <p>While XPath expressions select nodes in the XML document, the XPath |
196 API allows the selected nodes to be coalesced into one of the |
201 API allows the selected nodes to be coalesced into one of the |
197 following other data types:</p> |
202 following data types:</p> |
198 |
203 |
199 <ul> |
204 <ul> |
200 <li><code>Boolean</code></li> |
205 <li><code>Boolean</code></li> |
201 <li><code>Number</code></li> |
206 <li><code>Number</code></li> |
202 <li><code>String</code></li> |
207 <li><code>String</code></li> |
203 </ul> |
208 </ul> |
204 |
209 |
205 <p>The desired return type is specified by a {@link |
210 <a name="XPath.Datatypes.QName"></a> |
206 javax.xml.namespace.QName} parameter in method call used to evaluate |
211 <h3>3.1 QName types</h3> |
207 the expression, which is either a call to |
212 The XPath API defines the following {@link javax.xml.namespace.QName} types to |
208 <code>XPathExpression.evalute(...)</code> or to one of the |
213 represent return types of an XPath evaluation: |
209 <code>XPath.evaluate(...)</code> convenience methods. The allowed |
|
210 QName values are specified as constants in the {@link |
|
211 javax.xml.xpath.XPathConstants} class; they are:</p> |
|
212 |
|
213 <ul> |
214 <ul> |
214 <li>{@link javax.xml.xpath.XPathConstants#NODESET}</li> |
215 <li>{@link javax.xml.xpath.XPathConstants#NODESET}</li> |
215 <li>{@link javax.xml.xpath.XPathConstants#NODE}</li> |
216 <li>{@link javax.xml.xpath.XPathConstants#NODE}</li> |
216 <li>{@link javax.xml.xpath.XPathConstants#STRING}</li> |
217 <li>{@link javax.xml.xpath.XPathConstants#STRING}</li> |
217 <li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li> |
218 <li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li> |
218 <li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li> |
219 <li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li> |
219 </ul> |
220 </ul> |
220 |
221 |
|
222 <p>The return type is specified by a {@link javax.xml.namespace.QName} parameter |
|
223 in method call used to evaluate the expression, which is either a call to |
|
224 <code>XPathExpression.evalute(...)</code> or <code>XPath.evaluate(...)</code> |
|
225 methods. |
|
226 |
221 <p>When a <code>Boolean</code> return type is requested, |
227 <p>When a <code>Boolean</code> return type is requested, |
222 <code>Boolean.TRUE</code> is returned if one or more nodes were |
228 <code>Boolean.TRUE</code> is returned if one or more nodes were |
223 selected; otherwise, <code>Boolean.FALSE</code> is returned.</p> |
229 selected; otherwise, <code>Boolean.FALSE</code> is returned. |
224 |
230 |
225 <p>The <code>String</code> return type is a convenience for retrieving |
231 <p>The <code>String</code> return type is a convenience for retrieving |
226 the character data from a text node, attribute node, comment node, or |
232 the character data from a text node, attribute node, comment node, or |
227 processing-instruction node. When used on an element node, the value |
233 processing-instruction node. When used on an element node, the value |
228 of the child text nodes is returned. |
234 of the child text nodes is returned. |
229 </p> |
|
230 |
235 |
231 <p>The <code>Number</code> return type attempts to coalesce the text |
236 <p>The <code>Number</code> return type attempts to coalesce the text |
232 of a node to a <code>double</code> data type. |
237 of a node to a <code>double</code> data type. |
233 </p> |
238 |
234 |
239 <a name="XPath.Datatypes.Class"></a> |
235 <h3>XPath Context</h3> |
240 <h3>3.2 Class types</h3> |
|
241 In addition to the QName types, the XPath API supports the use of Class types |
|
242 through the <code>XPathExpression.evaluteExpression(...)</code> or |
|
243 <code>XPath.evaluateExpression(...)</code> methods. |
|
244 |
|
245 The XPath data types are mapped to Class types as follows: |
|
246 <ul> |
|
247 <li><code>Boolean</code> -- <code>Boolean.class</code></li> |
|
248 <li><code>Number</code> -- <code>Number.class</code></li> |
|
249 <li><code>String</code> -- <code>String.class</code></li> |
|
250 <li><code>Nodeset</code> -- <code>XPathNodes.class</code></li> |
|
251 <li><code>Node</code> -- <code>Node.class</code></li> |
|
252 </ul> |
|
253 |
|
254 <p> |
|
255 Of the subtypes of Number, only Double, Integer and Long are supported. |
|
256 |
|
257 <a name="XPath.Datatypes.Enum"></a> |
|
258 <h3>3.3 Enum types</h3> |
|
259 Enum types are defined in {@link javax.xml.xpath.XPathEvaluationResult.XPathResultType} |
|
260 that provide mappings between the QName and Class types above. The result of |
|
261 evaluating an expression using the <code>XPathExpression.evaluteExpression(...)</code> |
|
262 or <code>XPath.evaluateExpression(...)</code> methods will be of one of these types. |
|
263 |
|
264 <a name="XPath.Context"></a> |
|
265 <h3>4. XPath Context</h3> |
236 |
266 |
237 <p>XPath location paths may be relative to a particular node in the |
267 <p>XPath location paths may be relative to a particular node in the |
238 document, known as the <code>context</code>. Consider the following |
268 document, known as the <code>context</code>. A context consists of: |
239 XML document:</p> |
269 <ul> |
240 |
270 <li>a node (the context node)</li> |
|
271 <li>a pair of non-zero positive integers (the context position and the context size)</li> |
|
272 <li>a set of variable bindings</li> |
|
273 <li>a function library</li> |
|
274 <li>the set of namespace declarations in scope for the expression</li> |
|
275 </ul> |
|
276 |
|
277 <p> |
|
278 It is an XML document tree represented as a hierarchy of nodes, a |
|
279 {@link org.w3c.dom.Node} for example, in the JDK implementation. |
|
280 |
|
281 <a name="XPath.Use"></a> |
|
282 <h3>5. Using the XPath API</h3> |
|
283 |
|
284 Consider the following XML document: |
|
285 <p> |
|
286 <blockquote> |
241 <pre> |
287 <pre> |
242 <widgets> |
288 <widgets> |
243 <widget> |
289 <widget> |
244 <manufacturer/> |
290 <manufacturer/> |
245 <dimensions/> |
291 <dimensions/> |
246 </widget> |
292 </widget> |
247 </widgets> |
293 </widgets> |
248 </pre> |
294 </pre> |
249 |
295 </blockquote> |
250 <p>The <code><widget></code> element can be selected with the |
296 |
251 following XPath API code:</p> |
297 <p> |
252 |
298 The <code><widget></code> element can be selected with the following process: |
|
299 |
|
300 <blockquote> |
253 <pre> |
301 <pre> |
254 // parse the XML as a W3C Document |
302 // parse the XML as a W3C Document |
255 DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder(); |
303 DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder(); |
256 Document document = builder.parse(new File("/widgets.xml")); |
304 Document document = builder.parse(new File("/widgets.xml")); |
257 |
305 |
|
306 //Get an XPath object and evaluate the expression |
258 XPath xpath = XPathFactory.newInstance().newXPath(); |
307 XPath xpath = XPathFactory.newInstance().newXPath(); |
259 String expression = "/widgets/widget"; |
308 String expression = "/widgets/widget"; |
260 Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE); |
309 Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE); |
261 </pre> |
310 |
|
311 //or using the evaluateExpression method |
|
312 Node widgetNode = xpath.evaluateExpression(expression, document, Node.class); |
|
313 </pre> |
|
314 </blockquote> |
262 |
315 |
263 <p>With a reference to the <code><widget></code> element, a |
316 <p>With a reference to the <code><widget></code> element, a |
264 relative XPath expression can now written to select the |
317 relative XPath expression can be written to select the |
265 <code><manufacturer></code> child element:</p> |
318 <code><manufacturer></code> child element:</p> |
266 |
319 |
|
320 <blockquote> |
267 <pre> |
321 <pre> |
268 XPath xpath = XPathFactory.newInstance().newXPath(); |
322 XPath xpath = XPathFactory.newInstance().newXPath(); |
269 <strong>String expression = "manufacturer";</strong> |
323 <strong>String expression = "manufacturer";</strong> |
270 Node manufacturerNode = (Node) xpath.evaluate(expression, <strong>widgetNode</strong>, XPathConstants.NODE); |
324 Node manufacturerNode = (Node) xpath.evaluate(expression, <strong>widgetNode</strong>, XPathConstants.NODE); |
271 </pre> |
325 |
272 |
326 //or using the evaluateExpression method |
273 <ul> |
327 Node manufacturerNode = xpath.evaluateExpression(expression, <strong>widgetNode</strong>, Node.class); |
274 <li>Author <a href="mailto:Ben@galbraiths.org">Ben Galbraith</a></li> |
328 </pre> |
275 <li>Author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a></li> |
329 </blockquote> |
276 <li>Author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a></li> |
330 |
277 <li>See <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li> |
331 <p> |
278 <li>Since 1.5</li> |
332 In the above example, the XML file is read into a DOM Document before being passed |
279 </ul> |
333 to the XPath API. The following code demonstrates the use of InputSource to |
|
334 leave it to the XPath implementation to process it: |
|
335 |
|
336 <blockquote> |
|
337 <pre> |
|
338 XPath xpath = XPathFactory.newInstance().newXPath(); |
|
339 String expression = "/widgets/widget"; |
|
340 InputSource inputSource = new InputSource("widgets.xml"); |
|
341 NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET); |
|
342 |
|
343 //or using the evaluateExpression method |
|
344 XPathNodes nodes = xpath.evaluate(expression, inputSource, XPathNodes.class); |
|
345 </pre> |
|
346 </blockquote> |
|
347 |
|
348 <p> |
|
349 In the above cases, the type of the expected results are known. In case where |
|
350 the result type is unknown or any type, the {@link javax.xml.xpath.XPathEvaluationResult} |
|
351 may be used to determine the return type. The following code demonstrates the usage: |
|
352 <blockquote> |
|
353 <pre> |
|
354 XPathEvaluationResult<?> result = xpath.evaluateExpression(expression, document); |
|
355 switch (result.type()) { |
|
356 case NODESET: |
|
357 XPathNodes nodes = (XPathNodes)result.value(); |
|
358 ... |
|
359 break; |
|
360 } |
|
361 </pre> |
|
362 </blockquote> |
|
363 |
|
364 <p> |
|
365 The XPath 1.0 Number data type is defined as a double. However, the XPath |
|
366 specification also provides functions that returns Integer type. To facilitate |
|
367 such operations, the XPath API allows Integer and Long to be used in |
|
368 {@code evaluateExpression} method such as the following code: |
|
369 <p> |
|
370 <blockquote> |
|
371 <pre> |
|
372 int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class); |
|
373 </pre> |
|
374 </blockquote> |
|
375 |
|
376 @since 1.5 |
|
377 |
280 </body> |
378 </body> |
281 </html> |
379 </html> |