--- old/src/java.xml/share/classes/javax/xml/xpath/package.html Wed Jan 21 21:16:34 2015 +++ new/src/java.xml/share/classes/javax/xml/xpath/package.html Wed Jan 21 21:16:34 2015 @@ -1,6 +1,8 @@ - + + + - - - - -javax.xml.xpath - - - - - + - - -

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 +

+ +

+ +

1. XPath Overview

-
- -

XPath Overview

-

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.

-

XPath Expressions

+ +

2. XPath Expressions

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']
+
-

Using the XPath API

+ +

3. XPath Data Types

-

-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);
-
- -

XPath Expressions and Types

-

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:

-

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:

- + +

3.1 QName types

+The XPath API defines the following {@link javax.xml.namespace.QName} types to +represent return types of an XPath evaluation: +

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.

+selected; otherwise, 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. -

-

XPath Context

+ +

3.2 Class types

+In addition to the QName types, the XPath API supports the use of Class types +through the XPathExpression.evaluteExpression(...) or +XPath.evaluateExpression(...) methods. +The XPath data types are mapped to Class types as follows: + + +

+Of the subtypes of Number, only Double, Integer and Long are supported. + + +

3.3 Enum types

+Enum types are defined in {@link javax.xml.xpath.XPathEvaluationResult.XPathResultType} +that provide mappings between the QName and Class types above. The result of +evaluating an expression using the XPathExpression.evaluteExpression(...) +or XPath.evaluateExpression(...) methods will be of one of these types. + + +

4. XPath Context

+

XPath location paths may be relative to a particular node in the -document, known as the context. Consider the following -XML document:

+document, known as the 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. + + +

5. Using the XPath API

+ +Consider the following XML document: +

+

 <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: +

+

+
+int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class);
+
+
+ +@since 1.5 +