org.apache.commons.jxpath.JXPathContext

Direct Known Subclasses:: JXPathContextReferenceImpl

public abstract class JXPathContext extends Object

JXPathContext provides APIs for the traversal of graphs of JavaBeans using the XPath syntax. Using JXPathContext, you can read and write properties of JavaBeans, arrays, collections and maps. JXPathContext uses JavaBeans introspection to enumerate and access JavaBeans properties.

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. Bundled with JXPath comes a default implementation called Reference Implementation.

JXPath Interprets XPath Syntax on Java Object Graphs

JXPath uses an intuitive interpretation of the XPath syntax in the context of Java object graphs. Here are some examples:

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

Example 2: 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");

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

Example 4: Map Element Access

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

 public class Employee {
    public Map getAddresses(){
       return addressMap;
    }

    public void addAddress(String key, Address address){
       addressMap.put(key, address);
    }
    ...
 }

 Employee emp = new Employee();
 emp.addAddress("home", new Address(...));
 emp.addAddress("office", new Address(...));
 ...

 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");

In this case, the key can be an expression, e.g. a variable.
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.

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

Example 6: 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");

Example 7: Creating objects

JXPath can be used to create new objects. First, create a subclass of AbstractFactory and install it on the JXPathContext. Then call createPathAndSetValue() instead of "setValue". 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.createPathAndSetValue("address/zipCode", "90190");

Example 8: Using 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", Integer.valueOf(2));

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

You can also set variables using JXPath:

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

Note: you can only change the value of an existing variable this way, you cannot define a new variable.

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);

Example 9: Using Nested Contexts

If you need to use the same set of variable 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.

 JXPathContext varContext = JXPathContext.newContext(null);
 varContext.getVariables().declareVariable("title", "Java");
 JXPathContext context = JXPathContext.newContext(varContext, auth);
 Iterator javaBooks = context.iterate("books[title = $title]");

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

Example 10: Using Standard Extension Functions

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

Here's how you can create new objects:


 Book book = (Book) context.getValue("org.apache.commons.jxpath.example.Book.new ('John Updike')");

Here's how you can call static methods:


 Book book = (Book) context.getValue("org. apache.commons.jxpath.example.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.

Example 11: Using 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.

Configuring JXPath

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

Notes

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 attribute supported for JavaBeans is "name". The XPath "foo/bar" is equivalent to "foo[@name='bar']".
The term matches no property in the graph is used throughout the documentation. It describes a property or path that can be determined as not belonging to the graph. Determining whether a property or path belongs to the graph depends on the type of object being used as cotextBean (see newContext(Object)). It is only possible strongly typed models where a specific Java model is used as context. It is not possible with dynamic models such Maps or DOM implementations.
When a XPath does not match a property in the graph, the methods of this class that retrieve a pointer will generally behave in the following way, depending on the last value configured with setLenient(boolean):
1. If lenient is false (default) - methods will throw JXPathNotFoundException.
2. If lenient is true - methods will throw no exception and return a value appropriate for that method to express the absence: might be a Java null or a Pointer whose Pointer.getValue() returns null, depends on the method.

Class JXPathContext

JXPath Interprets XPath Syntax on Java Object Graphs

Example 1: JavaBean Property Access

Example 2: Nested Bean Property Access

Example 3: Collection Subscripts

Example 4: Map Element Access

Example 5: Retrieving Multiple Results

Example 6: Setting Properties

Example 7: Creating objects

Example 8: Using Variables

Example 9: Using Nested Contexts

Using Custom Variable Pools

Example 10: Using Standard Extension Functions

Example 11: Using Custom Extension Functions

Configuring JXPath

Notes

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

parentContext

contextBean

vars

functions

factory

idManager

keyManager

decimalFormats

Constructor Details

JXPathContext

Method Details

compile

newContext

newContext

compilePath

createPath

createPathAndSetValue

getContextBean

getContextPointer

getDecimalFormatSymbols

getFactory

getFunctions

getIdentityManager

getKeyManager

getLocale

getNamespaceContextPointer

getNamespaceURI

getNodeSetByKey

getParentContext

getPointer

getPointerByID

getPointerByKey

getPrefix

getRelativeContext

getValue

getValue

getVariables

isLenient

iterate

iteratePointers

registerNamespace

removeAll

removePath

selectNodes

selectSingleNode

setDecimalFormatSymbols

setExceptionHandler

setFactory

setFunctions

setIdentityManager

setKeyManager

setLenient

setLocale

setNamespaceContextPointer

setValue

setVariables