1 <!doctype html> |
|
2 <html> |
|
3 <head> |
|
4 <!-- |
|
5 Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved. |
|
6 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
7 |
|
8 This code is free software; you can redistribute it and/or modify it |
|
9 under the terms of the GNU General Public License version 2 only, as |
|
10 published by the Free Software Foundation. Oracle designates this |
|
11 particular file as subject to the "Classpath" exception as provided |
|
12 by Oracle in the LICENSE file that accompanied this code. |
|
13 |
|
14 This code is distributed in the hope that it will be useful, but WITHOUT |
|
15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
16 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
17 version 2 for more details (a copy is included in the LICENSE file that |
|
18 accompanied this code). |
|
19 |
|
20 You should have received a copy of the GNU General Public License version |
|
21 2 along with this work; if not, write to the Free Software Foundation, |
|
22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
23 |
|
24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
25 or visit www.oracle.com if you need additional information or have any |
|
26 questions. |
|
27 --> |
|
28 </head> |
|
29 <body> |
|
30 |
|
31 This package provides an <em>object-model neutral</em> API for the |
|
32 evaluation of XPath expressions and access to the evaluation |
|
33 environment. |
|
34 |
|
35 <p> |
|
36 The XPath API supports <a href="http://www.w3.org/TR/xpath"> |
|
37 XML Path Language (XPath) Version 1.0</a> |
|
38 |
|
39 <hr> |
|
40 |
|
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 id="XPath.Overview"></a> |
|
56 <h3>1. XPath Overview</h3> |
|
57 |
|
58 <p>The XPath language provides a simple, concise syntax for selecting |
|
59 nodes from an XML document. XPath also provides rules for converting a |
|
60 node in an XML document object model (DOM) tree to a boolean, double, |
|
61 or string value. XPath is a W3C-defined language and an official W3C |
|
62 recommendation; the W3C hosts the XML Path Language (XPath) Version |
|
63 1.0 specification. |
|
64 </p> |
|
65 |
|
66 <p>XPath started in life in 1999 as a supplement to the XSLT and |
|
67 XPointer languages, but has more recently become popular as a |
|
68 stand-alone language, as a single XPath expression can be used to |
|
69 replace many lines of DOM API code. |
|
70 </p> |
|
71 |
|
72 <a id="XPath.Expressions"></a> |
|
73 <h3>2. XPath Expressions</h3> |
|
74 |
|
75 <p>An XPath <em>expression</em> is composed of a <em>location |
|
76 path</em> and one or more optional <em>predicates</em>. Expressions |
|
77 may also include XPath variables. |
|
78 </p> |
|
79 |
|
80 <p>The following is an example of a simple XPath expression:</p> |
|
81 |
|
82 <blockquote> |
|
83 <pre> |
|
84 /foo/bar |
|
85 </pre> |
|
86 </blockquote> |
|
87 |
|
88 <p>This example would select the <code><bar></code> element in |
|
89 an XML document such as the following:</p> |
|
90 |
|
91 <blockquote> |
|
92 <pre> |
|
93 <foo> |
|
94 <bar/> |
|
95 </foo> |
|
96 </pre> |
|
97 </blockquote> |
|
98 |
|
99 <p>The expression <code>/foo/bar</code> is an example of a location |
|
100 path. While XPath location paths resemble Unix-style file system |
|
101 paths, an important distinction is that XPath expressions return |
|
102 <em>all</em> nodes that match the expression. Thus, all three |
|
103 <code><bar></code> elements in the following document would be |
|
104 selected by the <code>/foo/bar</code> expression:</p> |
|
105 |
|
106 <blockquote> |
|
107 <pre> |
|
108 <foo> |
|
109 <bar/> |
|
110 <bar/> |
|
111 <bar/> |
|
112 </foo> |
|
113 </pre> |
|
114 </blockquote> |
|
115 |
|
116 <p>A special location path operator, <code>//</code>, selects nodes at |
|
117 any depth in an XML document. The following example selects all |
|
118 <code><bar></code> elements regardless of their location in a |
|
119 document:</p> |
|
120 |
|
121 <blockquote> |
|
122 <pre> |
|
123 //bar |
|
124 </pre> |
|
125 </blockquote> |
|
126 |
|
127 <p>A wildcard operator, *, causes all element nodes to be selected. |
|
128 The following example selects all children elements of a |
|
129 <code><foo></code> element: |
|
130 |
|
131 <blockquote> |
|
132 <pre> |
|
133 /foo/* |
|
134 </pre> |
|
135 </blockquote> |
|
136 |
|
137 <p>In addition to element nodes, XPath location paths may also address |
|
138 attribute nodes, text nodes, comment nodes, and processing instruction |
|
139 nodes. The following table gives examples of location paths for each |
|
140 of these node types:</p> |
|
141 |
|
142 <table class="striped"> |
|
143 <caption>Examples of Location Path</caption> |
|
144 <thead> |
|
145 <tr> |
|
146 <th>Location Path</th> |
|
147 <th>Description</th> |
|
148 </tr> |
|
149 </thead> |
|
150 <tbody> |
|
151 <tr> |
|
152 <td> |
|
153 <code>/foo/bar/<strong>@id</strong></code> |
|
154 </td> |
|
155 <td>Selects the attribute <code>id</code> of the <code><bar></code> element |
|
156 </td> |
|
157 </tr> |
|
158 <tr> |
|
159 <td><code>/foo/bar/<strong>text()</strong></code> |
|
160 </td> |
|
161 <td>Selects the text nodes of the <code><bar></code> element. No |
|
162 distinction is made between escaped and non-escaped character data. |
|
163 </td> |
|
164 </tr> |
|
165 <tr> |
|
166 <td><code>/foo/bar/<strong>comment()</strong></code> |
|
167 </td> |
|
168 <td>Selects all comment nodes contained in the <code><bar></code> element. |
|
169 </td> |
|
170 </tr> |
|
171 <tr> |
|
172 <td><code>/foo/bar/<strong>processing-instruction()</strong></code> |
|
173 </td> |
|
174 <td>Selects all processing-instruction nodes contained in the |
|
175 <code><bar></code> element. |
|
176 </td> |
|
177 </tr> |
|
178 </tbody> |
|
179 </table> |
|
180 |
|
181 <p>Predicates allow for refining the nodes selected by an XPath |
|
182 location path. Predicates are of the form |
|
183 <code>[<em>expression</em>]</code>. The following example selects all |
|
184 <code><foo></code> elements that contain an <code>include</code> |
|
185 attribute with the value of <code>true</code>:</p> |
|
186 |
|
187 <blockquote> |
|
188 <pre> |
|
189 //foo[@include='true'] |
|
190 </pre> |
|
191 </blockquote> |
|
192 |
|
193 <p>Predicates may be appended to each other to further refine an |
|
194 expression, such as:</p> |
|
195 |
|
196 <blockquote> |
|
197 <pre> |
|
198 //foo[@include='true'][@mode='bar'] |
|
199 </pre> |
|
200 </blockquote> |
|
201 |
|
202 <a id="XPath.Datatypes"></a> |
|
203 <h3>3. XPath Data Types</h3> |
|
204 |
|
205 <p>While XPath expressions select nodes in the XML document, the XPath |
|
206 API allows the selected nodes to be coalesced into one of the |
|
207 following data types:</p> |
|
208 |
|
209 <ul> |
|
210 <li><code>Boolean</code></li> |
|
211 <li><code>Number</code></li> |
|
212 <li><code>String</code></li> |
|
213 </ul> |
|
214 |
|
215 <a id="XPath.Datatypes.QName"></a> |
|
216 <h3>3.1 QName types</h3> |
|
217 The XPath API defines the following {@link javax.xml.namespace.QName} types to |
|
218 represent return types of an XPath evaluation: |
|
219 <ul> |
|
220 <li>{@link javax.xml.xpath.XPathConstants#NODESET}</li> |
|
221 <li>{@link javax.xml.xpath.XPathConstants#NODE}</li> |
|
222 <li>{@link javax.xml.xpath.XPathConstants#STRING}</li> |
|
223 <li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li> |
|
224 <li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li> |
|
225 </ul> |
|
226 |
|
227 <p>The return type is specified by a {@link javax.xml.namespace.QName} parameter |
|
228 in method call used to evaluate the expression, which is either a call to |
|
229 <code>XPathExpression.evalute(...)</code> or <code>XPath.evaluate(...)</code> |
|
230 methods. |
|
231 |
|
232 <p>When a <code>Boolean</code> return type is requested, |
|
233 <code>Boolean.TRUE</code> is returned if one or more nodes were |
|
234 selected; otherwise, <code>Boolean.FALSE</code> is returned. |
|
235 |
|
236 <p>The <code>String</code> return type is a convenience for retrieving |
|
237 the character data from a text node, attribute node, comment node, or |
|
238 processing-instruction node. When used on an element node, the value |
|
239 of the child text nodes is returned. |
|
240 |
|
241 <p>The <code>Number</code> return type attempts to coalesce the text |
|
242 of a node to a <code>double</code> data type. |
|
243 |
|
244 <a id="XPath.Datatypes.Class"></a> |
|
245 <h3>3.2 Class types</h3> |
|
246 In addition to the QName types, the XPath API supports the use of Class types |
|
247 through the <code>XPathExpression.evaluteExpression(...)</code> or |
|
248 <code>XPath.evaluateExpression(...)</code> methods. |
|
249 |
|
250 The XPath data types are mapped to Class types as follows: |
|
251 <ul> |
|
252 <li><code>Boolean</code> -- <code>Boolean.class</code></li> |
|
253 <li><code>Number</code> -- <code>Number.class</code></li> |
|
254 <li><code>String</code> -- <code>String.class</code></li> |
|
255 <li><code>Nodeset</code> -- <code>XPathNodes.class</code></li> |
|
256 <li><code>Node</code> -- <code>Node.class</code></li> |
|
257 </ul> |
|
258 |
|
259 <p> |
|
260 Of the subtypes of Number, only Double, Integer and Long are supported. |
|
261 |
|
262 <a id="XPath.Datatypes.Enum"></a> |
|
263 <h3>3.3 Enum types</h3> |
|
264 Enum types are defined in {@link javax.xml.xpath.XPathEvaluationResult.XPathResultType} |
|
265 that provide mappings between the QName and Class types above. The result of |
|
266 evaluating an expression using the <code>XPathExpression.evaluteExpression(...)</code> |
|
267 or <code>XPath.evaluateExpression(...)</code> methods will be of one of these types. |
|
268 |
|
269 <a id="XPath.Context"></a> |
|
270 <h3>4. XPath Context</h3> |
|
271 |
|
272 <p>XPath location paths may be relative to a particular node in the |
|
273 document, known as the <code>context</code>. A context consists of: |
|
274 <ul> |
|
275 <li>a node (the context node)</li> |
|
276 <li>a pair of non-zero positive integers (the context position and the context size)</li> |
|
277 <li>a set of variable bindings</li> |
|
278 <li>a function library</li> |
|
279 <li>the set of namespace declarations in scope for the expression</li> |
|
280 </ul> |
|
281 |
|
282 <p> |
|
283 It is an XML document tree represented as a hierarchy of nodes, a |
|
284 {@link org.w3c.dom.Node} for example, in the JDK implementation. |
|
285 |
|
286 <a id="XPath.Use"></a> |
|
287 <h3>5. Using the XPath API</h3> |
|
288 |
|
289 Consider the following XML document: |
|
290 <blockquote> |
|
291 <pre> |
|
292 <widgets> |
|
293 <widget> |
|
294 <manufacturer/> |
|
295 <dimensions/> |
|
296 </widget> |
|
297 </widgets> |
|
298 </pre> |
|
299 </blockquote> |
|
300 |
|
301 <p> |
|
302 The <code><widget></code> element can be selected with the following process: |
|
303 |
|
304 <blockquote> |
|
305 <pre> |
|
306 // parse the XML as a W3C Document |
|
307 DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder(); |
|
308 Document document = builder.parse(new File("/widgets.xml")); |
|
309 |
|
310 //Get an XPath object and evaluate the expression |
|
311 XPath xpath = XPathFactory.newInstance().newXPath(); |
|
312 String expression = "/widgets/widget"; |
|
313 Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE); |
|
314 |
|
315 //or using the evaluateExpression method |
|
316 Node widgetNode = xpath.evaluateExpression(expression, document, Node.class); |
|
317 </pre> |
|
318 </blockquote> |
|
319 |
|
320 <p>With a reference to the <code><widget></code> element, a |
|
321 relative XPath expression can be written to select the |
|
322 <code><manufacturer></code> child element:</p> |
|
323 |
|
324 <blockquote> |
|
325 <pre> |
|
326 XPath xpath = XPathFactory.newInstance().newXPath(); |
|
327 <strong>String expression = "manufacturer";</strong> |
|
328 Node manufacturerNode = (Node) xpath.evaluate(expression, <strong>widgetNode</strong>, XPathConstants.NODE); |
|
329 |
|
330 //or using the evaluateExpression method |
|
331 Node manufacturerNode = xpath.evaluateExpression(expression, <strong>widgetNode</strong>, Node.class); |
|
332 </pre> |
|
333 </blockquote> |
|
334 |
|
335 <p> |
|
336 In the above example, the XML file is read into a DOM Document before being passed |
|
337 to the XPath API. The following code demonstrates the use of InputSource to |
|
338 leave it to the XPath implementation to process it: |
|
339 |
|
340 <blockquote> |
|
341 <pre> |
|
342 XPath xpath = XPathFactory.newInstance().newXPath(); |
|
343 String expression = "/widgets/widget"; |
|
344 InputSource inputSource = new InputSource("widgets.xml"); |
|
345 NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET); |
|
346 |
|
347 //or using the evaluateExpression method |
|
348 XPathNodes nodes = xpath.evaluate(expression, inputSource, XPathNodes.class); |
|
349 </pre> |
|
350 </blockquote> |
|
351 |
|
352 <p> |
|
353 In the above cases, the type of the expected results are known. In case where |
|
354 the result type is unknown or any type, the {@link javax.xml.xpath.XPathEvaluationResult} |
|
355 may be used to determine the return type. The following code demonstrates the usage: |
|
356 <blockquote> |
|
357 <pre> |
|
358 XPathEvaluationResult<?> result = xpath.evaluateExpression(expression, document); |
|
359 switch (result.type()) { |
|
360 case NODESET: |
|
361 XPathNodes nodes = (XPathNodes)result.value(); |
|
362 ... |
|
363 break; |
|
364 } |
|
365 </pre> |
|
366 </blockquote> |
|
367 |
|
368 <p> |
|
369 The XPath 1.0 Number data type is defined as a double. However, the XPath |
|
370 specification also provides functions that returns Integer type. To facilitate |
|
371 such operations, the XPath API allows Integer and Long to be used in |
|
372 {@code evaluateExpression} method such as the following code: |
|
373 <blockquote> |
|
374 <pre> |
|
375 int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class); |
|
376 </pre> |
|
377 </blockquote> |
|
378 |
|
379 @since 1.5 |
|
380 |
|
381 </body> |
|
382 </html> |
|