--- old/src/java.xml/share/classes/javax/xml/xpath/package.html Fri Jan 16 18:28:45 2015 +++ new/src/java.xml/share/classes/javax/xml/xpath/package.html Fri Jan 16 18:28:44 2015 @@ -1,6 +1,8 @@ - + + +
- - - - -This package provides an object-model neutral API for the +This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment. -
-The following XML standards apply:
++The XPath API supports + XML Path Language (XPath) Version 1.0 +
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, @@ -67,7 +69,8 @@ replace many lines of DOM API code.
-An XPath expression is composed of a location path and one or more optional predicates. Expressions @@ -76,18 +79,22 @@
The following is an example of a simple XPath expression:
+/foo/bar+
This example would select the <bar>
element in
an XML document such as the following:
<foo> -<bar/> + <bar/> </foo>+
The expression /foo/bar
is an example of a location
path. While XPath location paths resemble Unix-style file system
@@ -96,13 +103,15 @@
<bar>
elements in the following document would be
selected by the /foo/bar
expression:
<foo> -<bar/> -<bar/> -<bar/> + <bar/> + <bar/> + <bar/> </foo>+
A special location path operator, //
, selects nodes at
any depth in an XML document. The following example selects all
@@ -109,17 +118,21 @@
<bar>
elements regardless of their location in a
document:
//bar+
A wildcard operator, *, causes all element nodes to be selected.
The following example selects all children elements of a
-<foo>
element:
<foo>
element:
+/foo/*+
In addition to element nodes, XPath location paths may also address
attribute nodes, text nodes, comment nodes, and processing instruction
@@ -166,35 +179,27 @@
<foo>
elements that contain an include
attribute with the value of true
:
//foo[@include='true']+
Predicates may be appended to each other to further refine an expression, such as:
+-//foo[@include='true'][@mode='bar']+
-The following example demonstrates using the XPath API to select one -or more nodes from an XML document:
- --XPath xpath = XPathFactory.newInstance().newXPath(); -String expression = "/widgets/widget"; -InputSource inputSource = new InputSource("widgets.xml"); -NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET); -- -
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:
+following data types:Boolean
String
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
-XPathExpression.evalute(...)
or to one of the
-XPath.evaluate(...)
convenience methods. The allowed
-QName values are specified as constants in the {@link
-javax.xml.xpath.XPathConstants} class; they are:
The 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
+XPathExpression.evalute(...)
or XPath.evaluate(...)
+methods.
+
When a Boolean
return type is requested,
Boolean.TRUE
is returned if one or more nodes were
-selected; otherwise, Boolean.FALSE
is returned.
Boolean.FALSE
is returned.
The String
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.
-
The Number
return type attempts to coalesce the text
of a node to a double
data type.
-
XPathExpression.evaluteExpression(...)
or
+XPath.evaluateExpression(...)
methods.
+The XPath data types are mapped to Class types as follows:
+Boolean
-- Boolean.class
Number
-- Number.class
String
-- String.class
Nodeset
-- XPathNodes.class
Node
-- Node.class
+Of the subtypes of Number, only Double, Integer and Long are supported. + + +
XPathExpression.evaluteExpression(...)
+or XPath.evaluateExpression(...)
methods will be of one of these types.
+
+
+XPath location paths may be relative to a particular node in the
-document, known as the context
. Consider the following
-XML document:
context
. A context consists of:
++It is an XML document tree represented as a hierarchy of nodes, a +{@link org.w3c.dom.Node} for example, in the JDK implementation. + + +
+
-<widgets> <widget> @@ -246,36 +292,88 @@ </widget> </widgets>+
The <widget>
element can be selected with the
-following XPath API code:
+The <widget>
element can be selected with the following process:
+
// parse the XML as a W3C Document DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder(); Document document = builder.parse(new File("/widgets.xml")); +//Get an XPath object and evaluate the expression XPath xpath = XPathFactory.newInstance().newXPath(); String expression = "/widgets/widget"; Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE); + +//or using the evaluateExpression method +Node widgetNode = xpath.evaluateExpression(expression, document, Node.class);+
With a reference to the <widget>
element, a
-relative XPath expression can now written to select the
+relative XPath expression can be written to select the
<manufacturer>
child element:
-XPath xpath = XPathFactory.newInstance().newXPath(); String expression = "manufacturer"; Node manufacturerNode = (Node) xpath.evaluate(expression, widgetNode, XPathConstants.NODE); + +//or using the evaluateExpression method +Node manufacturerNode = xpath.evaluateExpression(expression, widgetNode, Node.class);+
+In the above example, the XML file is read into a DOM Document before being passed +to the XPath API. The following code demonstrates the use of InputSource to +leave it to the XPath implementation to process it: + +
++ ++XPath xpath = XPathFactory.newInstance().newXPath(); +String expression = "/widgets/widget"; +InputSource inputSource = new InputSource("widgets.xml"); +NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET); + +//or using the evaluateExpression method +XPathNodes nodes = xpath.evaluate(expression, inputSource, XPathNodes.class); ++
+In the above cases, the type of the expected results are known. In case where +the result type is unknown or any type, the {@link javax.xml.xpath.XPathEvaluationResult} +may be used to determine the return type. The following code demonstrates the usage: +
++ ++XPathEvaluationResult<?> result = xpath.evaluateExpression(expression, document); +switch (result.type()) { + case NODESET: + XPathNodes nodes = (XPathNodes)result.value(); + ... + break; +} ++
+The XPath 1.0 Number data type is defined as a double. However, the XPath +specification also provides functions that returns Integer type. To facilitate +such operations, the XPath API allows Integer and Long to be used in +{@code evaluateExpression} method such as the following code: +
+
++ +@since 1.5 ++int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class); ++