javax.xml.xpath.package-info Maven / Gradle / Ivy
Show all versions of qbicc-rt-java.xml Show documentation
/*
* Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
*
* Provides an object-model neutral API for the
* evaluation of XPath expressions and access to the evaluation
* environment.
*
*
* The XPath API supports
* XML Path Language (XPath) Version 1.0
*
*
*
*
* - 1. XPath Overview
* - 2. XPath Expressions
* - 3. XPath Data Types
*
*
* - 4. XPath Context
* - 5. Using the XPath API
*
* 1. 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,
* 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.
*
*
*
*
2. XPath Expressions
*
*
* 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 } element in
* an XML document such as the following:
*
*
*
* <foo>
* <bar/>
* </foo>
*
*
*
* 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 } elements in the following document would be
* selected by the {@code /foo/bar} expression:
*
*
*
* <foo>
* <bar/>
* <bar/>
* <bar/>
* </foo>
*
*
*
*
* A special location path operator, {@code //}, selects nodes at
* any depth in an XML document. The following example selects all
* {@code } 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
* {@code } 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:
*
*
* Examples of Location Path
*
*
* Location Path
* Description
*
*
*
*
*
* /foo/bar/@id
*
*
* Selects the attribute {@code id} of the {@code } element
*
*
*
* /foo/bar/text()
*
* Selects the text nodes of the {@code } element. No
* distinction is made between escaped and non-escaped character data.
*
*
*
* /foo/bar/comment()
*
* Selects all comment nodes contained in the {@code } element.
*
*
*
* /foo/bar/processing-instruction()
*
* Selects all processing-instruction nodes contained in the
* {@code } element.
*
*
*
*
*
*
* Predicates allow for refining the nodes selected by an XPath
* location path. Predicates are of the form
* [expression]. The following example selects all
* {@code } elements that contain an {@code include}
* attribute with the value of {@code true}:
*
*
*
* //foo[@include='true']
*
*
*
*
* Predicates may be appended to each other to further refine an
* expression, such as:
*
*
*
* //foo[@include='true'][@mode='bar']
*
*
*
*
* 3. XPath Data 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 data types:
*
*
* - {@code Boolean}
* - {@code Number}
* - {@code String}
*
*
*
* 3.1 QName types
* The XPath API defines the following {@link javax.xml.namespace.QName} types to
* represent return types of an XPath evaluation:
*
* - {@link javax.xml.xpath.XPathConstants#NODESET}
* - {@link javax.xml.xpath.XPathConstants#NODE}
* - {@link javax.xml.xpath.XPathConstants#STRING}
* - {@link javax.xml.xpath.XPathConstants#BOOLEAN}
* - {@link javax.xml.xpath.XPathConstants#NUMBER}
*
*
*
* 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.evalute(...)} 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.
*
*
*
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:
*
* - {@code Boolean} -- {@code Boolean.class}
* - {@code Number} -- {@code Number.class}
* - {@code String} -- {@code String.class}
* - {@code Nodeset} -- {@code XPathNodes.class}
* - {@code Node} -- {@code Node.class}
*
*
*
* Of the subtypes of {@code Number}, only {@code Double, Integer} and {@code 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 {@code XPathExpression.evaluateExpression(...)}
* or {@code XPath.evaluateExpression(...)} methods will be of one of these types.
*
* Note the differences between the Enum and QName
* mappings:
*
* - {@link javax.xml.xpath.XPathConstants#NUMBER NUMBER}
* The Enum mapping for {@link javax.xml.xpath.XPathConstants#NUMBER NUMBER}
* supports {@code Double, Integer} and {@code Long}.
*
* - {@link javax.xml.xpath.XPathConstants#NODESET NODESET}
* 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
*
*
* XPath location paths may be relative to a particular node in the
* document, known as the {@code context}. A context consists of:
*
* - a node (the context node)
* - a pair of non-zero positive integers (the context position and the context size)
* - a set of variable bindings
* - a function library
* - the set of namespace declarations in scope for the expression
*
*
*
* 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>
* <manufacturer/>
* <dimensions/>
* </widget>
* </widgets>
*
*
*
*
* The {@code } 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 {@code } element, a
* relative XPath expression can be written to select the
* {@code } 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.evaluateExpression(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.evaluateExpression("count(/widgets/widget)", document, Integer.class);
*
*
*
* @since 1.5
*
*/
package javax.xml.xpath;