##### Commons Jexl

- Overview
- 1.0 Javadoc
- Latest Javadoc
- Examples
- Releases and Builds
- Jar Downloads
- Reference
- Building
- JEXL Wiki

##### Project Documentation

- About
- Downloads
- Project Info
- Project Reports
- Development Process

##### Commons

- Home
- Components
- Sandbox
- Dormant
- Volunteering
- Contributing Patches
- Building Components
- Releasing Components
- Wiki

##### Legend

- External Link
- Opens in a new window

## Overview

In this reference you will find the following topics to help with your use of JEXL.

- Evaluating Expressions
- Custom Contexts
- Custom Resolvers
- Example Expressions

You can find two sample programs in JEXL's CVS repository:

- Using arrays
- Accessing Properties and invoking methods

As well, JEXL's Unit Tests provide handy examples of expressions. The test code also contains a simple class that evaluates its command line arguments as JEXL expressions when run.

## Evaluating Expressions

To evaluate expressions using JEXL, you need two things:

- A context containing any variables, and
- An expression

The easiest way of obtaining a a context is to use the JexlHelper.createContext() method. This creates a context which is simply an extension of a HashMap

Expressions are created using the ExpressionFactory.createExpression(String) method.

Once you have your expression, you can then use use the evaluate to execute it and obtain a result.

Here's a typical scenario:

        // Create an expression object for our calculation
        String calculateTax = taxManager.getTaxCalc(); //e.g. "((G1 + G2 + G3) * 0.1) + G4";
        Expression e = ExpressionFactory.createExpression( calculateTax );

        // populate the context
        JexlContext context = JexlHelper.createContext();
        context.getVars().put("G1", businessObject.getTotalSales());
        context.getVars().put("G2", taxManager.getTaxCredit(businessObject.getYear()));
        context.getVars().put("G3", businessObject.getIntercompanyPayments());
        context.getVars().put("G4", -taxManager.getAllowances());
        // ...

        // work it out
        Float result = (Float)e.evaluate(context);

## Custom Contexts

Often you have the objects and values that are needed in the context available elsewhere, and instead of creating the default context and populating it manually in the code, it may be simpler to create a context implementation of your own.

The JexlContext interface is very simple with only two methods, one to get the variables of the context as a Map and another to set the variables of the context from a Map.

Here's a simple context that wraps the JVM's system properties:

            JexlContext context = new JexlContext() {
                public Map getVars() { return System.getProperties(); }
                public void setVars(Map map) { }
            };

## Custom Resolvers

JEXL allows you to add custom expression resolvers that will get called with before or after expression evaluation.

If pre-resolvers is added to an expression, any value it returns will be used instead of that normally provided by JEXL. If JEXL evaluates an expression to `null` post-resolvers of an expression are called in turn in an attempt to get a value.

Expression resolvers are called in the order that they are added.

## Example Expressions

### Arithmetic

Most valid arithmetic expressions in Java are also valid in Jexl.

    1 + 2
    12.0 - 5.2
    6 * 12 + 5 / 2.6
    12 % 2
    6 div 4
    -12 + 77.2
    x * 1.1 + y

Arithmetic expressions can use variables. `null` is treated as a zero for arithmetic.

### Calling methods

JEXL allows you to call any method on a Java object using the same syntax. If you have a string in the context under the name `aString`, you could call it's `length` method like this:

    aString.length()
    aString.substring(6)

Often the values you want to pass to a method are other variables or expressions. If you have a number in the context, named `i`, you could use it in a method call:

    aString.substring(i)

### Accessing properties

JEXL provides a shorthand syntax to access methods that follow the JavaBean naming convention for properties, i.e. setters and getters.

If you have some object foo in the context and it has a method `getBar()`, you can call that method using the following syntax:

    foo.bar

Since `java.lang.Object` has a `getClass()` method that returns a `java.lang.Class` object, and the class has a `getName()` method, the following is a shorthand for obtaining the class name of an object `foo` in the context:

    foo.class.name

### Arrays, Lists and Maps

Array elements can be accessed using either square brackets or a dotted index notation, e.g. the following are equivalent

    arr[0]
    arr.0

The same holds true for lists.

For a map, the syntax is very similar, except the 'index' is an object, e.g. the following are equivalent.

    aMap['key']
    aMap.get('key')

Please note that the index does not have to be a string, and that the string usage above is just one possible option.