JXPath

Home

Information

Project Files

Downloads

About Us

Jakarta Community

What's JXPath

JXPath provides APIs for the traversal of graphs of JavaBeans, DOM and other types of objects using the XPath syntax.

If you are not familiar with the XPath syntax, start with XPath Tutorial by W3Schools.
Also see XML Path Language (XPath) Version 1.0 - that's the official standard.

XPath is the official expression language of XSLT. In XSLT you mostly use XPath to access various elements of XML documents. You can do that with JXPath as well. In addition, you can read and write properties of JavaBeans, get and set elements of arrays, collections, maps, transparent containers, various context objects in Servlets etc. In other words, JXPath applies the concepts of XPath to alternate object models.

You can also have JXPath create new objects if needed.

The central class in the JXPath architecture is JXPathContext. Most of the APIs discussed in this document have to do with the JXPathContext class.


Object Graph Traversal

JXPath uses JavaBeans introspection to enumerate and access JavaBeans properties.

The interpretation of the XPath syntax in the context of Java object graphs is quite intuitive: the "child" axis of XPath is mapped to JavaBean properties.

JavaBean Property Access

JXPath can be used to access properties of a JavaBean.

                                                                       
public class Employee {
    public String getFirstName(){
       ...
    }
}

Employee emp = new Employee();
...

JXPathContext context = JXPathContext.newContext(emp);
String fName = (String)context.getValue("firstName");

In this example, we are using JXPath to access a property of the emp bean. In this simple case the invocation of JXPath is equivalent to invocation of getFirstName() on the bean.


Lenient Mode

The context.getValue(xpath) method throws an exception if the supplied xpath does not map to an existing property. This constraint can be relaxed by calling context.setLenient(true). In the lenient mode the method merely returns null if the path maps to nothing.


Nested Bean Property Access

JXPath can traverse object graphs:

                                                                       
 public class Employee {
    public Address getHomeAddress(){
       ...
    }
 }
 public class Address {
    public String getStreetNumber(){
       ...
    }
 }

 Employee emp = new Employee();
 ...

 JXPathContext context = JXPathContext.newContext(emp);
 String sNumber = (String)context.getValue("homeAddress/streetNumber");
 

In this case XPath is used to access a property of a nested bean.

A property identified by the XPath does not have to be a "leaf" property. For instance, we can extract the whole Address object in above example:

                                                                       
    Address addr = (Address)context.getValue("homeAddress");
 

Collection Subscripts

JXPath can extract elements from arrays and collections.

                                                                       
 public class Integers {
    public int[] getNumbers(){
       ...
    }
 }

 Integers ints = new Integers();
 ...

 JXPathContext context = JXPathContext.newContext(ints);
 Integer thirdInt = (Integer)context.getValue("numbers[3]");
 

A collection can be an arbitrary array or an instance of java.util.Collection.

Note: in XPath the first element of a collection has index 1, not 0.


Retrieving Multiple Results

JXPath can retrieve multiple objects from a graph. Note that the method called in this case is not getValue, but iterate.

                                                                       
 public class Author {
    public Book[] getBooks(){
       ...
    }
 }

 Author auth = new Author();
 ...

 JXPathContext context = JXPathContext.newContext(auth);
 Iterator threeBooks = context.iterate("books[position() < 4]");
 

This returns a list of at most three books from the array of all books written by the author.


Map Element Access

JXPath supports maps. To get a value use its key.

                                                                       
 public class Employee {
    private Map addressMap = new HashMap();
    {
        addressMap.put("home", new Address(...));
        addressMap.put("office", new Address(...));
    }

    public Map getAddresses(){
       return addressMap;
    }
    ...
 }

 Employee emp = new Employee();
 JXPathContext context = JXPathContext.newContext(emp);
 String homeZipCode =
        (String)context.getValue("addresses/home/zipCode");
 

Often you will need to use the alternative syntax for accessing Map elements:

                                                                       
 String homeZipCode = (String)context.
        getValue("addresses[@name='home']/zipCode");
 

Unlike a child name in XPath, the value of the "name" attribute does not have to be a properly formed identifier. Also, in this case the key can be an expression, e.g. a variable.

The attribute "name" can be used not only with Maps, but with JavaBeans as well. The value of this attribute represents the name of a property.

Note: At this point JXPath only supports Maps that use strings for keys.

