1 /*
2 * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
33 * The XPath API supports <a href="http://www.w3.org/TR/xpath">
34 * XML Path Language (XPath) Version 1.0</a>
35 *
36 * <hr>
37 *
38 * <ul>
39 * <li><a href='#XPath.Overview'>1. XPath Overview</a></li>
40 * <li><a href='#XPath.Expressions'>2. XPath Expressions</a></li>
41 * <li><a href='#XPath.Datatypes'>3. XPath Data Types</a>
42 * <ul>
43 * <li><a href='#XPath.Datatypes.QName'>3.1 QName Types</a>
44 * <li><a href='#XPath.Datatypes.Class'>3.2 Class Types</a>
45 * <li><a href='#XPath.Datatypes.Enum'>3.3 Enum Types</a>
46 * </ul>
47 * </li>
48 * <li><a href='#XPath.Context'>4. XPath Context</a></li>
49 * <li><a href='#XPath.Use'>5. Using the XPath API</a></li>
50 * </ul>
51 * <p>
52 * <a id="XPath.Overview"></a>
53 * <h3>1. XPath Overview</h3>
54 *
55 * <p>
56 * The XPath language provides a simple, concise syntax for selecting
57 * 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,
59 * or string value. XPath is a W3C-defined language and an official W3C
60 * recommendation; the W3C hosts the XML Path Language (XPath) Version
61 * 1.0 specification.
62 *
63 *
64 * <p>
65 * 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 *
70 *
71 * <a id="XPath.Expressions"></a>
72 * <h3>2. XPath Expressions</h3>
73 *
74 * <p>
75 * 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 *
79 *
80 * <p>
81 * The following is an example of a simple XPath expression:
82 *
83 * <blockquote>
84 * <pre>
85 * /foo/bar
86 * </pre>
87 * </blockquote>
88 *
89 * <p>
90 * This example would select the <code><bar></code> element in
91 * an XML document such as the following:
92 *
194 * <code><foo></code> elements that contain an <code>include</code>
195 * attribute with the value of <code>true</code>:
196 *
197 * <blockquote>
198 * <pre>
199 * //foo[@include='true']
200 * </pre>
201 * </blockquote>
202 *
203 * <p>
204 * Predicates may be appended to each other to further refine an
205 * expression, such as:
206 *
207 * <blockquote>
208 * <pre>
209 * //foo[@include='true'][@mode='bar']
210 * </pre>
211 * </blockquote>
212 *
213 * <a id="XPath.Datatypes"></a>
214 * <h3>3. XPath Data Types</h3>
215 *
216 * <p>
217 * While XPath expressions select nodes in the XML document, the XPath
218 * API allows the selected nodes to be coalesced into one of the
219 * following data types:
220 *
221 * <ul>
222 * <li><code>Boolean</code></li>
223 * <li><code>Number</code></li>
224 * <li><code>String</code></li>
225 * </ul>
226 *
227 * <a id="XPath.Datatypes.QName"></a>
228 * <h3>3.1 QName types</h3>
229 * The XPath API defines the following {@link javax.xml.namespace.QName} types to
230 * represent return types of an XPath evaluation:
231 * <ul>
232 * <li>{@link javax.xml.xpath.XPathConstants#NODESET}</li>
233 * <li>{@link javax.xml.xpath.XPathConstants#NODE}</li>
234 * <li>{@link javax.xml.xpath.XPathConstants#STRING}</li>
235 * <li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li>
236 * <li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li>
237 * </ul>
238 *
239 * <p>
240 * The return type is specified by a {@link javax.xml.namespace.QName} parameter
241 * in method call used to evaluate the expression, which is either a call to
242 * <code>XPathExpression.evalute(...)</code> or <code>XPath.evaluate(...)</code>
243 * methods.
244 *
245 * <p>
246 * When a <code>Boolean</code> return type is requested,
247 * <code>Boolean.TRUE</code> is returned if one or more nodes were
248 * selected; otherwise, <code>Boolean.FALSE</code> is returned.
249 *
250 * <p>
251 * The <code>String</code> return type is a convenience for retrieving
252 * the character data from a text node, attribute node, comment node, or
253 * processing-instruction node. When used on an element node, the value
254 * of the child text nodes is returned.
255 *
256 * <p>
257 * The <code>Number</code> return type attempts to coalesce the text
258 * of a node to a <code>double</code> data type.
259 *
260 * <a id="XPath.Datatypes.Class"></a>
261 * <h3>3.2 Class types</h3>
262 * In addition to the QName types, the XPath API supports the use of Class types
263 * through the <code>XPathExpression.evaluteExpression(...)</code> or
264 * <code>XPath.evaluateExpression(...)</code> methods.
265 *
266 * The XPath data types are mapped to Class types as follows:
267 * <ul>
268 * <li><code>Boolean</code> -- <code>Boolean.class</code></li>
269 * <li><code>Number</code> -- <code>Number.class</code></li>
270 * <li><code>String</code> -- <code>String.class</code></li>
271 * <li><code>Nodeset</code> -- <code>XPathNodes.class</code></li>
272 * <li><code>Node</code> -- <code>Node.class</code></li>
273 * </ul>
274 *
275 * <p>
276 * Of the subtypes of Number, only Double, Integer and Long are supported.
277 *
278 * <a id="XPath.Datatypes.Enum"></a>
279 * <h3>3.3 Enum types</h3>
280 * Enum types are defined in {@link javax.xml.xpath.XPathEvaluationResult.XPathResultType}
281 * that provide mappings between the QName and Class types above. The result of
282 * evaluating an expression using the <code>XPathExpression.evaluteExpression(...)</code>
283 * or <code>XPath.evaluateExpression(...)</code> methods will be of one of these types.
284 *
285 * <a id="XPath.Context"></a>
286 * <h3>4. XPath Context</h3>
287 *
288 * <p>
289 * XPath location paths may be relative to a particular node in the
290 * document, known as the <code>context</code>. A context consists of:
291 * <ul>
292 * <li>a node (the context node)</li>
293 * <li>a pair of non-zero positive integers (the context position and the context size)</li>
294 * <li>a set of variable bindings</li>
295 * <li>a function library</li>
296 * <li>the set of namespace declarations in scope for the expression</li>
297 * </ul>
298 *
299 * <p>
300 * It is an XML document tree represented as a hierarchy of nodes, a
301 * {@link org.w3c.dom.Node} for example, in the JDK implementation.
302 *
303 * <a id="XPath.Use"></a>
304 * <h3>5. Using the XPath API</h3>
305 *
306 * Consider the following XML document:
307 * <blockquote>
308 * <pre>
309 * <widgets>
310 * <widget>
311 * <manufacturer/>
312 * <dimensions/>
313 * </widget>
314 * </widgets>
315 * </pre>
316 * </blockquote>
317 *
318 * <p>
319 * The <code><widget></code> element can be selected with the following process:
320 *
321 * <blockquote>
322 * <pre>
323 * // parse the XML as a W3C Document
324 * DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
|
1 /*
2 * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
33 * The XPath API supports <a href="http://www.w3.org/TR/xpath">
34 * XML Path Language (XPath) Version 1.0</a>
35 *
36 * <hr>
37 *
38 * <ul>
39 * <li><a href='#XPath.Overview'>1. XPath Overview</a></li>
40 * <li><a href='#XPath.Expressions'>2. XPath Expressions</a></li>
41 * <li><a href='#XPath.Datatypes'>3. XPath Data Types</a>
42 * <ul>
43 * <li><a href='#XPath.Datatypes.QName'>3.1 QName Types</a>
44 * <li><a href='#XPath.Datatypes.Class'>3.2 Class Types</a>
45 * <li><a href='#XPath.Datatypes.Enum'>3.3 Enum Types</a>
46 * </ul>
47 * </li>
48 * <li><a href='#XPath.Context'>4. XPath Context</a></li>
49 * <li><a href='#XPath.Use'>5. Using the XPath API</a></li>
50 * </ul>
51 * <p>
52 * <a id="XPath.Overview"></a>
53 * <h2>1. XPath Overview</h2>
54 *
55 * <p>
56 * The XPath language provides a simple, concise syntax for selecting
57 * 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,
59 * or string value. XPath is a W3C-defined language and an official W3C
60 * recommendation; the W3C hosts the XML Path Language (XPath) Version
61 * 1.0 specification.
62 *
63 *
64 * <p>
65 * 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 *
70 *
71 * <a id="XPath.Expressions"></a>
72 * <h2>2. XPath Expressions</h2>
73 *
74 * <p>
75 * 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 *
79 *
80 * <p>
81 * The following is an example of a simple XPath expression:
82 *
83 * <blockquote>
84 * <pre>
85 * /foo/bar
86 * </pre>
87 * </blockquote>
88 *
89 * <p>
90 * This example would select the <code><bar></code> element in
91 * an XML document such as the following:
92 *
194 * <code><foo></code> elements that contain an <code>include</code>
195 * attribute with the value of <code>true</code>:
196 *
197 * <blockquote>
198 * <pre>
199 * //foo[@include='true']
200 * </pre>
201 * </blockquote>
202 *
203 * <p>
204 * Predicates may be appended to each other to further refine an
205 * expression, such as:
206 *
207 * <blockquote>
208 * <pre>
209 * //foo[@include='true'][@mode='bar']
210 * </pre>
211 * </blockquote>
212 *
213 * <a id="XPath.Datatypes"></a>
214 * <h2>3. XPath Data Types</h2>
215 *
216 * <p>
217 * While XPath expressions select nodes in the XML document, the XPath
218 * API allows the selected nodes to be coalesced into one of the
219 * following data types:
220 *
221 * <ul>
222 * <li><code>Boolean</code></li>
223 * <li><code>Number</code></li>
224 * <li><code>String</code></li>
225 * </ul>
226 *
227 * <a id="XPath.Datatypes.QName"></a>
228 * <h2>3.1 QName types</h2>
229 * The XPath API defines the following {@link javax.xml.namespace.QName} types to
230 * represent return types of an XPath evaluation:
231 * <ul>
232 * <li>{@link javax.xml.xpath.XPathConstants#NODESET}</li>
233 * <li>{@link javax.xml.xpath.XPathConstants#NODE}</li>
234 * <li>{@link javax.xml.xpath.XPathConstants#STRING}</li>
235 * <li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li>
236 * <li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li>
237 * </ul>
238 *
239 * <p>
240 * The return type is specified by a {@link javax.xml.namespace.QName} parameter
241 * in method call used to evaluate the expression, which is either a call to
242 * <code>XPathExpression.evalute(...)</code> or <code>XPath.evaluate(...)</code>
243 * methods.
244 *
245 * <p>
246 * When a <code>Boolean</code> return type is requested,
247 * <code>Boolean.TRUE</code> is returned if one or more nodes were
248 * selected; otherwise, <code>Boolean.FALSE</code> is returned.
249 *
250 * <p>
251 * The <code>String</code> return type is a convenience for retrieving
252 * the character data from a text node, attribute node, comment node, or
253 * processing-instruction node. When used on an element node, the value
254 * of the child text nodes is returned.
255 *
256 * <p>
257 * The <code>Number</code> return type attempts to coalesce the text
258 * of a node to a <code>double</code> data type.
259 *
260 * <a id="XPath.Datatypes.Class"></a>
261 * <h2>3.2 Class types</h2>
262 * In addition to the QName types, the XPath API supports the use of Class types
263 * through the <code>XPathExpression.evaluteExpression(...)</code> or
264 * <code>XPath.evaluateExpression(...)</code> methods.
265 *
266 * The XPath data types are mapped to Class types as follows:
267 * <ul>
268 * <li><code>Boolean</code> -- <code>Boolean.class</code></li>
269 * <li><code>Number</code> -- <code>Number.class</code></li>
270 * <li><code>String</code> -- <code>String.class</code></li>
271 * <li><code>Nodeset</code> -- <code>XPathNodes.class</code></li>
272 * <li><code>Node</code> -- <code>Node.class</code></li>
273 * </ul>
274 *
275 * <p>
276 * Of the subtypes of Number, only Double, Integer and Long are supported.
277 *
278 * <a id="XPath.Datatypes.Enum"></a>
279 * <h2>3.3 Enum types</h2>
280 * Enum types are defined in {@link javax.xml.xpath.XPathEvaluationResult.XPathResultType}
281 * that provide mappings between the QName and Class types above. The result of
282 * evaluating an expression using the <code>XPathExpression.evaluteExpression(...)</code>
283 * or <code>XPath.evaluateExpression(...)</code> methods will be of one of these types.
284 *
285 * <a id="XPath.Context"></a>
286 * <h2>4. XPath Context</h2>
287 *
288 * <p>
289 * XPath location paths may be relative to a particular node in the
290 * document, known as the <code>context</code>. A context consists of:
291 * <ul>
292 * <li>a node (the context node)</li>
293 * <li>a pair of non-zero positive integers (the context position and the context size)</li>
294 * <li>a set of variable bindings</li>
295 * <li>a function library</li>
296 * <li>the set of namespace declarations in scope for the expression</li>
297 * </ul>
298 *
299 * <p>
300 * It is an XML document tree represented as a hierarchy of nodes, a
301 * {@link org.w3c.dom.Node} for example, in the JDK implementation.
302 *
303 * <a id="XPath.Use"></a>
304 * <h2>5. Using the XPath API</h2>
305 *
306 * Consider the following XML document:
307 * <blockquote>
308 * <pre>
309 * <widgets>
310 * <widget>
311 * <manufacturer/>
312 * <dimensions/>
313 * </widget>
314 * </widgets>
315 * </pre>
316 * </blockquote>
317 *
318 * <p>
319 * The <code><widget></code> element can be selected with the following process:
320 *
321 * <blockquote>
322 * <pre>
323 * // parse the XML as a W3C Document
324 * DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
|