* 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 {@code The expression {@code /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
* {@code
* A special location path operator, {@code //}, selects nodes at
* any depth in an XML document. The following example selects all
* {@code
* A wildcard operator, *, causes all element nodes to be selected.
* The following example selects all children elements of a
* {@code
* 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:
*
*
* Predicates allow for refining the nodes selected by an XPath
* location path. Predicates are of the form
*
* Predicates may be appended to each other to further refine an
* expression, such as:
*
*
* 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:
*
*
* 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
* {@code XPathExpression.evaluate(...)} or {@code XPath.evaluate(...)}
* methods.
*
*
* When a {@code Boolean} return type is requested,
* {@code Boolean.TRUE} is returned if one or more nodes were
* selected; otherwise, {@code Boolean.FALSE} is returned.
*
*
* The {@code 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 {@code Number} return type attempts to coalesce the text
* of a node to a {@code double} data type.
*
*
*
* Of the subtypes of {@code Number}, only {@code Double, Integer} and {@code Long} are supported.
*
*
*
* Note the differences between the Enum and QName
* mappings:
*
* XPath location paths may be relative to a particular node in the
* document, known as the {@code 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.
*
*
*
* The {@code
* With a reference to the {@code
* 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:
*
*
* 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:
*
* 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:
*
*
*
*
* <foo>
* <bar/>
* </foo>
*
*
*
*
*
* <foo>
* <bar/>
* <bar/>
* <bar/>
* </foo>
*
*
*
*
*
* //bar
*
*
*
*
*
* /foo/*
*
*
*
*
*
*
*
*
* Location Path
* Description
*
*
*
*
* /foo/bar/@id
*
* Selects the attribute {@code id} of the {@code
*
*
* /foo/bar/text()
*
* Selects the text nodes of the {@code
*
*
* /foo/bar/comment()
*
* Selects all comment nodes contained in the {@code
*
*
*
* /foo/bar/processing-instruction()
*
* Selects all processing-instruction nodes contained in the
* {@code
* [expression]. The following example selects all
* {@code
*
*
*
* //foo[@include='true']
*
*
*
*
*
*
* //foo[@include='true'][@mode='bar']
*
* 3. XPath Data Types
*
*
*
*
*
* 3.1 QName types
* The XPath API defines the following {@link javax.xml.namespace.QName} types to
* represent return types of an XPath evaluation:
*
*
*
* 3.2 Class types
* In addition to the QName types, the XPath API supports the use of Class types
* through the {@code XPathExpression.evaluateExpression(...)} or
* {@code XPath.evaluateExpression(...)} methods.
*
* The XPath data types are mapped to Class types as follows:
*
*
*
* 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 {@code XPathExpression.evaluateExpression(...)}
* or {@code XPath.evaluateExpression(...)} methods will be of one of these types.
*
*
*
*
*
* The Enum mapping for {@link javax.xml.xpath.XPathConstants#NUMBER NUMBER}
* supports {@code Double, Integer} and {@code Long}.
*
* The Enum mapping for {@link javax.xml.xpath.XPathConstants#NODESET NODESET}
* is {@link javax.xml.xpath.XPathNodes XPathNodes} instead of
* {@link org.w3c.dom.NodeList NodeList} in the
* QName mapping.
* 4. XPath Context
*
*
*
*
* 5. Using the XPath API
*
* Consider the following XML document:
*
*
*
*
* <widgets>
* <widget>
* <manufacturer/>
* <dimensions/>
* </widget>
* </widgets>
*
*
*
*
*
* // 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);
*
*
*
*
*
* 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);
*
*
*
*
*
* 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.evaluateExpression(expression, inputSource, XPathNodes.class);
*
*
*
*
*
* XPathEvaluationResult<?> result = xpath.evaluateExpression(expression, document);
* switch (result.type()) {
* case NODESET:
* XPathNodes nodes = (XPathNodes)result.value();
* ...
* break;
* }
*
*
*
*
* @since 1.5
*
*/
package javax.xml.xpath;
* int count = xpath.evaluateExpression("count(/widgets/widget)", document, Integer.class);
*
*