Note: JXPath supports the extended notion of Map: any object with dynamic properties can be handled by JXPath provided that its class is registered with the JXPathIntrospector.


DOM Document Access

JXPath supports access to DOM Nodes. The DOM node can be the context node of JXPathContext or it can be a value of a property, element of a collection, variable value etc. Let's say we have a path "$foo/bar/baz". It will work if, for instance, the value of the variable "foo" is a JavaBean, whose property "bar" contains a DOM Node, which has a child element named "baz".

The intepretation of XPath over DOM structures is implemented in with the XPath specification. For instance, the "attribute" axis is supported for DOM objects, even though it is not applicable to JavaBeans.


Containers

A Container is an object implementing an indirection mechanism transparent to JXPath.

For example, if property "foo" of the context node has a Container as its value, the XPath "foo" will produce the contents of that Container, not the container itself.

An example of a useful container is XMLDocumentContainer. When you create an XMLDocumentContainer, you give it a pointer to an XML file (a URL or a javax.xml.transform.Source. It will read and parse the XML file only when it is accessed. You can create XMLDocumentContainers for various XML documents that may or may not be accessed by XPaths. If they are, they will be automatically read, parsed and traversed. If they are not- they won't be read at all.

Let's say we have the the following XML file, which is stored as a Java resource.

                                                                       
    <?xml version="1.0" ?>
    <vendor>
      <location id="store101">
        <address>
          <street>Orchard Road</street>
        </address>
      </location>

      <location id="store102">
        <address>
          <street>Tangerine Drive</street>
        </address>
      </location>
    </vendor>

Here's the code that makes use of XMLDocumentContainer.

                                                                       
 class Company {
    private Container locations = null;

    public Container getLocations(){
        if (locations == null){
            URL url = getClass().getResource("Vendor.xml");
            locations = new XMLDocumentContainer(url);
        }
        return locations;
    }
 }
 ...
 context = JXPathContext.newContext(new Company());
 ...
 String street = (String)context.getValue(
                "locations/vendor/location[@id = 'store102']//street");

Like was described before, this code will implicitly open and parse the XML file and find a value in it according to the XPath.


Functions id() and key()

Functions id() and key() can be used with JXPath, however most of the time it requires custom coding.

The only situation where no custom coding is needed is when you want to use the id() function and you have a DOM Node as the context node of the JXPathContext. In this case, JXPath will use the standard behavior of DOM.

In order to evaluate the id() function, JXPath calls a delegate object that should be implemented and installed on the JXPathContext. The object should implement the IdentityManager interface.

Similarly, the key() function relies on a custom implementation of the KeyManager interface.


Note: JXPath does not support DOM attributes for non-DOM objects. Even though XPaths like "para[@type='warning']" are legitimate, they will always produce empty results. The only attributes supported for JavaBeans are "name" and "xml:lang".


Modifying Object Graphs

JXPath can also be used to modify parts of object graphs: property values, values for keys in Maps. It can in some cases create intermediate nodes in object graphs.

Setting Properties

JXPath can be used to modify property values.

                                                                       
 public class Employee {
    public Address getAddress() {
       ...
    }

    public void setAddress(Address address) {
       ...
    }
 }

 Employee emp = new Employee();
 Address addr = new Address();
 ...

 JXPathContext context = JXPathContext.newContext(emp);
 context.setValue("address", addr);
 context.setValue("address/zipCode", "90190");
 

Creating Objects

JXPath can be used to create new objects. First, create a subclass of AbstractFactory and install it on the JXPathContext. Then call jxPathContext.createPath(xpath). JXPathContext will invoke your AbstractFactory when it discovers that an intermediate node of the path is null. It will not override existing nodes.

                                                                       
 public class AddressFactory extends AbstractFactory {
    public boolean createObject(JXPathContext context, Pointer pointer,
                                Object parent, String name, int index){
     if ((parent instanceof Employee) && name.equals("address"){
       ((Employee)parent).setAddress(new Address());
       return true;
     }
     return false;
   }
 }

 JXPathContext context = JXPathContext.newContext(emp);
 context.setFactory(new AddressFactory());
 context.createPath("address");

You can also combine creating a path with setting the value of the leaf: the createPathAndSetValue(path, value) method is used for that.

                                                                       
 context.createPathAndSetValue("address/zipCode", "90190");

Note that it only makes sense to the automatic creation of nodes with very simple paths. In fact, JXPath will not attempt to create intermediate nodes for paths that don't follow these rules:

  • The only axis used is "child::", e.g. "foo/bar/baz"
  • The only two types of predicates used are context-independent indexing and the "[@name = expr]" construct, e.g. "map[@name='key1'][4/2]".
  • If a variable is used, it is the root of the path, e.g. "$object/child".



Variables

JXPath supports the notion of variables. The XPath syntax for accessing variables is "$varName".

                                                                       
 public class Author {
    public Book[] getBooks(){
       ...
    }
 }

 Author auth = new Author();
 ...

 JXPathContext context = JXPathContext.newContext(auth);
 context.getVariables().declareVariable("index", new Integer(2));

 Book secondBook = (Book)context.getValue("books[$index]");
 

You can also set variables using JXPath:

                                                                       
 context.setValue("$index", new Integer(3));
 

Note: generally speaking, you can only change the value of an existing variable this way, you cannot define a new variable. If you do want to define a new variable dynamically, implement a defineVariable() method on your custom AbstractFactory and call createPathAndSetValue() rather than setValue(). The restrictions described in the "Creating Objects" section still apply.

When a variable contains a JavaBean or a collection, you can traverse the bean or collection as well:

                                                                       
 ...
 context.getVariables().declareVariable("book", myBook);
 String title = (String)context.getValue("$book/title);

 Book array[] = new Book[]{...};

 context.getVariables().declareVariable("books", array);

 String title = (String)context.getValue("$books[2]/title);
 

Custom Variable Pools

By default, JXPathContext creates a HashMap of variables. However, you can substitute a custom implementation of the Variables interface to make JXPath work with an alternative source of variables. For example, you can define implementations of Variables that cover a servlet context, HTTP request or any similar structure.

See the org.apache.commons.jxpath.servlet package for an example of just that.



Servlet Contexts

The org.apache.commons.jxpath.servlet package contains classes that make it easy to use XPath to access values in various sevlet contexts: "page" (for JSPs), "request", "session" and "application".

See static methods of the class JXPathServletContexts. They allocate various servlet-related JXPathContexts.

JSP Page Context

The JXPathContext returned by getPageContext(PageContext pageContext) provides access to all scopes via the PageContext.findAttribute() method. Thus, an expression like "foo" will first look for the attribute named "foo" in the "page" context, then the "request" context, then the "session" one and finally in the "application" context.

If you need to limit the attibute lookup to just one scope, you can use the pre-definded variables "page", "request", "session" and "application". For example, the expression "$session/foo" extracts the value of the session attribute named "foo".


Servlet Request Context

The getRequestContext(ServletRequest request, ServletContext servletContext) method will give you a context that checks the request scope first, then (if there is a session) the session context, then the application context.


HttpSession Context

The getSessionContext(HttpSession session, ServletContext servletContext) method will give you a context that checks the session context, then the application context.


ServletContext Context

Finally, getApplicationContext(ServletContext servletContext) method will give you a context that checks the application context.


All these methods cache the JXPathContexts they create within the corresponding scopes. Subsequent calls use the JXPathContexts created earlier.


Pointers

JXPath supports so called Pointers. A Pointer is an object that represents a location of a node in an object graph. For example, you can call

                                                                       
Pointer ptr = context.getPointer("employees[$i]/addresses[$j]")

Let's say the value of the variable i is 1 and j = 3. If we call ptr.asPath(), it returns an XPath that describes this concrete location: "/employees[1]/addresses[3]".

If you have an XPath that finds many nodes in the graph, you can get JXPath to produce a collection of pointers for all of those found locations:

                                                                       
List homeAddresses = context.getPointer("//employee/address[@name='home']");

Each Pointer in the list will map to a home address object in the graph.

It is a good idea to use pointers whenever you need to access the same node of a graph repeatedly.

Also, when an XPath is repeatedly evaluated in different contexts (for example, with different variable values) and you need to preseve results of those evaluations. A Pointer, as well as the XPath produced by pointer.asPath() is context-independent, it won't change if involved variables or expressions change.

JXPath is optimized to interpret XPaths produced by Pointers much faster than many other types of XPaths.


Extension Functions

JXPath supports standard XPath functions right out of the box. It also supports "standard" extension functions, which are basically a bridge to Java as well as entirely custom extension functions.

Standard Extension Functions

Using the standard extension functions, you can call methods on objects, static methods on classes and create objects using any constructors. All class names should be fully qualified.

Here's how you can create new objects:

                                                                       
 Book book = (Book)context.
   getValue("com.myco.books.Book.new('John Updike')");

Here's how you can call static methods:

                                                                       
 Book book = (Book)context.
   getValue("com.myco.books.Book.getBestBook('John Updike')");

Here's how you can call regular methods:

                                                                       
 String firstName = (String)context.
   getValue("getAuthorsFirstName($book)");
 

As you can see, the target of the method is specified as the first parameter of the function.


Custom Extension Functions

Collections of custom extension functions can be implemented as Functions objects or as Java classes, whose methods become extenstion functions.

Let's say the following class implements various formatting operations:

                                                                       
 public class Formats {
    public static String date(Date d, String pattern){
        return new SimpleDateFormat(pattern).format(d);
    }
    ...
 }

We can register this class with a JXPathContext:

                                                                       
 context.setFunctions(new ClassFunctions(Formats.class, "format"));
 ...

 context.getVariables().declareVariable("today", new Date());
 String today =
     (String)context.getValue("format:date($today, 'MM/dd/yyyy')");

You can also register whole packages of Java classes using PackageFunctions.

Also, see FunctionLibrary, which is a class that allows you to register multiple sets of extension functions with the same JXPathContext.


Expression Context

A custom function can get access to the context in which it is being evaluated. ClassFunctions and PackageFunctions have special support for methods and constructors that have ExpressionContext as the first argument. When such extension function is invoked, it is given an object that implements the ExpressionContext interface. The function can then gain access to the "current" object in the currently evaluated context.

                                                                       
public class MyExtenstionFunctions {
   public static boolean isDate(ExpressionContext context){
      Pointer pointer = context.getContextNodePointer();
      if (pointer == null){
        return false;
      }
      return pointer.getValue() instanceof Date;
   }
   ...
}

You can then register this extension function using ClassFunctions and call it like this:

                                                                       
  "//.[myext:isDate()]"

This expression will find all nodes of the graph that are dates.

The current context is passed to an extension function by default. Any other context can be passed as an explicit argument declared as ExpressionContext. Note, that if the first argument is ExpressionContext, it is always passed the current context. Therefore, you may need to declare two ExpressionContext arguments- one for the current and one for the parameter context. For example,

                                                                       
public class MyExtenstionFunctions {
   ...
   public static boolean contains(ExpressionContext current,
                            ExpressionContext context, Object value){
      Iterator iter = context.getContextNodeList().iterator();
      while (iter.hasNext()) {
          Pointer item = (Pointer)iter.next();
          if (item.getValue().equals(value)){
            return true;
          }
      }
      return false;
   }
}

You can call this function to find all people who have a certain phone number:

                                                                       
  "/addressBook/contact[myext:contains(phoneNumbers, '555-5555']"


Type Conversions

JXPath automatically performs the following type convertions:

From type To type Operation
null primitive false, zero
any String Calls toString()
Boolean any Number True = 1, false = 0
any Number any other Number Truncates if needed
String any primitive type Parses the string
array of length 1 any Takes the single element of the array
and (recursively) converts it to the needed type
collection of size 1 any Takes the single element of the array
and (recursively) converts it to the needed type
array array Creates a new array of the same size and converts every element
array Collection Creates a collection and adds to it all elements of the array. Note that it will only know how to create the collection if the type is a concrete class, List or Set
Collection array Creates a new array the same size as the collection, converts and copies every element of the collection into the array.
Collection Collection Creates a collection and copies the source collection into the new collection. Note that it will only know how to create the collection if the type is a concrete class, List or Set
ExpressionContext Collection, List, Vector, Set Creates a collection of type ArrayList,
ArrayList, Vector, HashSet respectively and
populates it with all current context node pointers
ExpressionContext any Obtains value of the current context node pointer
and (recursively) converts it to the needed type


Internationalization

For DOM Documents JXPathContext supports internationalization XPath-style. A locale can be declared on an XML Element like this:

                                                                       
     <book xml:lang="fr">Les Miserables</book>

You can then use the lang function in XPath to find nodes for a specific language:

                                                                       
     "//book[lang('fr')]

The "lang" boolean function is supported for non-DOM objects as well. It tests the Locale set on the JXPathContext (or the default locale). See JXPathContext.setLocale().

You can also utilize the xml:lang attribute, whose value is the name of the locale, whether in a DOM document or outside.


Nested Contexts

If you need to use the same set of variables while interpreting XPaths with different beans, it makes sense to put the variables in a separate context and specify that context as a parent context every time you allocate a new JXPathContext for a JavaBean. This way you don't need to waste time fully configuring every context.

The same logic applies to shared extension functions, abstract factories and locale.

                                                                       
 JXPathContext sharedContext = JXPathContext.newContext(null);
 sharedContext.getVariables().declareVariable("title", "Java");
 sharedContext.setFunctions(new MyExtensionFunctions());
 sharedContext.setLocale(Locale.CANADA);
 sharedContext.setFactory(new MyFactory());

 ...

 JXPathContext context = JXPathContext.newContext(sharedContext, auth);

 Iterator javaBooks =
      context.iterate("books[preprocessTitle(title) = $title]");
 


Compiled Expressions

When JXPath is asked to evaluate an expression for the first time, it compiles it and caches its compiled representation. This mechanism reduces the overhead caused by compilation. In some cases though, JXPath's own caching may not be sufficient- JXPath caches have limited size and they are cleared once in a while.

Here's how you can precompile an XPath expression:

                                                                       
     CompiledExpression expr = context.compile(xpath);
     ...
     Object value = expr.getValue(context);

The following requirements can be addressed with compiled expressions:

  • There is a relatively small number of XPaths your application works with, and it needs to evaluate those XPaths multiple times.
  • Some XPaths need to be precompiled at initialization time
  • The syntax of some XPaths needs to be checked before they are used for the first time


Customizing JXPath

JXPath can be customized on several levels.

  • You can provide custom JXPathBeanInfo objects to customize lists of properties of JavaBeans available to JXPath.
  • You can easily add support for object types similar to Map. All you need to do is implement the DynamicPropertyHandler interface and register the implementation with JXPathIntrospector.
  • You can add support for types of object models JXPath does not support out of the box. An example of such model would be an alternative implementation of XML parse tree (e.g. JDOM etc). You will need to implement one or two APIs to allow JXPath to traverse properties of these custom objects.
  • The most dramatic customization of JXPath can be done at the level of JXPathContextFactory- you can transparently provide an alternative implementation of all top level APIs.
Custom JXPathBeanInfo

JXPath uses JavaBeans introspection to discover properties of JavaBeans. You can provide alternative property lists by supplying custom JXPathBeanInfo classes (see JXPathBeanInfo).


Custom DynamicPropertyHandler

JXPath uses various implementations of the DynamicPropertyHandler interface to access properties of objects similar to Map.

The org.apache.commons.jxpath.servlet package has several examples of custom DynamicPropertyHandlers.


Custom Pointers and Iterators

Architecturally, multiple model support is made possible by the notions of a NodePointer and NodeIterator, which are simple abstract classes that are extended in different ways to traverse graphs of objects of different kinds. The NodePointer/NodeIterator APIs are designed with models like JavaBeans in mind. They directly support indexed collections. As a result, XPaths like "foo[10]" can be executed as "getFoo(9)" or "getFoo()[9]", or "getFoo().get(9)", depending on the type of collection. This flexibility is disguised well enough by the APIs of the abstract classes, so we can still have a natural implementation of traversal of object models, such as DOM, that do not have the same notion of collection.

To add support for a new object model, build custom implementations of NodePointer and NodeIterator as well as NodePointerFactory. Then register the new factory with JXPathContextReferenceImpl.

See existing NodePointerFactories for examples of how that's done:

  • BeanPointerFactory works with JavaBeans
  • DynamicPointerFactory works with Dynamic beans like Map, HttpRequest and such
  • ContainerPointerFactory works with Container objects like XMLDocumentContainer
  • DOMPointerFactory works with DOM Nodes


Alternative JXPath Implementation

JXPathContext allows alternative implementations. This is why instead of allocating JXPathContext directly, you should call a static newContext method. This method will utilize the JXPathContextFactory API to locate a suitable implementation of JXPath. JXPath comes bundled with a default implementation called Reference Implementation.




Copyright © 1999-2002, Apache Software Foundation