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: 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.

XPath API - use-case
 

Assumptions and limitations

There is one general assumption: user cannot mix element created by different engines. In details:
  1. 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}).
  2. Value, variable map and execution unit works together only if they were created by the same engine class.
  3. 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: