* 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, * 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. * * *
* 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. * * * *
* An XPath expression is composed of a location * path and one or more optional predicates. Expressions * may also include XPath variables. * * *
* 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/> * </foo> **
The expression /foo/bar 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
* all nodes that match the expression. Thus, all three
* <bar> elements in the following document would be
* selected by the /foo/bar expression:
*
*
** ** <foo> * <bar/> * <bar/> * <bar/> * </foo> **
* A special location path operator, //, selects nodes at
* any depth in an XML document. The following example selects all
* <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/* **
* 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: * *
| Location Path | *Description | *
|---|---|
* /foo/bar/@id
* |
*
* Selects the attribute id of the <bar> element
* |
*
/foo/bar/text()
* |
*
* Selects the text nodes of the <bar> element. No
* distinction is made between escaped and non-escaped character data.
* |
*
/foo/bar/comment()
* |
*
* Selects all comment nodes contained in the <bar> element.
* |
*
/foo/bar/processing-instruction()
* |
*
* Selects all processing-instruction nodes contained in the
* <bar> element.
* |
*
* Predicates allow for refining the nodes selected by an XPath
* location path. Predicates are of the form
* [expression]. The following example selects all
* <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'] **
* While XPath expressions select nodes in the XML document, the XPath * API allows the selected nodes to be coalesced into one of the * following data types: * *
BooleanNumberString
* 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.
*
*
* 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.classNumber -- Number.classString -- String.classNodeset -- XPathNodes.classNode -- 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. 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> * <manufacturer/> * <dimensions/> * </widget> * </widgets> **
* 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 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
*
*/
package javax.xml.xpath;