Author: henrib
Date: Mon Aug 6 13:11:05 2012
New Revision: 1369832
URL: http://svn.apache.org/viewvc?rev=1369832&view=rev
Log:
JEXL-123:
Rename JxltEngine.UnifiedExpression as JxltEngine.Expression (no need to have a
longer name);
Completed JexlContext javadoc;
Updated examples to jexl3 API
Modified:
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/JexlContext.java
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/JxltEngine.java
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/internal/TemplateEngine.java
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/package.html
commons/proper/jexl/trunk/src/site/xdoc/reference/examples.xml
commons/proper/jexl/trunk/src/test/java/org/apache/commons/jexl3/IssuesTest.java
commons/proper/jexl/trunk/src/test/java/org/apache/commons/jexl3/JXLTTest.java
Modified:
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/JexlContext.java
URL:
http://svn.apache.org/viewvc/commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/JexlContext.java?rev=1369832&r1=1369831&r2=1369832&view=diff
==============================================================================
---
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/JexlContext.java
(original)
+++
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/JexlContext.java
Mon Aug 6 13:11:05 2012
@@ -18,8 +18,21 @@ package org.apache.commons.jexl3;
/**
* Manages variables which can be referenced in a JEXL expression.
- * <p>Note that JEXL may use '$jexl' and '$ujexl' variables for internal
purpose; setting or getting those
- * variables may lead to unexpected results unless specified otherwise.</p>
+ * <p>
+ * Jexl variable names in their simplest form are 'java-like' identifiers.
+ * Jexl also considers 'ant' inspired variables expressions as valid.
+ * For instance, the expression 'x.y.z' is an 'antish' variable and will be
resolved as a whole by the context,
+ * i.e. using the key "x.y.z". This proves to be useful to solve "fully
qualified class names".
+ * <p>
+ * </p>
+ * The interpreter variable resolution algorithm will try the different
sequences of identifiers till it finds
+ * one that exists in the context; if "x" is an object known in the context
(JexlContext.has("x") returns true),
+ * "x.y" will <em>not</em> be looked up in the context but will most likely
refer to "x.getY()".
+ * </p>
+ * <p>
+ * Note that JEXL may use '$jexl' and '$ujexl' variables for internal purpose;
setting or getting those
+ * variables may lead to unexpected results unless specified otherwise.
+ * </p>
* @since 1.0
*/
public interface JexlContext {
Modified:
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/JxltEngine.java
URL:
http://svn.apache.org/viewvc/commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/JxltEngine.java?rev=1369832&r1=1369831&r2=1369832&view=diff
==============================================================================
---
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/JxltEngine.java
(original)
+++
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/JxltEngine.java
Mon Aug 6 13:11:05 2012
@@ -56,7 +56,7 @@ public abstract class JxltEngine {
}
/**
- * A unified expression can mix immediate, deferred and nested
sub-expressions as well as string constants;
+ * A unified expression that can mix immediate, deferred and nested
sub-expressions as well as string constants;
* <ul>
* <li>The "immediate" syntax is of the form
<code>"...${jexl-expr}..."</code></li>
* <li>The "deferred" syntax is of the form
<code>"...#{jexl-expr}..."</code></li>
@@ -102,7 +102,7 @@ public abstract class JxltEngine {
* </p>
* @since 2.0
*/
- public interface UnifiedExpression {
+ public interface Expression {
/**
* Generates this expression's string representation.
* @return the string representation
@@ -137,7 +137,7 @@ public abstract class JxltEngine {
* <p>Other expressions return themselves.</p>
* @return the source expression
*/
- UnifiedExpression getSource();
+ Expression getSource();
/**
* Gets the list of variables accessed by this expression.
@@ -176,12 +176,12 @@ public abstract class JxltEngine {
* If the underlying JEXL engine is silent, errors will be logged
through its logger as warning.
* </p>
* @param context the context to use for immediate expression
evaluations
- * @return an {@link UnifiedExpression} or null if an error occurs and
the {@link JexlEngine} is running
+ * @return an {@link Expression} or null if an error occurs and the
{@link JexlEngine} is running
* in silent mode
* @throws Exception if an error occurs and the {@link JexlEngine}
* is not in silent mode
*/
- UnifiedExpression prepare(JexlContext context);
+ Expression prepare(JexlContext context);
/**
* Formats this expression, adding its source string representation in
@@ -193,24 +193,24 @@ public abstract class JxltEngine {
}
/**
- * Creates a a {@link UnifiedExpression} from an expression string.
+ * Creates a a {@link Expression} from an expression string.
* Uses & fills up the expression cache if any.
* <p>
* If the underlying JEXL engine is silent, errors will be logged through
its logger as warnings.
* </p>
* @param expression the {@link Template} string expression
- * @return the {@link UnifiedExpression}, null if silent and an error
occured
+ * @return the {@link Expression}, null if silent and an error occured
* @throws Exception if an error occurs and the {@link JexlEngine}
* is not silent
*/
- public abstract UnifiedExpression createExpression(String expression);
+ public abstract Expression createExpression(String expression);
/**
* A template is a JEXL script that evaluates by writing its content
through a Writer.
* <p>
* The source text is parsed considering each line beginning with '$$' (as
default pattern) as JEXL script code
* and all others as Unified JEXL expressions; those expressions will be
invoked from the script during
- * evaluation and their output gathered through a writer.
+ * evaluation and their output gathered through a writer.
* It is thus possible to use looping or conditional construct "around"
expressions generating output.
* </p>
* For instance:
Modified:
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/internal/TemplateEngine.java
URL:
http://svn.apache.org/viewvc/commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/internal/TemplateEngine.java?rev=1369832&r1=1369831&r2=1369832&view=diff
==============================================================================
---
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/internal/TemplateEngine.java
(original)
+++
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/internal/TemplateEngine.java
Mon Aug 6 13:11:05 2012
@@ -175,7 +175,7 @@ public final class TemplateEngine extend
/**
* The abstract base class for all unified expressions, immediate '${...}'
and deferred '#{...}'.
*/
- private abstract class TemplateExpression implements UnifiedExpression {
+ private abstract class TemplateExpression implements Expression {
/** The source of this template expression(see {@link
TemplateEngine.TemplateExpression#prepare}). */
protected final TemplateExpression source;
@@ -582,7 +582,7 @@ public final class TemplateEngine extend
}
@Override
- public JxltEngine.UnifiedExpression createExpression(String expression) {
+ public JxltEngine.Expression createExpression(String expression) {
Exception xuel = null;
TemplateExpression stmt = null;
try {
@@ -988,7 +988,7 @@ public final class TemplateEngine extend
/** The wrapped context. */
private final JexlContext wrap;
/** The array of TemplateEngine expressions. */
- private final UnifiedExpression[] exprs;
+ private final Expression[] exprs;
/** The writer used to output. */
private final Writer writer;
/** The call frame. */
@@ -1002,7 +1002,7 @@ public final class TemplateEngine extend
* @param out the output writer
*/
protected TemplateContext(JexlContext jcontext, Scope.Frame jframe,
- UnifiedExpression[] expressions, Writer out) {
+ Expression[] expressions, Writer out) {
wrap = jcontext;
frame = jframe;
exprs = expressions;
@@ -1065,7 +1065,7 @@ public final class TemplateEngine extend
if (e < 0 || e >= exprs.length) {
return;
}
- UnifiedExpression expr = exprs[e];
+ Expression expr = exprs[e];
if (expr.isDeferred()) {
expr = expr.prepare(wrap);
}
Modified:
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/package.html
URL:
http://svn.apache.org/viewvc/commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/package.html?rev=1369832&r1=1369831&r2=1369832&view=diff
==============================================================================
---
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/package.html
(original)
+++
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl3/package.html
Mon Aug 6 13:11:05 2012
@@ -170,13 +170,13 @@
<h3><a name="usage_ujexl">Unified Expressions and Templates</a></h3>
<p>
If you are looking for JSP-EL like and basic templating features,
you can
- use UnifiedExpression from a JxltEngine.
+ use Expression from a JxltEngine.
</p>
The main methods are:
<ul>
<li>{@link
org.apache.commons.jexl3.JxltEngine#createExpression}</li>
- <li>{@link
org.apache.commons.jexl3.JxltEngine.UnifiedExpression#prepare}</li>
- <li>{@link
org.apache.commons.jexl3.JxltEngine.UnifiedExpression#evaluate}</li>
+ <li>{@link
org.apache.commons.jexl3.JxltEngine.Expression#prepare}</li>
+ <li>{@link
org.apache.commons.jexl3.JxltEngine.Expression#evaluate}</li>
<li>{@link org.apache.commons.jexl3.JxltEngine#createTemplate}</li>
<li>{@link
org.apache.commons.jexl3.JxltEngine.Template#prepare}</li>
<li>{@link
org.apache.commons.jexl3.JxltEngine.Template#evaluate}</li>
@@ -185,11 +185,11 @@
<pre>
JexlEngine jexl = new JexlBuilder().create();
JxltEngine jxlt = jexl.jxlt();
- JxltEngine.UnifiedExpression expr = jxlt.createExpression("Hello
${user}");
+ JxltEngine.Expression expr = jxlt.createExpression("Hello
${user}");
String hello = jxlt.evaluate(context, jxlt).toString();
</pre>
- <h3>JexlExpression, JexlScript, UnifiedExpression and Template:
summary</h3>
+ <h3>JexlExpression, JexlScript, Expression and Template: summary</h3>
<h4>JexlExpression </h4>
<p>
These are the most basic form of JexlEngine expressions and only
allow for a single command
@@ -203,7 +203,7 @@
use variable assignments, loops, calculations, etc. More or less
what can be achieved in Shell or
JavaScript at its basic level. The result from the last command is
returned from the script.
</p>
- <h4>JxltEngine.UnifiedExpression</h4>
+ <h4>JxltEngine.Expression</h4>
<p>
These are ideal to produce "one-liner" text, like a 'toString()'
on steroids.
To get a calculation you use the EL-like syntax
@@ -216,7 +216,7 @@
<h4>JxltEngine.Template</h4>
<p>
These produce text documents. Each line beginning with '$$' (as a
default) is
- considered JEXL code and all others considered as
JxltEngine.UnifiedExpression.
+ considered JEXL code and all others considered as
JxltEngine.Expression.
Think of those as simple Velocity templates. A rewritten MudStore
initial Velocity sample looks like this:
</p>
<pre><code>
@@ -298,7 +298,7 @@
repeatedly in your application, these are worth configuring since
expression parsing is quite heavy.
Note that all caches created by JEXL are held through
SoftReference; under high memory pressure, the GC will be able
to reclaim those caches and JEXL will rebuild them if needed. By
default, a JexlEngine does create a cache for "small" expressions
- and a JxltEngine does create one for UnifiedExpression .
+ and a JxltEngine does create one for Expression .
</p>
<p>{@link org.apache.commons.jexl3.JexlBuilder#cache} will set how
many expressions can be simultaneously cached by the
JEXL engine. JxltEngine allows to define the cache size through
its constructor.
Modified: commons/proper/jexl/trunk/src/site/xdoc/reference/examples.xml
URL:
http://svn.apache.org/viewvc/commons/proper/jexl/trunk/src/site/xdoc/reference/examples.xml?rev=1369832&r1=1369831&r2=1369832&view=diff
==============================================================================
--- commons/proper/jexl/trunk/src/site/xdoc/reference/examples.xml (original)
+++ commons/proper/jexl/trunk/src/site/xdoc/reference/examples.xml Mon Aug 6
13:11:05 2012
@@ -6,9 +6,9 @@
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.
@@ -59,15 +59,10 @@
</ul>
</p>
<p>
- The common way of using a JEXL engine is to allocate it as a singleton
and use this opportunity to tailor its
- behavior and cache.
+ The common way of using a JEXL engine is to create it as a singleton
and use this opportunity to tailor its
+ behavior and cache through the jexlBuilder options.
<source>
- private static final JexlEngine jexl = new JexlEngine();
- static {
- jexl.setCache(512);
- jexl.setLenient(false);
- jexl.setSilent(false);
- }
+ private static final JexlEngine jexl = new
JexlBuilder.cache(512).strict(true).silent(false).create();
</source>
</p>
<p>
@@ -79,7 +74,7 @@
<p>
<a
href="http://commons.apache.org/jexl/apidocs/org/apache/commons/jexl3/Expression.html";>Expressions</a>
are
created using the <a
href="http://commons.apache.org/jexl/apidocs/org/apache/commons/jexl3/JexlEngine.html#createExpression(java.lang.String)">JexlEngine.createExpression(String)</a>
- method.
+ method.
</p>
<p>
Once you have your expression, you can then use use the
@@ -102,7 +97,7 @@
context.set("G3", businessObject.getIntercompanyPayments());
context.set("G4", -taxManager.getAllowances());
// ...
-
+
// work it out
Float result = (Float)e.evaluate(context);
</source>
@@ -144,7 +139,7 @@ x * 1.1 + y
<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>
+ you could call it's <code>length</code>
method like this:
<source>
aString.length()
@@ -174,7 +169,7 @@ aString.substring(6)
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:
+ for obtaining the class name of an object <code>foo</code> in the
context:
<source>foo.class.name</source>
</p>
</subsection>
Modified:
commons/proper/jexl/trunk/src/test/java/org/apache/commons/jexl3/IssuesTest.java
URL:
http://svn.apache.org/viewvc/commons/proper/jexl/trunk/src/test/java/org/apache/commons/jexl3/IssuesTest.java?rev=1369832&r1=1369831&r2=1369832&view=diff
==============================================================================
---
commons/proper/jexl/trunk/src/test/java/org/apache/commons/jexl3/IssuesTest.java
(original)
+++
commons/proper/jexl/trunk/src/test/java/org/apache/commons/jexl3/IssuesTest.java
Mon Aug 6 13:11:05 2012
@@ -129,7 +129,7 @@ public class IssuesTest extends JexlTest
ctxt.setStrict(false);
ctxt.set("ax", "ok");
- JxltEngine.UnifiedExpression expr = uel.createExpression("${ax+(bx)}");
+ JxltEngine.Expression expr = uel.createExpression("${ax+(bx)}");
Object value = expr.evaluate(ctxt);
assertTrue("should be ok", "ok".equals(value));
}
Modified:
commons/proper/jexl/trunk/src/test/java/org/apache/commons/jexl3/JXLTTest.java
URL:
http://svn.apache.org/viewvc/commons/proper/jexl/trunk/src/test/java/org/apache/commons/jexl3/JXLTTest.java?rev=1369832&r1=1369831&r2=1369832&view=diff
==============================================================================
---
commons/proper/jexl/trunk/src/test/java/org/apache/commons/jexl3/JXLTTest.java
(original)
+++
commons/proper/jexl/trunk/src/test/java/org/apache/commons/jexl3/JXLTTest.java
Mon Aug 6 13:11:05 2012
@@ -95,7 +95,7 @@ public class JXLTTest extends JexlTestCa
public void testStatement() throws Exception {
context.set("froboz", new Froboz(123));
- JxltEngine.UnifiedExpression check =
JXLT.createExpression("${froboz.value = 32; froboz.plus10(); froboz.value}");
+ JxltEngine.Expression check = JXLT.createExpression("${froboz.value =
32; froboz.plus10(); froboz.value}");
Object o = check.evaluate(context);
assertEquals("Result is not 42", new Integer(42), o);
Set<List<String>> evars = check.getVariables();
@@ -103,8 +103,8 @@ public class JXLTTest extends JexlTestCa
}
public void testAssign() throws Exception {
- JxltEngine.UnifiedExpression assign =
JXLT.createExpression("${froboz.value = 10}");
- JxltEngine.UnifiedExpression check =
JXLT.createExpression("${froboz.value}");
+ JxltEngine.Expression assign = JXLT.createExpression("${froboz.value =
10}");
+ JxltEngine.Expression check = JXLT.createExpression("${froboz.value}");
Object o = assign.evaluate(context);
assertEquals("Result is not 10", new Integer(10), o);
o = check.evaluate(context);
@@ -113,7 +113,7 @@ public class JXLTTest extends JexlTestCa
public void testComposite() throws Exception {
String source = "Dear ${p} ${name};";
- JxltEngine.UnifiedExpression expr = JXLT.createExpression(source);
+ JxltEngine.Expression expr = JXLT.createExpression(source);
context.set("p", "Mr");
context.set("name", "Doe");
assertTrue("expression should be immediate", expr.isImmediate());
@@ -137,14 +137,14 @@ public class JXLTTest extends JexlTestCa
public void testPrepareEvaluate() throws Exception {
final String source = "Dear #{p} ${name};";
- JxltEngine.UnifiedExpression expr = JXLT.createExpression("Dear #{p}
${name};");
+ JxltEngine.Expression expr = JXLT.createExpression("Dear #{p}
${name};");
assertTrue("expression should be deferred", expr.isDeferred());
Set<List<String>> evars = expr.getVariables();
assertEquals(1, evars.size());
assertTrue(contains(evars, Arrays.asList("name")));
context.set("name", "Doe");
- JxltEngine.UnifiedExpression phase1 = expr.prepare(context);
+ JxltEngine.Expression phase1 = expr.prepare(context);
String as = phase1.asString();
assertEquals("Dear ${p} Doe;", as);
Set<List<String>> evars1 = phase1.getVariables();
@@ -163,7 +163,7 @@ public class JXLTTest extends JexlTestCa
public void testNested() throws Exception {
final String source = "#{${hi}+'.world'}";
- JxltEngine.UnifiedExpression expr = JXLT.createExpression(source);
+ JxltEngine.Expression expr = JXLT.createExpression(source);
Set<List<String>> evars = expr.getVariables();
assertEquals(1, evars.size());
@@ -181,8 +181,8 @@ public class JXLTTest extends JexlTestCa
public void testImmediate() throws Exception {
JexlContext none = null;
final String source = "${'Hello ' + 'World!'}";
- JxltEngine.UnifiedExpression expr = JXLT.createExpression(source);
- JxltEngine.UnifiedExpression prepared = expr.prepare(none);
+ JxltEngine.Expression expr = JXLT.createExpression(source);
+ JxltEngine.Expression prepared = expr.prepare(none);
assertEquals("prepare should return same expression", "Hello World!",
prepared.asString());
Object o = expr.evaluate(none);
assertTrue("expression should be immediate", expr.isImmediate());
@@ -194,7 +194,7 @@ public class JXLTTest extends JexlTestCa
public void testConstant() throws Exception {
JexlContext none = null;
final String source = "Hello World!";
- JxltEngine.UnifiedExpression expr = JXLT.createExpression(source);
+ JxltEngine.Expression expr = JXLT.createExpression(source);
assertTrue("prepare should return same expression", expr.prepare(none)
== expr);
Object o = expr.evaluate(none);
assertTrue("expression should be immediate", expr.isImmediate());
@@ -206,7 +206,7 @@ public class JXLTTest extends JexlTestCa
public void testDeferred() throws Exception {
JexlContext none = null;
final String source = "#{'world'}";
- JxltEngine.UnifiedExpression expr = JXLT.createExpression(source);
+ JxltEngine.Expression expr = JXLT.createExpression(source);
assertTrue("expression should be deferred", expr.isDeferred());
String as = expr.prepare(none).asString();
assertEquals("prepare should return immediate version", "${'world'}",
as);
@@ -218,7 +218,7 @@ public class JXLTTest extends JexlTestCa
public void testEscape() throws Exception {
JexlContext none = null;
- JxltEngine.UnifiedExpression expr;
+ JxltEngine.Expression expr;
Object o;
// $ and # are escapable in TemplateEngine
expr = JXLT.createExpression("\\#{'world'}");
@@ -230,14 +230,14 @@ public class JXLTTest extends JexlTestCa
}
public void testEscapeString() throws Exception {
- JxltEngine.UnifiedExpression expr =
JXLT.createExpression("\\\"${'world\\'s finest'}\\\"");
+ JxltEngine.Expression expr = JXLT.createExpression("\\\"${'world\\'s
finest'}\\\"");
JexlContext none = null;
Object o = expr.evaluate(none);
assertEquals("\"world's finest\"", o);
}
public void testNonEscapeString() throws Exception {
- JxltEngine.UnifiedExpression expr =
JXLT.createExpression("c:\\some\\windows\\path");
+ JxltEngine.Expression expr =
JXLT.createExpression("c:\\some\\windows\\path");
JexlContext none = null;
Object o = expr.evaluate(none);
assertEquals("c:\\some\\windows\\path", o);
@@ -245,7 +245,7 @@ public class JXLTTest extends JexlTestCa
public void testMalformed() throws Exception {
try {
- JxltEngine.UnifiedExpression expr =
JXLT.createExpression("${'world'");
+ JxltEngine.Expression expr = JXLT.createExpression("${'world'");
JexlContext none = null;
expr.evaluate(none);
fail("should be malformed");
@@ -258,7 +258,7 @@ public class JXLTTest extends JexlTestCa
public void testMalformedNested() throws Exception {
try {
- JxltEngine.UnifiedExpression expr = JXLT.createExpression("#{${hi}
world}");
+ JxltEngine.Expression expr = JXLT.createExpression("#{${hi}
world}");
JexlContext none = null;
expr.evaluate(none);
fail("should be malformed");
@@ -271,7 +271,7 @@ public class JXLTTest extends JexlTestCa
public void testBadContextNested() throws Exception {
try {
- JxltEngine.UnifiedExpression expr =
JXLT.createExpression("#{${hi}+'.world'}");
+ JxltEngine.Expression expr =
JXLT.createExpression("#{${hi}+'.world'}");
JexlContext none = null;
expr.evaluate(none);
fail("should be malformed");
@@ -284,7 +284,7 @@ public class JXLTTest extends JexlTestCa
public void testCharAtBug() throws Exception {
context.set("foo", "abcdef");
- JxltEngine.UnifiedExpression expr =
JXLT.createExpression("${foo.substring(2,4)/*comment*/}");
+ JxltEngine.Expression expr =
JXLT.createExpression("${foo.substring(2,4)/*comment*/}");
Object o = expr.evaluate(context);
assertEquals("cd", o);
