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 23 * questions. 24 */ 25 26/** 27 * 28 * Provides an <em>object-model neutral</em> API for the 29 * evaluation of XPath expressions and access to the evaluation 30 * environment. 31 * 32 * <p> 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 * 93 * <blockquote> 94 * <pre> 95 * <foo> 96 * <bar/> 97 * </foo> 98 * </pre> 99 * </blockquote> 100 * 101 * <p>The expression <code>/foo/bar</code> is an example of a location 102 * path. While XPath location paths resemble Unix-style file system 103 * paths, an important distinction is that XPath expressions return 104 * <em>all</em> nodes that match the expression. Thus, all three 105 * <code><bar></code> elements in the following document would be 106 * selected by the <code>/foo/bar</code> expression: 107 * 108 * <blockquote> 109 * <pre> 110 * <foo> 111 * <bar/> 112 * <bar/> 113 * <bar/> 114 * </foo> 115 * </pre> 116 * </blockquote> 117 * 118 * <p> 119 * A special location path operator, <code>//</code>, selects nodes at 120 * any depth in an XML document. The following example selects all 121 * <code><bar></code> elements regardless of their location in a 122 * document: 123 * 124 * <blockquote> 125 * <pre> 126 * //bar 127 * </pre> 128 * </blockquote> 129 * 130 * <p> 131 * A wildcard operator, *, causes all element nodes to be selected. 132 * The following example selects all children elements of a 133 * <code><foo></code> element: 134 * 135 * <blockquote> 136 * <pre> 137 * /foo/* 138 * </pre> 139 * </blockquote> 140 * 141 * <p> 142 * In addition to element nodes, XPath location paths may also address 143 * attribute nodes, text nodes, comment nodes, and processing instruction 144 * nodes. The following table gives examples of location paths for each 145 * of these node types: 146 * 147 * <table class="striped"> 148 * <caption>Examples of Location Path</caption> 149 * <thead> 150 * <tr> 151 * <th scope="col">Location Path</th> 152 * <th scope="col">Description</th> 153 * </tr> 154 * </thead> 155 * <tbody> 156 * <tr> 157 * <th scope="row"> 158 * <code>/foo/bar/<strong>@id</strong></code> 159 * </th> 160 * <td> 161 * Selects the attribute <code>id</code> of the <code><bar></code> element 162 * </td> 163 * </tr> 164 * <tr> 165 * <th scope="row"><code>/foo/bar/<strong>text()</strong></code> 166 * </th> 167 * <td> 168 * Selects the text nodes of the <code><bar></code> element. No 169 * distinction is made between escaped and non-escaped character data. 170 * </td> 171 * </tr> 172 * <tr> 173 * <th scope="row"><code>/foo/bar/<strong>comment()</strong></code> 174 * </th> 175 * <td> 176 * Selects all comment nodes contained in the <code><bar></code> element. 177 * </td> 178 * </tr> 179 * <tr> 180 * <th scope="row"><code>/foo/bar/<strong>processing-instruction()</strong></code> 181 * </th> 182 * <td> 183 * Selects all processing-instruction nodes contained in the 184 * <code><bar></code> element. 185 * </td> 186 * </tr> 187 * </tbody> 188 * </table> 189 * 190 * <p> 191 * Predicates allow for refining the nodes selected by an XPath 192 * location path. Predicates are of the form 193 * <code>[<em>expression</em>]</code>. The following example selects all 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(); 325 * Document document = builder.parse(new File("/widgets.xml")); 326 * 327 * //Get an XPath object and evaluate the expression 328 * XPath xpath = XPathFactory.newInstance().newXPath(); 329 * String expression = "/widgets/widget"; 330 * Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE); 331 * 332 * //or using the evaluateExpression method 333 * Node widgetNode = xpath.evaluateExpression(expression, document, Node.class); 334 * </pre> 335 * </blockquote> 336 * 337 * <p> 338 * With a reference to the <code><widget></code> element, a 339 * relative XPath expression can be written to select the 340 * <code><manufacturer></code> child element: 341 * 342 * <blockquote> 343 * <pre> 344 * XPath xpath = XPathFactory.newInstance().newXPath(); 345 * String expression = <b>"manufacturer";</b> 346 * Node manufacturerNode = (Node) xpath.evaluate(expression, <b>widgetNode</b>, XPathConstants.NODE); 347 * 348 * //or using the evaluateExpression method 349 * Node manufacturerNode = xpath.evaluateExpression(expression, <b>widgetNode</b>, Node.class); 350 * </pre> 351 * </blockquote> 352 * 353 * <p> 354 * In the above example, the XML file is read into a DOM Document before being passed 355 * to the XPath API. The following code demonstrates the use of InputSource to 356 * leave it to the XPath implementation to process it: 357 * 358 * <blockquote> 359 * <pre> 360 * XPath xpath = XPathFactory.newInstance().newXPath(); 361 * String expression = "/widgets/widget"; 362 * InputSource inputSource = new InputSource("widgets.xml"); 363 * NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET); 364 * 365 * //or using the evaluateExpression method 366 * XPathNodes nodes = xpath.evaluate(expression, inputSource, XPathNodes.class); 367 * </pre> 368 * </blockquote> 369 * 370 * <p> 371 * In the above cases, the type of the expected results are known. In case where 372 * the result type is unknown or any type, the {@link javax.xml.xpath.XPathEvaluationResult} 373 * may be used to determine the return type. The following code demonstrates the usage: 374 * <blockquote> 375 * <pre> 376 * XPathEvaluationResult<?> result = xpath.evaluateExpression(expression, document); 377 * switch (result.type()) { 378 * case NODESET: 379 * XPathNodes nodes = (XPathNodes)result.value(); 380 * ... 381 * break; 382 * } 383 * </pre> 384 * </blockquote> 385 * 386 * <p> 387 * The XPath 1.0 Number data type is defined as a double. However, the XPath 388 * specification also provides functions that returns Integer type. To facilitate 389 * such operations, the XPath API allows Integer and Long to be used in 390 * {@code evaluateExpression} method such as the following code: 391 * <blockquote> 392 * <pre> 393 * int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class); 394 * </pre> 395 * </blockquote> 396 * 397 * @since 1.5 398 * 399 */ 400 401package javax.xml.xpath; 402