Author: henrib
Date: Thu Nov 12 17:11:24 2009
New Revision: 835449
URL: http://svn.apache.org/viewvc?rev=835449&view=rev
Log:
Updated package documentation
Modified:
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl/package.html
Modified:
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl/package.html
URL:
http://svn.apache.org/viewvc/commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl/package.html?rev=835449&r1=835448&r2=835449&view=diff
==============================================================================
---
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl/package.html
(original)
+++
commons/proper/jexl/trunk/src/main/java/org/apache/commons/jexl/package.html
Thu Nov 12 17:11:24 2009
@@ -1,80 +1,276 @@
<html>
-<!--
- 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.
--->
- <head>
- <title>Package Documentation for org.apache.commons.jexl Package</title>
- </head>
- <body bgcolor="white">
- Provides a framework for evaluating JEXL expressions.
- <br/><br/>
- <p>
- <ul>
- <li><a href="#intro">Introduction</a></li>
- <li><a href="#example">Brief Example</a></li>
- </ul>
- </p>
- <h2><a name="intro">Introduction</a></h2>
- <p>
- Java Expression Language (JEXL) is an expression language engine which can
be
- embedded in applications and frameworks. JEXL is inspired by Jakarta
Velocity
- and the Expression Language defined in the JavaServer Pages Standard Tag
Library
- version 1.1 (JSTL) and JavaServer Pages version 2.0 (JSP).
- </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 needed</a>
- Velocity-ish method access, it just had to have it.
- </p>
- <p>
- It must be noted that JEXL is not a compatibile 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>
-
- <h2><a name="example">A Brief Example</a></h2>
-
- <p>
- When evaluating expressions, JEXL merges an
- <a
href="http://commons.apache.org/jexl/apidocs/org/apache/commons/jexl/Expression.html";>Expression</a>
- with a
- <a
href="http://commons.apache.org/jexl/apidocs/org/apache/commons/jexl/JexlContext.html";>JexlContext</a>.
- An Expression is created using
- <a
href="http://commons.apache.org/jexl/apidocs/org/apache/commons/jexl/ExpressionFactory.html#createExpression(java.lang.String)">ExpressionFactory.createExpression()</a>,
- passing a String containing valid JEXL syntax. A JexlContext is created
using
- <a
href="http://commons.apache.org/jexl/apidocs/org/apache/commons/jexl/JexlHelper.html#createContext()">JexlHelper.createContext()</a>,
- and variables are put into a map exposed through the
- <a
href="http://commons.apache.org/jexl/apidocs/org/apache/commons/jexl/JexlContext.html#getVars()">getVars()</a>
- method on JexlContext. The following example, takes a variable named foo,
and
- invokes the bar() method on the property innerFoo:
- </p>
- <pre>
- // Create an expression object
- String jexlExp = "foo.innerFoo.bar()";
- Expression e = ExpressionFactory.createExpression( jexlExp );
-
- // Create a context and add data
- JexlContext jc = JexlHelper.createContext();
- jc.getVars().put("foo", new Foo() );
-
- // Now evaluate the expression, getting the result
- Object o = e.evaluate(jc);
- </pre>
-
-</body>
+ <!--
+ 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.
+ -->
+ <head>
+ <title>Package Documentation for org.apache.commons.jexl
Package</title>
+ </head>
+ <body bgcolor="white">
+ Provides a framework for evaluating JEXL expressions.
+ <br/><br/>
+ <ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#example">Brief Example</a></li>
+ <li><a href="#usage">Using JEXL</a></li>
+ <li><a href="#configuration">Configuring JEXL</a></li>
+ <li><a href="#customization">Customizing JEXL</a></li>
+ </ul>
+
+ <h2><a name="intro">Introduction</a></h2>
+ <p>
+ JEXL is a library intended to facilitate the implementation of
dynamic and scripting features in applications
+ and frameworks.
+ It enables coding configuration, module/component loose-coupling
dependencies or simple template capabilities using a
+ small footprint API.
+ Its name itself stands for Java EXpression Language, a simple
expression language inspired by Jakarta Velocity
+ and the Expression Language defined in the JavaServer Pages
Standard Tag Library version 1.1 (JSTL) and
+ JavaServer Pages version 2.0 (JSP).
+ The API and the expression language exploit Java-beans naming
patterns through
+ introspection to expose property getters and setters.
+ </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 needed</a>
+ Velocity-ish method access, it just had to have it.
+ </p>
+ <p>
+ It must be noted that JEXL is not a compatibile 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>
+
+ <h2><a name="example">A Brief Example</a></h2>
+ <p>
+ When evaluating expressions, JEXL merges an
+ {...@link org.apache.commons.jexl.Expression}
+ with a
+ {...@link org.apache.commons.jexl.JexlContext}.
+ An Expression is created using
+ {...@link
org.apache.commons.jexl.JexlEngine#createExpression(java.lang.String)},
+ passing a String containing valid JEXL syntax. A JexlContext is
created using
+ {...@link org.apache.commons.jexl.JexlHelper#createContext()},
+ and variables are put into a map exposed through the
+ {...@link org.apache.commons.jexl.JexlContext#getVars()}
+ method on JexlContext. The following example, takes a variable
named foo, and
+ invokes the bar() method on the property innerFoo:
+ </p>
+ <pre>
+ // Create a JexlEngine (could reuse one instead)
+ JexlEngine jexl = new JexlEngine();
+ // Create an expression object
+ String jexlExp = "foo.innerFoo.bar()";
+ Expression e = jexl.createExpression( jexlExp );
+
+ // Create a context and add data
+ JexlContext jc = JexlHelper.createContext();
+ jc.getVars().put("foo", new Foo() );
+
+ // Now evaluate the expression, getting the result
+ Object o = e.evaluate(jc);
+ </pre>
+
+ <h2><a name="usage">Using JEXL</a></h2>
+ The API is composed of three levels addressing different functional
needs:
+ <ul>
+ <li>Dynamic invocation of setters, getters, methods and
constructors</li>
+ <li>Script expressions known as JEXL expressions</li>
+ <li>JSP/JSF like expression known as UnifiedJEXL expresions</li>
+ </ul>
+
+ <h3><a name="usage_api">Dynamic invocation</a></h3>
+ <p>
+ These functionalities are close to the core level utilities found
in
+ <a href="http://commons.apache.org/beanutils/";>BeanUtils</a>.
+ For basic dynamic property manipulations and method invocation,
you can use the following
+ set of methods:
+ </p>
+ <ul>
+ <li>{...@link org.apache.commons.jexl.JexlEngine#setProperty}</li>
+ <li>{...@link org.apache.commons.jexl.JexlEngine#getProperty}</li>
+ <li>{...@link org.apache.commons.jexl.JexlEngine#invokeMethod}</li>
+ <li>{...@link org.apache.commons.jexl.JexlEngine#newInstance}</li>
+ </ul>
+ The following example illustrate their usage:
+ <pre>
+ // test outer class
+ public static class Froboz {
+ int value;
+ public Froboz(int v) { value = v; }
+ public void setValue(int v) { value = v; }
+ public int getValue() { return value; }
+ }
+ // test inner class
+ public static class Quux {
+ String str;
+ Froboz froboz;
+ public Quux(String str, int fro) {
+ this.str = str;
+ froboz = new Froboz(fro);
+ }
+ public Froboz getFroboz() { return froboz; }
+ public void setFroboz(Froboz froboz) { this.froboz = froboz; }
+ public String getStr() { return str; }
+ public void setStr(String str) { this.str = str; }
+ }
+ // test API
+ JexlEngine jexl = nex JexlEngine();
+ Quux quux = jexl.newInstance(Quux.class, "xuuq", 100);
+ jexl.setProperty(quux, "froboz.value", Integer.valueOf(100));
+ Object o = jexl.getProperty(quux, "froboz.value");
+ assertEquals("Result is not 100", new Integer(100), o);
+ jexl.setProperty(quux, "['froboz'].value", Integer.valueOf(1000));
+ o = jexl.getProperty(quux, "['froboz']['value']");
+ assertEquals("Result is not 1000", new Integer(1000), o);
+ </pre>
+
+ <h3><a name="usage_jexl">JEXL script expression</a></h3>
+ <p>
+ If your needs require simple expression evaluation capabilities,
the core JEXL features
+ will most likely fit.
+ The main methods are:
+ </p>
+ <ul>
+ <li>{...@link
org.apache.commons.jexl.JexlEngine#createExpression}</li>
+ <li>{...@link org.apache.commons.jexl.JexlEngine#createScript}</li>
+ <li>{...@link org.apache.commons.jexl.Expression#evaluate}</li>
+ </ul>
+ The following example illustrates their usage:
+ <pre>
+ JexlEngine jexl = nex JexlEngine();
+
+ JexlContext jc = JexlHelper.createContext();
+ jc.getVars().put("quuxClass", quux.class);
+
+ Expression create = jexl.createExpression("quux = new(quuxClass,
'xuuq', 100)");
+ Expression assign = jexl.createExpression("quux.froboz.value =
10");
+ Expression check = jexl.createExpression("quux[\"froboz\"].value");
+ Quux quux = (Quux) create.evaluate(jc);
+ Object o = assign.evaluate(jc);
+ assertEquals("Result is not 10", new Integer(10), o);
+ o = check.evaluate(jc);
+ assertEquals("Result is not 10", new Integer(10), o);
+ </pre>
+
+ <h3><a name="usage_ujexl">UnifiedJEXL script expressions</a></h3>
+ <p>
+ If you are looking for JSP-EL like and basic templating features,
you can
+ use UnifiedJEXL.
+ </p>
+ The main methods are:
+ <ul>
+ <li>{...@link org.apache.commons.jexl.UnifiedJEXL#parse}</li>
+ <li>{...@link
org.apache.commons.jexl.UnifiedJEXL.Expression#evaluate}</li>
+ <li>{...@link
org.apache.commons.jexl.UnifiedJEXL.Expression#prepare}</li>
+ </ul>
+ The following example illustrates their usage:
+ <pre>
+ JexlEngine jexl = new JexlEngine();
+ UnifiedJEXL ujexl = new UnifiedJEXL(jexl);
+ UnifiedJEXL.Expression expr = ujexl.parse("Hello ${user}");
+ String hello = expr.evaluate(context, expr);
+ </pre>
+
+ <h2><a name="configuration">JEXL Configuration</a></h2>
+ <p>
+ The JexlEngine can be configured through a few parameters that
will drive how it reacts
+ in case of errors. These configuration methods are best called at
JEXL engine initialization time; it
+ is recommended to derive from JexlEngine to call those in a
constructor.
+ </p>
+ <p>
+ {...@link org.apache.commons.jexl.JexlEngine#setLenient}
configures when JEXL considers 'null' as an error or not in various situations;
+ when facing an unreferenceable variable, using null as an argument
to an arithmetic operator or failing to call
+ a method or constructor. The lenient mode is close to JEXL-1.1
behavior.
+ </p>
+ <p>
+ {...@link org.apache.commons.jexl.JexlEngine#setSilent} configures
how JEXL reacts to errors; if silent, the engine will not throw exceptions
+ but will warn through loggers and return null in case of errors.
Note that when non-silent, JEXL throws
+ JexlException which are unchecked exception.
+ </p>
+ <p>
+ {...@link org.apache.commons.jexl.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.jexl.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.
+ This
+ </p>
+ <p>
+ JexlEngine and UnifiedJEXL expression caches can be configured as
well. If you intend to use JEXL
+ 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 not create a cache
+ whilst UnifiedJEXL does.
+ </p>
+ <p>Both JexlEngine and UnifiedJEXL are thread-safe; the same instance
can be shared between different
+ threads and proper synchronization is enforced in critical
areas.</p>
+ <p>{...@link org.apache.commons.jexl.JexlEngine#setCache} will set how
many expressions can be simultaneously cached by the
+ JEXL engine. UnifiedJEXL allows to define the cache size through
its constructor.</p>
+ <p>
+ {...@link org.apache.commons.jexl.JexlEngine#setFunctions} extend
JEXL scripting by registering functions in
+ namespaces.
+ </p>
+ This can be used as in:
+ <pre><code>
+ public static MyMath {
+ public double cos(double x) {
+ return Math.cos(x);
+ }
+ }
+ Map<String, Object> funcs = new HashMap<String, Object>();
+ funcs.put("math", new MyMath());
+ JexlEngine jexl = new JexlEngine();
+ jexl.setFunctions(funcs);
+
+ JexlContext jc = JexlHelper.createContext();
+ jc.getVars().put("pi", Math.PI);
+
+ e = JEXL.createExpression("math:cos(pi)");
+ o = e.evaluate(jc);
+ assertEquals(Double.valueOf(-1),o);
+ </code></pre>
+
+ <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.jexl.JexlEngine} is meant to be
+ extended and let 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.jexl.JexlArithmetic}
+ is the class to derive if you need to change how operators behave.
For example, this would
+ be the case if you wanted '+' to operate on arrays; you'd need to
derive JexlArithmetic and
+ implement your own version of Add.
+ </p>
+ <p>
+ {...@link org.apache.commons.jexl.Interpreter}
+ is the class to derive if you need to add more features to the
evaluation
+ itself; for instance, you want pre- and post- resolvers for
variables or nested scopes for
+ for variable contexts or add factory based support to the 'new'
operator.
+ </p>
+ <p>
+ {...@link org.apache.commons.jexl.util.introspection.UberspectImpl}
+ is the class to derive if you need to add introspection or
reflection capabilities for some objects.
+ For instance, being able to expose and manipulate public fields
instead of Java-beans conventions.
+ </p>
+ </body>
</html>
