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>