Using the JAXP XPath APIs
- Basic steps
- Plugging in the XPathFactory
- Using NamespaceContext
- Using XPathVariableResolver
- Using XPathFunctionResolver
- Using the sample XPathFunctionResolver
Basic steps
- Instantiate an XPathFactory
- Create an XPath
- (optional) Create an XPathExpression
- Evaluate the XPath expression in a specified context
The following example illustrates the basic steps involved in evaluating an XPath expression.
// 1. Instantiate an XPathFactory.
javax.xml.xpath.XPathFactory factory =
javax.xml.xpath.XPathFactory.newInstance();
// 2. Use the XPathFactory to create a new XPath object
javax.xml.xpath.XPath xpath = factory.newXPath();
// 3. Compile an XPath string into an XPathExpression
javax.xml.xpath.XPathExpression expression = xpath.compile("/doc/name");
// 4. Evaluate the XPath expression on an input document
String result = expression.evaluate(new org.xml.sax.InputSource("foo.xml"));
1. Instantiate an XPathFactory
XPathFactory is an abstract class with two static newInstance() methods (newInstance() and newInstance(String uri)) that instantiate the concrete subclass designated as the javax.xml.xpath.XPathFactory service provider. The optional parameter uri specifies the object model. The implementation in Xalan-Java 2 only supports the W3C DOM object model, identified by the URI DEFAULT_OBJECT_MODEL_URI.
The default service provider for the javax.xml.xpath.XPathFactory service is org.apache.xpath.jaxp.XPathFactoryImpl.
2. Create an XPath
You can use the XPathFactory.newXPath() method to create a new XPath. 3. (optional) Create an XPathExpression
You can use the XPath.compile(String expression) method to compile an XPath string into an XPathExpression object for later evaluation. This is an optional step. You can evaluate an XPath expression without compiling it first. 4. Evaluate an XPath expression
If you compile an XPath String into an XPathExpression in step 3, you can use one of the four evaluate() methods in the XPathExpression interface to evaluate the XPath expression. If the evaluation context is a W3C Node in an existing Document, you can use the evaluate(Object item) or evaluate(Object item, QName returnType) method by passing the context item as the first parameter. The method with a returnType parameter allows you to specify the return type as one of the following supported return types:
If the returnType parameter is not specified, the default is XPathConstants.STRING.
If the evaluation context is an input document, you can use one of the two evaluate() methods with an InputSource parameter (evaluate(InputSource source) or evaluate(InputSource source, QName returnType)) to evaluate the XPath expression.
The compiling step allows you to reuse an XPath expression for evaluation on multiple contexts. If an XPath expression is only used once, you can use one of the four evaluate() methods in the XPath interface to evaluate the XPath expression without compiling it first.
Plugging in the XPathFactory
The Java API for XML Processing interfaces enable you to plug in your own implementation of XPathFactory. The abstract class XPathFactory has a static newInstance() method that instantiates a concrete Factory which wraps the underlying implementation. The newInstance() method uses system property settings to determine which implementation to instantiate.
Xalan-Java 2 is distributed with a pre-configured setting for the provider of the XPathFactory service. This setting is in xalan.jar in META-INF/services/javax.xml.xpath.XPathFactory, with a value of org.apache.xpath.jaxp.XPathFactoryImpl.
You can plug in a new XPathFactory as follows (in order of precedence):
- Set the system property "javax.xml.xpath.XPathFactory" + ":uri" from the command line when you
launch Java or from within your application, where uri is the URI of the underlying object model. The URI of
the default W3C DOM object model is
http://java.sun.com/jaxp/xpath/dom. - Set the property in jaxp.properties in the JAVA_HOME/lib directory, where JAVA_HOME is the root of the JDK.
- Revise the entry in src/META-INF/services/javax.xml.xpath.XPathFactory and rebuild xalan.jar. Each potential service
provider entry in this file is required to implement the method
isObjectModelSupported(String objectModel).The first service provider found in class loader order that supports the specified object model will be used.
Using NamespaceContext
If namespace prefixes are used in an XPath expression, the XPath processor needs to know what namespace URIs the prefixes are bound to. Logically a prefix can only be bound to a single Namespace URI in the current scope. However, a Namespace URI can be bound to multiple prefixes in the current scope. The information about namespace prefix to URI mappings is provided by an object that implements the javax.xml.namespace.NamespaceContext interface.
Suppose you want to evaluate the XPath expression "/foo:document/bar:element" on the following xml document:
<?xml version='1.0'?>
<foo:document xmlns:foo="http://apache.org/foo" xmlns:bar="http://apache.org/bar">
<bar:element>MyBar</bar:element>
</foo:document>
You need to create your own implementation of NamespaceContext to inform the XPath processor what namespace URIs the prefixes are bound to. For the example above, you can create a NamespaceContext implementation as follows:
public class MyNamespaceContext implements NamespaceContext
{
public String getNamespaceURI(String prefix)
{
if (prefix.equals("foo"))
return "http://apache.org/foo";
else if (prefix.equals("bar"))
return "http://apache.org/bar";
else
return XMLConstants.NULL_NS_URI;
}
public String getPrefix(String namespace)
{
if (namespace.equals("http://apache.org/foo"))
return "foo";
else if (namespace.equals("http://apache.org/bar"))
return "bar";
else
return null;
}
public Iterator getPrefixes(String namespace)
{
return null;
}
}
Then you can use the XPath.setNamespaceContext(NamespaceContext nsContext) method to set the NamespaceContext on the XPath object you create using the basic steps.
The XPath processor in Xalan-Java 2 only uses the getNamespaceURI(String prefix) method on NamespaceContext. The other two methods getPrefix(String namespace) and getPrefixes(String namespace) are not used. If the NamespaceContext object is only used by the XPath processor, you can let the unused methods return null for simplicity.
Using XPathVariableResolver
XPathVariableResolver provides access to the set of user defined XPath variables. If an XPath expression contains a variable reference, we need to set a XPathVariableResolver on the XPath object using the XPath.setXPathVariableResolver(XPathVariableResolver resolver) method. You can also set the XPathVariableResolver on the XPathFactory, using the XPathFactory.setXPathVariableResolver(XPathVariableResolver resolver) method. If the XPathVariableResolver is set on the XPathFacory, then all XPath objects constructed from this XPathFactory will use the specified XPathVariableResolver by default. The XPath processor uses the XPathVariableResolver to retrieve the value of a user defined variable. In the course of evaluating any single XPath expression, a variable's value must be immutable.
Suppose that the XPath expression to be evaluated is "$x + $y", we need to provide a XPathVariableResolver
implementation from which the values of the variable x and y can be retrieved. For this example, the
XPathVariableResolver implementation can be written as follows:
public class MyVariableResolver implements XPathVariableResolver
{
public Object resolveVariable(QName var)
{
if (var == null)
throw new NullPointerException("The variable name cannot be null");
if (var.equals(new QName("x")))
return new Integer(2);
else if (var.equals(new QName("y")))
return new Integer(3);
else
return null;
}
}
Using XPathFunctionResolver
XPathFunctionResolver provides access to the set of user defined XPathFunctions. If an XPath expression contains an extension function, you can use the XPath.setXPathFunctionResolver(XPathFunctionResolver resolver) method to set a XPathFunctionResolver on the XPath object. You can also use the XPathFactory.setXPathFunctionResolver(XPathFunctionResolver resolver) method to set a XPathFunctionResolver on the XPathFactory, in which case all XPath objects constructed from this XPathFactory will use the specified XPathVariableResolver by default.
The XPathFunctionResolver interface only has one method:
public XPathFunction resolveFunction(QName functionName, int arity)
This method returns a XPathFunction object from the given function name and arity. XPath functions are resolved by name and arity. The parameter types have no impact here. XPathFunctionResolver is only used for functions with an explicit prefix. It is not needed for XPath built-in functions and it cannot be used to override those functions.
The XPathFunction interface has only one method:
public java.lang.Object evaluate(java.util.List args) throws XPathFunctionException
The function parameters are passed in using the args parameter as a java.util.List. And the method returns the result of evaluating the XPath function as an Object.
To support the use of extension functions in an XPath expression, a user needs to provide implementations of the XPathFunctionResolver and XPathFunction interfaces. The resolveFunction method of the XPathFunctionResolver implementation should return an object of a class that implements the XPathFunction interface.
Suppose we want to evaluate the XPath expression "ext:myAdditionFunction(2, 3)", and the purpose
of the extension function is simply to return the sum of the two parameters. Because an extension function
always has an explicit prefix, we also need to implement the NamespaceContext interface to provide a namespace
prefix to URI mapping. For this example, we need to implement three interfaces: NamespaceContext,
XPathFunctionResolver and XPathFunction. A sample implementation is as follows:
public class MyNamespaceContext implements NamespaceContext
{
public String getNamespaceURI(String prefix)
{
if (prefix == null)
throw new IllegalArgumentException("The prefix cannot be null.");
if (prefix.equals("ext"))
return "http://ext.com";
else
return null;
}
public String getPrefix(String namespace)
{
if (namespace == null)
throw new IllegalArgumentException("The namespace uri cannot be null.");
if (namespace.equals("http://ext.com"))
return "ext";
else
return null;
}
public Iterator getPrefixes(String namespace)
{
return null;
}
}
/**
* The XPathFunctionResolver implementation is used to evaluate
* the extension function "ext:myAdditionFunction(2, 3)".
*/
public class MyFunctionResolver implements XPathFunctionResolver
{
/**
* This method returns a customized XPathFunction implementation
* for the extension function "ext:myAdditionFunction(2, 3)".
*/
public XPathFunction resolveFunction(QName fname, int arity)
{
if (fname == null)
throw new NullPointerException("The function name cannot be null.");
// We only recognize one function, i.e. ex:addFunc().
if (fname.equals(new QName("http://ext.com", "myAdditionFunction", "ext")))
/**
* Return a customized implementation of XPathFunction. We need
* to implement the evaluate(List) method.
*/
return new XPathFunction() {
/**
* The actual implementation of the extension function.
* Just cast two arguments to Double and add them together.
*/
public Object evaluate(java.util.List args) {
if (args.size() == 2) {
Double arg1 = (Double)args.get(0);
Double arg2 = (Double)args.get(1);
return new Double(arg1.doubleValue() + arg2.doubleValue());
}
else
return null;
}
};
else
return null;
}
}
Using the sample XPathFunctionResolver
Normally you need to provide your own implementation of XPathFunctionResolver in order to use extension functions in XPath expressions. In Xalan-Java 2, we provide a sample implementation of XPathFunctionResolver in the class org.apache.xalan.extensions.XPathFunctionResolverImpl, with supports for Java and EXSLT extensions. If you set the XPathFunctionResolver to an object of this class, then you can use Java and EXSLT extension functions in the XPath expression. You also need to use a NamespaceContext along with the sample XPathFunctionResolver. Xalan-Java 2 also includes a sample implementation of NamespaceContext in org.apache.xalan.extensions.ExtensionNamespaceContext, which provides the following namespace prefix to URI mappings:
| Prefix | URI |
|---|---|
| java | http://xml.apache.org/xalan/java |
| exslt | http://exslt.org/common |
| math | http://exslt.org/math |
| set | http://exslt.org/sets |
| str | http://exslt.org/strings |
| dyn | http://exslt.org/dynamic |
| datetime | http://exslt.org/dates-and-times |
Suppose you want to evaluate the XPath expression "math:max(/doc/num)", which contains
an EXSLT extension call. Here the prefix "math" corresponds to the URI "http://exslt.org/math".
The following code snippet demonstrates how to use the sample XPathFunctionResolver to evaluate the
XPath expression above:
XPathFactory factory = XPathFactory.newInstance();
XPath xpath = factory.newXPath();
// set the NamespaceContext to
// org.apache.xalan.extensions.ExtensionNamespaceContext
xpath.setNamespaceContext(new org.apache.xalan.extensions.ExtensionNamespaceContext());
// set the XPathFunctionResolver to
// org.apache.xalan.extensions.XPathFunctionResolverImpl
xpath.setXPathFunctionResolver(new org.apache.xalan.extensions.XPathFunctionResolverImpl());
// Evaluate the XPath expression "math:max(/doc/num)" against
// the input document numlist.xml
Object result = xpath.evaluate("math:max(/doc/num)", new InputSource("numlist.xml"), XPathConstants.NUMBER);