XPath API definition - common interface to execute XPath 1.0 expressions.
Package Specification
Main concept of this package is to provide common interface for executing XPath 1.0 expressions
in Java code.
There are plenty of XPath 1.0 implementations, every uses different API. This module
introduces common API to use them.
It bases on abstract factory and facade design pattern. There is one entry point (a factory)
that creates all other objects. Objects have to implement common interfaces and
behaviour. By simply changing only factory instance in user code, user may switch from one XPath
implementation to another.
The main part is located directly in this package. It is a set of interfaces:
- {@link org.xdv.xpath.XPathEngine} - an entry point to use XPath implementation,
acts like an factory to all other kind of objects.
- {@link org.xdv.xpath.XPathExecutionUnit} – interface to execute XPath expressions.
- {@link org.xdv.xpath.XPathExpression} - XPath expression ready to execute.
- {@link org.xdv.xpath.XPathValue} - value, either a XPath result or a XPath variable value.
- {@link org.xdv.xpath.XPathVariableMap} - map to resolve variables in XPath expression.
An implementation of this API should be rather a wrapper that compacts and simplifies usage of one
existing XPath implementation, like Jaxen,
Saxon,
Xalan.
You can find a proper implementation of this API for
Jaxen XPath engine
in package {@link org.xdv.xpath.jaxen}.
It is an efficient and ready to use implementation for W3C DOM source.
Example, use case
Following sequence diagram shows simple example (use-case) that describes how to correctly
use this XPath API.
Assumptions and limitations
There is one general assumption: user cannot mix element created by different engines.
In details:
- Expression can be properly executed only by execution-unit created by the same engine instance.
Some implementations may relax this constraint - for instance they may require the same class
but not exacly the same instance (see implementation for Jaxen - {@link org.xdv.xpath.jaxen}).
- Value, variable map and execution unit works together only if they were created by the same
engine class.
- Variables in XPath expression are resolved at execution time.
It means that proper binding has to be provided at time then you actually execute expression
using execution unit, not at the time when you create expression using engine.
Some implementations may relax those constraints, but cannot tighten them.
Related Documentation
For overviews, examples please see:
- XPath 1.0 specification from W3C.
- {@link org.xdv.xpath.common} - some common classes that can be used across different
implementations.
- {@link org.xdv.xpath.jaxen} - implementation for Jaxen XPath engine.
A model implementation - please take a look at this implementation before you start
creating your own XPath implementation.
- General info - general information about this
documentation, global assumptions, etc.