| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- $Id: package.html 570107 2007-08-27 13:30:19Z mrglavas $ --> |
| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <title>javax.xml.xpath</title> |
| <meta name="@author" content="mailto:Ben@galbraiths.org" /> |
| <meta name="@author" content="mailto:Norman.Walsh@Sun.com" /> |
| <meta name="@author" content="mailto:Jeff.Suttor@Sun.com" /> |
| <meta name="@version" content="$Revision: 570107 $, $Date: 2007-08-27 06:30:19 -0700 (Mon, 27 Aug 2007) $" /> |
| <meta name="@see" content="http://www.w3.org/TR/xpath" /> |
| <meta name="@since" content="1.5" /> |
| </head> |
| |
| <body> |
| |
| <p>This package provides an <em>object-model neutral</em> API for the |
| evaluation of XPath expressions and access to the evaluation |
| environment. |
| </p> |
| |
| <p>The following XML standards apply:</p> |
| |
| <ul> |
| <li><a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li> |
| </ul> |
| |
| <hr /> |
| |
| <h2>XPath Overview</h2> |
| |
| <p>The XPath language provides a simple, concise syntax for selecting |
| nodes from an XML document. XPath also provides rules for converting a |
| node in an XML document object model (DOM) tree to a boolean, double, |
| or string value. XPath is a W3C-defined language and an official W3C |
| recommendation; the W3C hosts the XML Path Language (XPath) Version |
| 1.0 specification. |
| </p> |
| |
| <p>XPath started in life in 1999 as a supplement to the XSLT and |
| XPointer languages, but has more recently become popular as a |
| stand-alone language, as a single XPath expression can be used to |
| replace many lines of DOM API code. |
| </p> |
| |
| <h3>XPath Expressions</h3> |
| |
| <p>An XPath <em>expression</em> is composed of a <em>location |
| path</em> and one or more optional <em>predicates</em>. Expressions |
| may also include XPath variables. |
| </p> |
| |
| <p>The following is an example of a simple XPath expression:</p> |
| |
| <pre> |
| /foo/bar |
| </pre> |
| |
| <p>This example would select the <code><bar></code> element in |
| an XML document such as the following:</p> |
| |
| <pre> |
| <foo> |
| <bar/> |
| </foo> |
| </pre> |
| |
| <p>The expression <code>/foo/bar</code> is an example of a location |
| path. While XPath location paths resemble Unix-style file system |
| paths, an important distinction is that XPath expressions return |
| <em>all</em> nodes that match the expression. Thus, all three |
| <code><bar></code> elements in the following document would be |
| selected by the <code>/foo/bar</code> expression:</p> |
| |
| <pre> |
| <foo> |
| <bar/> |
| <bar/> |
| <bar/> |
| </foo> |
| </pre> |
| |
| <p>A special location path operator, <code>//</code>, selects nodes at |
| any depth in an XML document. The following example selects all |
| <code><bar></code> elements regardless of their location in a |
| document:</p> |
| |
| <pre> |
| //bar |
| </pre> |
| |
| <p>A wildcard operator, *, causes all element nodes to be selected. |
| The following example selects all children elements of a |
| <code><foo></code> element:</p> |
| |
| <pre> |
| /foo/* |
| </pre> |
| |
| <p>In addition to element nodes, XPath location paths may also address |
| attribute nodes, text nodes, comment nodes, and processing instruction |
| nodes. The following table gives examples of location paths for each |
| of these node types:</p> |
| |
| <table border="1"> |
| <tr> |
| <td>Location Path</td> |
| <td>Description</td> |
| </tr> |
| <tr> |
| <td> |
| <code>/foo/bar/<strong>@id</strong></code> |
| </td> |
| <td>Selects the attribute <code>id</code> of the <code><bar></code> element |
| </td> |
| </tr> |
| <tr> |
| <td><code>/foo/bar/<strong>text()</strong></code> |
| </td> |
| <td>Selects the text nodes of the <code><bar></code> element. No |
| distinction is made between escaped and non-escaped character data. |
| </td> |
| </tr> |
| <tr> |
| <td><code>/foo/bar/<strong>comment()</strong></code> |
| </td> |
| <td>Selects all comment nodes contained in the <code><bar></code> element. |
| </td> |
| </tr> |
| <tr> |
| <td><code>/foo/bar/<strong>processing-instruction()</strong></code> |
| </td> |
| <td>Selects all processing-instruction nodes contained in the |
| <code><bar></code> element. |
| </td> |
| </tr> |
| </table> |
| |
| <p>Predicates allow for refining the nodes selected by an XPath |
| location path. Predicates are of the form |
| <code>[<em>expression</em>]</code>. The following example selects all |
| <code><foo></code> elements that contain an <code>include</code> |
| attribute with the value of <code>true</code>:</p> |
| |
| <pre> |
| //foo[@include='true'] |
| </pre> |
| |
| <p>Predicates may be appended to each other to further refine an |
| expression, such as:</p> |
| |
| <pre> |
| //foo[@include='true'][@mode='bar'] |
| </pre> |
| |
| <h3>Using the XPath API</h3> |
| |
| <p> |
| The following example demonstrates using the XPath API to select one |
| or more nodes from an XML document:</p> |
| |
| <pre> |
| XPath xpath = XPathFactory.newInstance().newXPath(); |
| String expression = "/widgets/widget"; |
| InputSource inputSource = new InputSource("widgets.xml"); |
| NodeSet nodes = (NodeSet) xpath.evaluate(expression, inputSource, XPathConstants.NODESET); |
| </pre> |
| |
| <h3>XPath Expressions and Types</h3> |
| |
| <p>While XPath expressions select nodes in the XML document, the XPath |
| API allows the selected nodes to be coalesced into one of the |
| following other data types:</p> |
| |
| <ul> |
| <li><code>Boolean</code></li> |
| <li><code>Number</code></li> |
| <li><code>String</code></li> |
| </ul> |
| |
| <p>The desired return type is specified by a {@link |
| javax.xml.namespace.QName} parameter in method call used to evaluate |
| the expression, which is either a call to |
| <code>XPathExpression.evaluate(...)</code> or to one of the |
| <code>XPath.evaluate(...)</code> convenience methods. The allowed |
| QName values are specified as constants in the {@link |
| javax.xml.xpath.XPathConstants} class; they are:</p> |
| |
| <ul> |
| <li>{@link javax.xml.xpath.XPathConstants#NODESET}</li> |
| <li>{@link javax.xml.xpath.XPathConstants#NODE}</li> |
| <li>{@link javax.xml.xpath.XPathConstants#STRING}</li> |
| <li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li> |
| <li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li> |
| </ul> |
| |
| <p>When a <code>Boolean</code> return type is requested, |
| <code>Boolean.TRUE</code> is returned if one or more nodes were |
| selected; otherwise, <code>Boolean.FALSE</code> is returned.</p> |
| |
| <p>The <code>String</code> return type is a convenience for retrieving |
| the character data from a text node, attribute node, comment node, or |
| processing-instruction node. When used on an element node, the value |
| of the child text nodes is returned. |
| </p> |
| |
| <p>The <code>Number</code> return type attempts to coalesce the text |
| of a node to a <code>double</code> data type. |
| </p> |
| |
| <h3>XPath Context</h3> |
| |
| <p>XPath location paths may be relative to a particular node in the |
| document, known as the <code>context</code>. Consider the following |
| XML document:</p> |
| |
| <pre> |
| <widgets> |
| <widget> |
| <manufacturer/> |
| <dimensions/> |
| </widget> |
| </widgets> |
| </pre> |
| |
| <p>The <code><widget></code> element can be selected with the |
| following XPath API code:</p> |
| |
| <pre> |
| // parse the XML as a W3C Document |
| DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance(); |
| builderFactory.setNamespaceAware(true); |
| DocumentBuilder builder = builderFactory.newDocumentBuilder(); |
| Document document = builder.parse(new File("/widgets.xml")); |
| |
| XPath xpath = XPathFactory.newInstance().newXPath(); |
| String expression = "/widgets/widget"; |
| Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE); |
| </pre> |
| |
| <p>With a reference to the <code><widget></code> element, a |
| relative XPath expression can now written to select the |
| <code><manufacturer></code> child element:</p> |
| |
| <pre> |
| XPath xpath = XPathFactory.newInstance().newXPath(); |
| <strong>String expression = "manufacturer";</strong> |
| Node manufacturerNode = (Node) xpath.evaluate(expression, <strong>widgetNode</strong>, XPathConstants.NODE); |
| </pre> |
| |
| <ul> |
| <li>Author <a href="mailto:Ben@galbraiths.org">Ben Galbraith</a></li> |
| <li>Author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a></li> |
| <li>Author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a></li> |
| <li>See <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li> |
| <li>Since 1.5</li> |
| </ul> |
| </body> |
| </html> |