src/site/xdoc/index.xml - commons-jexl - Git at Google

 <?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>
	<?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>