286N/A<?xml version="1.0" encoding="UTF-8"?>
286N/A<!--
286N/ACopyright (c) 2003, 2005, Oracle and/or its affiliates. All rights reserved.
286N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
286N/A
286N/AThis code is free software; you can redistribute it and/or modify it
286N/Aunder the terms of the GNU General Public License version 2 only, as
286N/Apublished by the Free Software Foundation. Oracle designates this
286N/Aparticular file as subject to the "Classpath" exception as provided
286N/Aby Oracle in the LICENSE file that accompanied this code.
286N/A
286N/AThis code is distributed in the hope that it will be useful, but WITHOUT
286N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
286N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
286N/Aversion 2 for more details (a copy is included in the LICENSE file that
286N/Aaccompanied this code).
286N/A
286N/AYou should have received a copy of the GNU General Public License version
286N/A2 along with this work; if not, write to the Free Software Foundation,
286N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
286N/A
286N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
286N/Aor visit www.oracle.com if you need additional information or have any
286N/Aquestions.
286N/A-->
286N/A
286N/A<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
286N/A "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
286N/A<html xmlns="http://www.w3.org/1999/xhtml">
286N/A<head>
286N/A<title>javax.xml.xpath</title>
286N/A<meta name="@author" content="mailto:Ben@galbraiths.org" />
286N/A<meta name="@author" content="mailto:Norman.Walsh@Sun.com" />
286N/A<meta name="@author" content="mailto:Jeff.Suttor@Sun.com" />
286N/A<meta name="@version" content="$Revision: 1.3 $, $Date: 2005/11/03 19:34:17 $" />
286N/A<meta name="@see" content="http://www.w3.org/TR/xpath" />
286N/A<meta name="@since" content="1.5" />
286N/A</head>
286N/A
286N/A<body>
286N/A
286N/A<p>This package provides an <em>object-model neutral</em> API for the
286N/Aevaluation of XPath expressions and access to the evaluation
286N/Aenvironment.
286N/A</p>
286N/A
286N/A<p>The following XML standards apply:</p>
286N/A
286N/A<ul>
286N/A<li><a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li>
286N/A</ul>
286N/A
286N/A<hr />
286N/A
286N/A<h2>XPath Overview</h2>
286N/A
286N/A<p>The XPath language provides a simple, concise syntax for selecting
286N/Anodes from an XML document. XPath also provides rules for converting a
286N/Anode in an XML document object model (DOM) tree to a boolean, double,
286N/Aor string value. XPath is a W3C-defined language and an official W3C
286N/Arecommendation; the W3C hosts the XML Path Language (XPath) Version
286N/A1.0 specification.
286N/A</p>
286N/A
286N/A<p>XPath started in life in 1999 as a supplement to the XSLT and
286N/AXPointer languages, but has more recently become popular as a
286N/Astand-alone language, as a single XPath expression can be used to
286N/Areplace many lines of DOM API code.
286N/A</p>
286N/A
286N/A<h3>XPath Expressions</h3>
286N/A
286N/A<p>An XPath <em>expression</em> is composed of a <em>location
286N/Apath</em> and one or more optional <em>predicates</em>. Expressions
286N/Amay also include XPath variables.
286N/A</p>
286N/A
286N/A<p>The following is an example of a simple XPath expression:</p>
286N/A
286N/A<pre>
286N/A/foo/bar
286N/A</pre>
286N/A
286N/A<p>This example would select the <code>&lt;bar&gt;</code> element in
286N/Aan XML document such as the following:</p>
286N/A
286N/A<pre>
286N/A&lt;foo&gt;
286N/A&lt;bar/&gt;
286N/A&lt;/foo&gt;
286N/A</pre>
286N/A
286N/A<p>The expression <code>/foo/bar</code> is an example of a location
286N/Apath. While XPath location paths resemble Unix-style file system
286N/Apaths, an important distinction is that XPath expressions return
286N/A<em>all</em> nodes that match the expression. Thus, all three
286N/A<code>&lt;bar&gt;</code> elements in the following document would be
286N/Aselected by the <code>/foo/bar</code> expression:</p>
286N/A
286N/A<pre>
286N/A&lt;foo&gt;
286N/A&lt;bar/&gt;
286N/A&lt;bar/&gt;
286N/A&lt;bar/&gt;
286N/A&lt;/foo&gt;
286N/A</pre>
286N/A
286N/A<p>A special location path operator, <code>//</code>, selects nodes at
286N/Aany depth in an XML document. The following example selects all
286N/A<code>&lt;bar&gt;</code> elements regardless of their location in a
286N/Adocument:</p>
286N/A
286N/A<pre>
286N/A//bar
286N/A</pre>
286N/A
286N/A<p>A wildcard operator, *, causes all element nodes to be selected.
286N/AThe following example selects all children elements of a
286N/A<code>&lt;foo&gt;</code> element:</p>
286N/A
286N/A<pre>
286N/A/foo/*
286N/A</pre>
286N/A
286N/A<p>In addition to element nodes, XPath location paths may also address
286N/Aattribute nodes, text nodes, comment nodes, and processing instruction
286N/Anodes. The following table gives examples of location paths for each
286N/Aof these node types:</p>
286N/A
286N/A<table border="1">
286N/A<tr>
286N/A<td>Location Path</td>
286N/A<td>Description</td>
286N/A</tr>
286N/A<tr>
286N/A<td>
286N/A<code>/foo/bar/<strong>@id</strong></code>
286N/A</td>
286N/A<td>Selects the attribute <code>id</code> of the <code>&lt;bar&gt;</code> element
286N/A</td>
286N/A</tr>
286N/A<tr>
286N/A<td><code>/foo/bar/<strong>text()</strong></code>
286N/A</td>
286N/A<td>Selects the text nodes of the <code>&lt;bar&gt;</code> element. No
286N/Adistinction is made between escaped and non-escaped character data.
286N/A</td>
286N/A</tr>
286N/A<tr>
286N/A<td><code>/foo/bar/<strong>comment()</strong></code>
286N/A</td>
286N/A<td>Selects all comment nodes contained in the <code>&lt;bar&gt;</code> element.
286N/A</td>
286N/A</tr>
286N/A<tr>
286N/A<td><code>/foo/bar/<strong>processing-instruction()</strong></code>
286N/A</td>
286N/A<td>Selects all processing-instruction nodes contained in the
286N/A<code>&lt;bar&gt;</code> element.
286N/A</td>
286N/A</tr>
286N/A</table>
286N/A
286N/A<p>Predicates allow for refining the nodes selected by an XPath
286N/Alocation path. Predicates are of the form
286N/A<code>[<em>expression</em>]</code>. The following example selects all
286N/A<code>&lt;foo&gt;</code> elements that contain an <code>include</code>
286N/Aattribute with the value of <code>true</code>:</p>
286N/A
286N/A<pre>
286N/A//foo[@include='true']
286N/A</pre>
286N/A
286N/A<p>Predicates may be appended to each other to further refine an
286N/Aexpression, such as:</p>
286N/A
286N/A<pre>
286N/A//foo[@include='true'][@mode='bar']
286N/A</pre>
286N/A
286N/A<h3>Using the XPath API</h3>
286N/A
286N/A<p>
286N/AThe following example demonstrates using the XPath API to select one
286N/Aor more nodes from an XML document:</p>
286N/A
286N/A<pre>
286N/AXPath xpath = XPathFactory.newInstance().newXPath();
286N/AString expression = "/widgets/widget";
286N/AInputSource inputSource = new InputSource("widgets.xml");
286N/ANodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET);
286N/A</pre>
286N/A
286N/A<h3>XPath Expressions and Types</h3>
286N/A
286N/A<p>While XPath expressions select nodes in the XML document, the XPath
286N/AAPI allows the selected nodes to be coalesced into one of the
286N/Afollowing other data types:</p>
286N/A
286N/A<ul>
286N/A<li><code>Boolean</code></li>
286N/A<li><code>Number</code></li>
286N/A<li><code>String</code></li>
286N/A</ul>
286N/A
286N/A<p>The desired return type is specified by a {@link
286N/Ajavax.xml.namespace.QName} parameter in method call used to evaluate
286N/Athe expression, which is either a call to
286N/A<code>XPathExpression.evalute(...)</code> or to one of the
286N/A<code>XPath.evaluate(...)</code> convenience methods. The allowed
286N/AQName values are specified as constants in the {@link
286N/Ajavax.xml.xpath.XPathConstants} class; they are:</p>
286N/A
286N/A<ul>
286N/A<li>{@link javax.xml.xpath.XPathConstants#NODESET}</li>
286N/A<li>{@link javax.xml.xpath.XPathConstants#NODE}</li>
286N/A<li>{@link javax.xml.xpath.XPathConstants#STRING}</li>
286N/A<li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li>
286N/A<li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li>
286N/A</ul>
286N/A
286N/A<p>When a <code>Boolean</code> return type is requested,
286N/A<code>Boolean.TRUE</code> is returned if one or more nodes were
286N/Aselected; otherwise, <code>Boolean.FALSE</code> is returned.</p>
286N/A
286N/A<p>The <code>String</code> return type is a convenience for retrieving
286N/Athe character data from a text node, attribute node, comment node, or
286N/Aprocessing-instruction node. When used on an element node, the value
286N/Aof the child text nodes is returned.
286N/A</p>
286N/A
286N/A<p>The <code>Number</code> return type attempts to coalesce the text
286N/Aof a node to a <code>double</code> data type.
286N/A</p>
286N/A
286N/A<h3>XPath Context</h3>
286N/A
286N/A<p>XPath location paths may be relative to a particular node in the
286N/Adocument, known as the <code>context</code>. Consider the following
286N/AXML document:</p>
286N/A
286N/A<pre>
286N/A&lt;widgets&gt;
286N/A&lt;widget&gt;
286N/A&lt;manufacturer/&gt;
286N/A&lt;dimensions/&gt;
286N/A&lt;/widget&gt;
286N/A&lt;/widgets&gt;
286N/A</pre>
286N/A
286N/A<p>The <code>&lt;widget&gt;</code> element can be selected with the
286N/Afollowing XPath API code:</p>
286N/A
286N/A<pre>
286N/A// parse the XML as a W3C Document
286N/ADocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
286N/ADocument document = builder.parse(new File("/widgets.xml"));
286N/A
286N/AXPath xpath = XPathFactory.newInstance().newXPath();
286N/AString expression = "/widgets/widget";
286N/ANode widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE);
286N/A</pre>
286N/A
286N/A<p>With a reference to the <code>&lt;widget&gt;</code> element, a
286N/Arelative XPath expression can now written to select the
286N/A<code>&lt;manufacturer&gt;</code> child element:</p>
286N/A
286N/A<pre>
286N/AXPath xpath = XPathFactory.newInstance().newXPath();
286N/A<strong>String expression = "manufacturer";</strong>
286N/ANode manufacturerNode = (Node) xpath.evaluate(expression, <strong>widgetNode</strong>, XPathConstants.NODE);
286N/A</pre>
286N/A
286N/A<ul>
286N/A<li>Author <a href="mailto:Ben@galbraiths.org">Ben Galbraith</a></li>
286N/A<li>Author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a></li>
286N/A<li>Author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a></li>
286N/A<li>See <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li>
286N/A<li>Since 1.5</li>
286N/A</ul>
286N/A</body>
286N/A</html>