1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
<?xml version="1.0"?>
<!--
Copyright 2002,2004 The Apache Software Foundation.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<document>
<properties>
<title>Commons JEXL Examples</title>
</properties>
<body>
<section name="Overview">
<p>
In this reference you will find the following topics to help with your use of JEXL.
<ul>
<li><a href="#Evaluating Expressions">Evaluating Expressions</a></li>
<li><a href="#Custom Contexts">Custom Contexts</a></li>
<li><a href="#Custom Resolvers">Custom Resolvers</a></li>
<li><a href="#Example Expressions">Example Expressions</a></li>
</ul>
</p>
<p>
You can find two sample programs in JEXL's CVS repository:
<ul>
<li><a href="http://svn.apache.org/viewcvs.cgi/jakarta/commons/proper/jexl/trunk/examples/ArrayExample.java?view=markup">Using arrays</a></li>
<li><a href="http://svn.apache.org/viewcvs.cgi/jakarta/commons/proper/jexl/trunk/examples/MethodPropertyExample.java?view=markup">Accessing Properties and invoking methods</a></li>
</ul>
</p>
<p>
As well, <a href="http://svn.apache.org/viewcvs.cgi/jakarta/commons/proper/jexl/trunk/src/test/org/apache/commons/jexl/JexlTest.java?view=markup">JEXL's Unit Tests</a>
provide handy examples of expressions. The test code also contains a
<a href="http://svn.apache.org/viewcvs.cgi/jakarta/commons/proper/jexl/trunk/src/test/org/apache/commons/jexl/Jexl.java?view=markup">simple class</a>
that evaluates its command line arguments as JEXL expressions when run.
</p>
</section>
<section name="Evaluating Expressions">
<p>
To evaluate expressions using JEXL, you need two things:
<ul>
<li>A <a href="http://jakarta.apache.org/commons/jexl/apidocs/org/apache/commons/jexl/JexlContext.html">context</a> containing any variables, and</li>
<li>An <a href="http://jakarta.apache.org/commons/jexl/apidocs/org/apache/commons/jexl/Expression.html">expression</a></li>
</ul>
</p>
<p>
The easiest way of obtaining a a context is to use the
<a href="http://jakarta.apache.org/commons/jexl/apidocs/org/apache/commons/jexl/JexlHelper.html#createContext()">JexlHelper.createContext()</a>
method. This creates a context which is simply an extension of a
<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/HashMap.html">HashMap</a>
</p>
<p>
<a href="http://jakarta.apache.org/commons/jexl/apidocs/org/apache/commons/jexl/Expression.html">Expressions</a> are
created using the <a href="http://jakarta.apache.org/commons/jexl/apidocs/org/apache/commons/jexl/ExpressionFactory.html#createExpression(java.lang.String)">ExpressionFactory.createExpression(String)</a>
method.
</p>
<p>
Once you have your expression, you can then use use the
<a href="http://jakarta.apache.org/commons/jexl/apidocs/org/apache/commons/jexl/Expression.html#evaluate(org.apache.commons.jexl.JexlContext)">evaluate</a>
to execute it and obtain a result.
</p>
<p>
Here's a typical scenario:
</p>
<source>
// 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);
</source>
</section>
<section name="Custom Contexts">
<p>
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.
</p>
<p>
The <a href="http://jakarta.apache.org/commons/jexl/apidocs/org/apache/commons/jexl/JexlContext.html">JexlContext</a>
interface is very simple with only two methods, one to get the variables of the
context as a <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Map.html">Map</a> and
another to set the variables of the context from a Map.
</p>
<p>
Here's a simple context that wraps the JVM's system properties:
<source>
JexlContext context = new JexlContext() {
public Map getVars() { return System.getProperties(); }
public void setVars(Map map) { }
};
</source>
</p>
</section>
<section name="Custom Resolvers">
<p>
JEXL allows you to add custom expression resolvers that will get called with before or after expression
evaluation.
</p>
<p>
If <a href="http://jakarta.apache.org/commons/jexl/apidocs/org/apache/commons/jexl/JexlExprResolver.html">pre-resolvers</a>
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 <code>null</code> post-resolvers of an expression are called in turn in an attempt to get a value.
</p>
<p>
Expression resolvers are called in the order that they are added.
</p>
</section>
<section name="Example Expressions">
<!-- invoking methods, property access, array access, empty, size etc... -->
<subsection name="Arithmetic">
<p>Most valid arithmetic expressions in Java are also valid in Jexl.</p>
<source>
1 + 2
12.0 - 5.2
6 * 12 + 5 / 2.6
12 % 2
6 div 4
-12 + 77.2
x * 1.1 + y
</source>
<p>Arithmetic expressions can use variables. <code>null</code> is treated as a zero for arithmetic.</p>
</subsection>
<subsection name="Calling methods">
<p>
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 <code>aString</code>,
you could call it's <code>length</code>
method like this:
<source>
aString.length()
aString.substring(6)
</source>
</p>
<p>
Often the values you want to pass to a method are other variables or expressions.
If you have a number in the context, named <code>i</code>, you could use it
in a method call:
<source>aString.substring(i)</source>
</p>
</subsection>
<subsection name="Accessing properties">
<p>
JEXL provides a shorthand syntax to access methods that
follow the JavaBean naming convention for properties, i.e.
setters and getters.
</p>
<p>
If you have some object foo in the context and it has a
method <code>getBar()</code>, you can call that method using
the following syntax:
<source>foo.bar</source>
</p>
<p>
Since <code>java.lang.Object</code> has a <code>getClass()</code> method
that returns a <code>java.lang.Class</code> object, and the
class has a <code>getName()</code> method, the following is a shorthand
for obtaining the class name of an object <code>foo</code> in the context:
<source>foo.class.name</source>
</p>
</subsection>
<subsection name="Arrays, Lists and Maps">
<p>
Array elements can be accessed using either square brackets or a dotted
index notation, e.g. the following are equivalent
<source>arr[0]
arr.0</source>
The same holds true for lists.
</p>
<p>
For a map, the syntax is very similar, except the 'index' is an object, e.g.
the following are equivalent.
<source>aMap['key']
aMap.get('key')</source>
Please note that the index does not have to be a string, and
that the string usage above is just one possible option.
</p>
</subsection>
</section>
</body>
</document>
|
