1
<?xml version="1.0" encoding="UTF-8"?>
2
<!-- $Id: package.html 226258 2005-07-22 18:20:18Z mrglavas $ -->
4
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
5
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
6
<html xmlns="http://www.w3.org/1999/xhtml">
8
<title>javax.xml.xpath</title>
9
<meta name="@author" content="mailto:Ben@galbraiths.org" />
10
<meta name="@author" content="mailto:Norman.Walsh@Sun.com" />
11
<meta name="@author" content="mailto:Jeff.Suttor@Sun.com" />
12
<meta name="@version" content="$Revision: 226258 $, $Date: 2005-07-22 14:20:18 -0400 (Fri, 22 Jul 2005) $" />
13
<meta name="@see" content="http://www.w3.org/TR/xpath" />
14
<meta name="@since" content="1.5" />
19
<p>This package provides an <em>object-model neutral</em> API for the
20
evaluation of XPath expressions and access to the evaluation
24
<p>The following XML standards apply:</p>
27
<li><a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li>
32
<h2>XPath Overview</h2>
34
<p>The XPath language provides a simple, concise syntax for selecting
35
nodes from an XML document. XPath also provides rules for converting a
36
node in an XML document object model (DOM) tree to a boolean, double,
37
or string value. XPath is a W3C-defined language and an official W3C
38
recommendation; the W3C hosts the XML Path Language (XPath) Version
42
<p>XPath started in life in 1999 as a supplement to the XSLT and
43
XPointer languages, but has more recently become popular as a
44
stand-alone language, as a single XPath expression can be used to
45
replace many lines of DOM API code.
48
<h3>XPath Expressions</h3>
50
<p>An XPath <em>expression</em> is composed of a <em>location
51
path</em> and one or more optional <em>predicates</em>. Expressions
52
may also include XPath variables.
55
<p>The following is an example of a simple XPath expression:</p>
61
<p>This example would select the <code><bar></code> element in
62
an XML document such as the following:</p>
70
<p>The expression <code>/foo/bar</code> is an example of a location
71
path. While XPath location paths resemble Unix-style file system
72
paths, an important distinction is that XPath expressions return
73
<em>all</em> nodes that match the expression. Thus, all three
74
<code><bar></code> elements in the following document would be
75
selected by the <code>/foo/bar</code> expression:</p>
85
<p>A special location path operator, <code>//</code>, selects nodes at
86
any depth in an XML document. The following example selects all
87
<code><bar></code> elements regardless of their location in a
94
<p>A wildcard operator, *, causes all element nodes to be selected.
95
The following example selects all children elements of a
96
<code><foo></code> element:</p>
102
<p>In addition to element nodes, XPath location paths may also address
103
attribute nodes, text nodes, comment nodes, and processing instruction
104
nodes. The following table gives examples of location paths for each
105
of these node types:</p>
109
<td>Location Path</td>
114
<code>/foo/bar/<strong>@id</strong></code>
116
<td>Selects the attribute <code>id</code> of the <code><bar></code> element
120
<td><code>/foo/bar/<strong>text()</strong></code>
122
<td>Selects the text nodes of the <code><bar></code> element. No
123
distinction is made between escaped and non-escaped character data.
127
<td><code>/foo/bar/<strong>comment()</strong></code>
129
<td>Selects all comment nodes contained in the <code><bar></code> element.
133
<td><code>/foo/bar/<strong>processing-instruction()</strong></code>
135
<td>Selects all processing-instruction nodes contained in the
136
<code><bar></code> element.
141
<p>Predicates allow for refining the nodes selected by an XPath
142
location path. Predicates are of the form
143
<code>[<em>expression</em>]</code>. The following example selects all
144
<code><foo></code> elements that contain an <code>include</code>
145
attribute with the value of <code>true</code>:</p>
148
//foo[@include='true']
151
<p>Predicates may be appended to each other to further refine an
152
expression, such as:</p>
155
//foo[@include='true'][@mode='bar']
158
<h3>Using the XPath API</h3>
161
The following example demonstrates using the XPath API to select one
162
or more nodes from an XML document:</p>
165
XPath xpath = XPathFactory.newInstance().newXPath();
166
String expression = "/widgets/widget";
167
InputSource inputSource = new InputSource("widgets.xml");
168
NodeSet nodes = (NodeSet) xpath.evaluate(expression, inputSource, XPathConstants.NODESET);
171
<h3>XPath Expressions and Types</h3>
173
<p>While XPath expressions select nodes in the XML document, the XPath
174
API allows the selected nodes to be coalesced into one of the
175
following other data types:</p>
178
<li><code>Boolean</code></li>
179
<li><code>Number</code></li>
180
<li><code>String</code></li>
183
<p>The desired return type is specified by a {@link
184
javax.xml.namespace.QName} parameter in method call used to evaluate
185
the expression, which is either a call to
186
<code>XPathExpression.evalute(...)</code> or to one of the
187
<code>XPath.evaluate(...)</code> convenience methods. The allowed
188
QName values are specified as constants in the {@link
189
javax.xml.xpath.XPathConstants} class; they are:</p>
192
<li>{@link javax.xml.xpath.XPathConstants#NODESET}</li>
193
<li>{@link javax.xml.xpath.XPathConstants#NODE}</li>
194
<li>{@link javax.xml.xpath.XPathConstants#STRING}</li>
195
<li>{@link javax.xml.xpath.XPathConstants#BOOLEAN}</li>
196
<li>{@link javax.xml.xpath.XPathConstants#NUMBER}</li>
199
<p>When a <code>Boolean</code> return type is requested,
200
<code>Boolean.TRUE</code> is returned if one or more nodes were
201
selected; otherwise, <code>Boolean.FALSE</code> is returned.</p>
203
<p>The <code>String</code> return type is a convenience for retrieving
204
the character data from a text node, attribute node, comment node, or
205
processing-instruction node. When used on an element node, the value
206
of the child text nodes is returned.
209
<p>The <code>Number</code> return type attempts to coalesce the text
210
of a node to a <code>double</code> data type.
213
<h3>XPath Context</h3>
215
<p>XPath location paths may be relative to a particular node in the
216
document, known as the <code>context</code>. Consider the following
222
<manufacturer/>
228
<p>The <code><widget></code> element can be selected with the
229
following XPath API code:</p>
232
// parse the XML as a W3C Document
233
DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
234
Document document = builder.parse(new File("/widgets.xml"));
236
XPath xpath = XPathFactory.newInstance().newXPath();
237
String expression = "/widgets/widget";
238
Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE);
241
<p>With a reference to the <code><widget></code> element, a
242
relative XPath expression can now written to select the
243
<code><manufacturer></code> child element:</p>
246
XPath xpath = XPathFactory.newInstance().newXPath();
247
<strong>String expression = "manufacturer";</strong>
248
Node manufacturerNode = (Node) xpath.evaluate(expression, <strong>widgetNode</strong>, XPathConstants.NODE);
252
<li>Author <a href="mailto:Ben@galbraiths.org">Ben Galbraith</a></li>
253
<li>Author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a></li>
254
<li>Author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a></li>
255
<li>See <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a></li>
added
removed
javax/xml/xpath/package.html
