| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You 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>Apache Commons JEXL Overview</title> |
| </properties> |
| |
| <body> |
| <section name="Java Expression Language (JEXL)"> |
| <p> |
| JEXL is a library intended to facilitate the implementation of dynamic and scripting features in |
| applications and frameworks written in Java. |
| </p> |
| <p> |
| JEXL implements an Expression Language based on some extensions to the JSTL Expression Language supporting most of the |
| constructs seen in shell-script or ECMAScript. |
| <br/> |
| Its goal is to expose scripting features usable by technical operatives or consultants |
| working with enterprise platforms. |
| </p> |
| <p> |
| The library exposes a small footprint API |
| - the <a href="apidocs/org/apache/commons/jexl3/package-summary.html#usage">core features</a> fit in |
| 3 classes and 10 methods - that can be used in various conditions: |
| <ul> |
| <li>Scripting features: |
| <ul><li>Your application lets (advanced) users evaluate or define some simple expressions |
| like computation formulas.</li></ul> |
| </li> |
| <li>Module or component configuration: |
| <ul> |
| <li>Your application has configuration files (eventually generated by a design module) |
| consumed by the end-user module that would benefit from variables and expressions. |
| </li> |
| <li>When it would be convenient to use IOC but overall complexity doesn't require |
| (or can't depend upon) a full-blown library (Spring, Guice...). |
| </li> |
| </ul> |
| </li> |
| <li>Loose-coupling of interfaces and implementations or duck-typing: |
| <ul> |
| <li>You have optional classes that your code cant consider as compilation dependencies.</li> |
| <li>You have to integrate and call "legacy" code or use components that you dont want to |
| strongly depend upon.</li> |
| </ul> |
| </li> |
| <li>Simple template capabilities: |
| <ul><li>Your application has basic template requirements and JSPs or |
| Velocity would be overkill or too inconvenient to deploy.</li></ul> |
| </li> |
| </ul> |
| </p> |
| <p> |
| JEXL name stands for Java EXpression Language, a simple expression language originally inspired by Apache |
| Velocity and the Expression Language defined in the JavaServer Pages Standard Tag Library version 1.1 (JSTL) |
| and JavaServer Pages version 2.0 (JSP). |
| JEXL 2.0 added features inspired by |
| <a href="https://en.wikipedia.org/wiki/Unified_Expression_Language">Unified EL</a>. |
| The syntax is now close to a mix of ECMAScript and "shell-script" |
| making it easy to master by technical operatives or consultants. The objects exposed and their behavior |
| obviously need to be documented though... |
| </p> |
| <p> |
| The API and the expression language exploit Java-beans naming patterns through |
| introspection to expose property getters and setters. It also considers public class fields |
| as properties and allows to invoke any accessible method. |
| </p> |
| <p> |
| JEXL attempts to bring some of the lessons learned by the Velocity |
| community about expression languages in templating to a wider audience. |
| <a href="http://commons.apache.org/jelly">Commons Jelly</a> needed |
| Velocity-ish method access, it just had to have it. |
| </p> |
| <p> |
| It must be noted that JEXL is <strong>not</strong> a compatible implementation of EL as defined |
| in JSTL 1.1 (JSR-052) or JSP 2.0 (JSR-152). For a compatible implementation of |
| these specifications, see the <a href="http://commons.apache.org/el">Commons EL</a> project. |
| </p> |
| </section> |
| |
| <section name="A Brief Example"> |
| <p> |
| When evaluating expressions, JEXL merges an |
| <a href="apidocs/org/apache/commons/jexl3/JexlExpression.html">JexlExpression</a> |
| or a |
| <a href="apidocs/org/apache/commons/jexl3/JexlScript.html">JexlScript</a> |
| with a |
| <a href="apidocs/org/apache/commons/jexl3/JexlContext.html">JexlContext</a>. |
| An Expression is created using |
| <a href="apidocs/org/apache/commons/jexl3/JexlEngine.html#createExpression(java.lang.String)">JexlEngine#createExpression()</a>, |
| passing a String containing valid JEXL syntax. A simple JexlContext can be created by instantiating a |
| <a href="apidocs/org/apache/commons/jexl3/MapContext.html">MapContext</a>; |
| a map of variables that will be internally wrapped can be optionally provided through its constructor. |
| The following example, takes a variable named foo, and invokes the bar() method on the property innerFoo: |
| </p> |
| |
| <source><![CDATA[ |
| // Create or retrieve an engine |
| JexlEngine jexl = new JexlBuilder().create(); |
| |
| // Create an expression |
| String jexlExp = "foo.innerFoo.bar()"; |
| JexlExpression e = jexl.createExpression( jexlExp ); |
| |
| // Create a context and add data |
| JexlContext jc = new MapContext(); |
| jc.set("foo", new Foo() ); |
| |
| // Now evaluate the expression, getting the result |
| Object o = e.evaluate(jc);]]></source> |
| </section> |
| |
| <section name="Extensions to JSTL Expression Language"> |
| <p> |
| While JEXL is similar to the expression language defined in JSTL, it has improved |
| upon the syntax in a few areas: |
| </p> |
| <ul> |
| <li>Support for invocation of any accessible method (see example above).</li> |
| <li>Support for setting/getting any accessible public field.</li> |
| <li>A general <span class="literal">new()</span> method allowing to instantiate objects.</li> |
| <li>A general <span class="literal">size()</span> method, which works on: |
| <ul> |
| <li><span class="literal">String</span> - returns length</li> |
| <li><span class="literal">Map</span> - returns number of keys</li> |
| <li><span class="literal">List</span> - returns number of elements.</li> |
| </ul> |
| </li> |
| <li>A general <span class="literal">empty()</span> method, which works on Collections and Strings.</li> |
| <li>Support for the ternary operator 'a ? b : c' - and its GNU-C / "Elvis" variant 'a ?: c'.</li> |
| <li>Support for the Perl-like regex matching operators '=~' and '!~'</li> |
| <li>Support for the CSS3-inspired 'startsWith' and 'endsWith' operators '=^' and '=$'</li> |
| <li>Support for user-defined functions.</li> |
| <li>Misc : '+' has been overloaded to be use as a String concatenation operator</li> |
| </ul> |
| |
| </section> |
| |
| <section name="Related Resources"> |
| <p> |
| JEXL is not a product of the Java Community Process (JCP), but it provides a |
| similar expression syntax. For more information about JSP 2.0 EL and JSTL 1.1 |
| EL: |
| </p> |
| <ul> |
| <li> |
| <a href="http://www.oracle.com/technetwork/java/index-jsp-138231.html">JSP 2.0</a> is covered |
| by Java Specification Requests (JSR) |
| <a href="http://www.jcp.org/en/jsr/detail?id=152">JSR-152: JavaServer |
| Pages 2.0 Specification</a>. |
| </li> |
| <li> |
| Apache has an implementation of the expression language for JSP 2.0, |
| called <a href="http://commons.apache.org/el/index.html">EL</a> |
| </li> |
| <li> |
| <a href="http://www.oracle.com/technetwork/java/index-jsp-135995.html">JSTL 1.1</a> is covered |
| by <a href="http://jcp.org/en/jsr/detail?id=52">JSR 52: A Standard |
| Tag Library for JavaServer Pages</a>. See the |
| <a href="http://docs.oracle.com/javaee/5/jstl/1.1/docs/tlddocs/">JSTL API</a>. |
| </li> |
| <li>Apache has a <a href="http://tomcat.apache.org/taglibs/standard/">JSTL Implementation</a>.</li> |
| </ul> |
| <subsection name="Velocity"> |
| <p> |
| <a href="http://velocity.apache.org/">Apache Velocity</a> implements |
| a similar expression language. |
| </p> |
| <p> |
| In particular the <a href="http://velocity.apache.org/engine/devel/user-guide.html#References">References</a> |
| section of the User Guide has some good information on properties and method which correlate |
| directly to JEXL. |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="Anyone Using It Yet?"> |
| <ul> |
| <li> |
| <a href="http://commons.apache.org/configuration">Commons Configuration</a> |
| </li> |
| <li> |
| <a href="http://commons.apache.org/scxml">Commons SCXML</a> |
| </li> |
| <li> |
| <a href="http://commons.apache.org/jelly">Jelly</a> |
| </li> |
| </ul> |
| </section> |
| |
| </body> |
| </document> |
| |