Author: henrib
Date: Thu Jul 7 03:11:02 2011
New Revision: 1143637
URL: http://svn.apache.org/viewvc?rev=1143637&view=rev
Log:
Added precisions about Expression, Script and UnifiedJEXL.Expression
Modified:
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl2/package.html
Modified:
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl2/package.html
URL:
http://svn.apache.org/viewvc/commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl2/package.html?rev=1143637&r1=1143636&r2=1143637&view=diff
==============================================================================
---
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl2/package.html
(original)
+++
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl2/package.html
Thu Jul 7 03:11:02 2011
@@ -34,7 +34,7 @@
JEXL is a library intended to facilitate the implementation of
dynamic and scripting features in applications
and frameworks.
</p>
-
+
<h2><a name="example">A Brief Example</a></h2>
<p>
When evaluating expressions, JEXL merges an
@@ -74,16 +74,16 @@
</ul>
<h3><a name="usage_note">Important note</a></h3>
- The only public packages you should use are:
+ The only public packages you should use are:
<ul>
<li>org.apache.commons.jexl2</li>
<li>org.apache.commons.jexl2.introspection</li>
</ul>
- The following packages follow a "use at your own maintenance cost"
policy.
- Their classes and methods are not guaranteed to remain compatible
in subsequent versions.
- If you think you need to use some of their features, it might be a
good idea to check with
- the community through the mailing list first.
- <ul>
+ The following packages follow a "use at your own maintenance cost"
policy.
+ Their classes and methods are not guaranteed to remain compatible in
subsequent versions.
+ If you think you need to use some of their features, it might be a
good idea to check with
+ the community through the mailing list first.
+ <ul>
<li>org.apache.commons.jexl2.parser</li>
<li>org.apache.commons.jexl2.scripting</li>
<li>org.apache.commons.jexl2.internal</li>
@@ -182,6 +182,29 @@
UnifiedJEXL.Expression expr = ujexl.parse("Hello ${user}");
String hello = expr.evaluate(context, expr).toString();
</pre>
+ <h3>Expressions Script and UnifiedJEXL.Expression: differences</h3>
+ <h4><Expression</h4>
+ <p>
+ This only allows for a single command to be executed and the result
from
+ that is returned. If you try to use multiple commands it ignores
+ everything after the first semi-colon and just returns the result from
+ the first command.
+ </p>
+ <h4>Script</h4>
+ <p>
+ This allows you to put multiple commands in the expression and you can
+ use variable assignments, loops, calculations, etc. The result from
the
+ last command is returned from the script.
+ </p>
+ <h4>UnifiedJEXL.Expression</h4>
+ <p>
+ This is ideal to produce text. To get a calculation you use the
EL-like syntax
+ as in ${someVariable}. The expression that goes between the brackets
+ behaves like a script, not an expression. You can use semi-colons to
+ execute multiple commands and the result from the last command is
+ returned from the script. You also have the ability to use a 2-pass
evaluation using
+ the #{someScript} syntax.
+ </p>
<h2><a name="configuration">JEXL Configuration</a></h2>
<p>
@@ -200,13 +223,13 @@
JexlException which are unchecked exception.
</p>
<p>
- {@link org.apache.commons.jexl2.JexlEngine#setDebug} makes
stacktraces carried by JExlException more meaningfull; in particular, these
+ {@link org.apache.commons.jexl2.JexlEngine#setDebug} makes
stacktraces carried by JExlException more meaningfull; in particular, these
traces will carry the exact caller location the Expression was
created from.
</p>
<p>
- {@link org.apache.commons.jexl2.JexlEngine#setClassLoader} indicates
to a JexlEngine which class loader to use to solve a class name; this affects
- how JexlEngine.newInstance and the 'new' script method operates. This
is mostly usefull in cases where
- you rely on JEXL to dynamically load and call plugins for your
application.
+ {@link org.apache.commons.jexl2.JexlEngine#setClassLoader}
indicates to a JexlEngine which class loader to use to solve a class name; this
affects
+ how JexlEngine.newInstance and the 'new' script method operates.
This is mostly usefull in cases where
+ you rely on JEXL to dynamically load and call plugins for your
application.
</p>
<p>
JexlEngine and UnifiedJEXL expression caches can be configured as
well. If you intend to use JEXL
@@ -223,7 +246,7 @@
{@link org.apache.commons.jexl2.JexlEngine#setFunctions} extends
JEXL scripting by registering functions in
namespaces.
</p>
- This can be used as in:
+ This can be used as in:
<pre><code>
public static MyMath {
public double cos(double x) {
@@ -242,18 +265,18 @@
o = e.evaluate(jc);
assertEquals(Double.valueOf(-1),o);
</code></pre>
- If the <i>namespace</i> is a Class and that class declares a
constructor that takes a JexlContext (or
- a class extending JexlContext), one <i>namespace</i> instance is
created on first usage in an
- expression; this instance lifetime is limited to the expression
evaluation.
+ If the <i>namespace</i> is a Class and that class declares a
constructor that takes a JexlContext (or
+ a class extending JexlContext), one <i>namespace</i> instance is
created on first usage in an
+ expression; this instance lifetime is limited to the expression
evaluation.
<h2><a name="customization">JEXL Customization</a></h2>
If you need to make JEXL treat some objects in a specialized manner or
tweak how it
reacts to some settings, you can derive most of its inner-workings.
<p>
- {@link org.apache.commons.jexl2.JexlEngine} is meant to be
- extended and lets you capture your own configuration defaults wrt
cache sizes and various flags.
- Implementing your own cache - instead of the basic LinkedHashMap
based one - would be
- another possible extension.
+ {@link org.apache.commons.jexl2.JexlEngine} is meant to be
+ extended and lets you capture your own configuration defaults wrt
cache sizes and various flags.
+ Implementing your own cache - instead of the basic LinkedHashMap
based one - would be
+ another possible extension.
</p>
<p>
{@link org.apache.commons.jexl2.JexlArithmetic}
