<?xml version="1.0"?>
<!--
  Copyright 2002,2004 The Apache Software Foundation.
  
  Licensed 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>Commons JEXL Overview</title>
    </properties>

    <body>
    <section name="Java Expression Language (JEXL)">

    <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).  
      While inspired by JSTL EL, it must be noted that JEXL is not 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://jakarta.apache.org/commons/el/">Commons EL</a> project.

    </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://jakarta.apache.org/commons/jelly">Commons Jelly</a> needed
      Velocity-ish method access, it just had to have it.
    </p>
    
    </section>

    <section name="A Brief Example">

    <p>
      When evaluating expressions, JEXL merges an <a href="http://jakarta.apache.org/commons/jexl/apidocs/org/apache/commons/jexl/Expression.html">Expression</a> with a <a href="http://jakarta.apache.org/commons/jexl/apidocs/org/apache/commons/jexl/JexlContext.html">JexlContext</a>.
      An Expression is created using <a href="http://jakarta.apache.org/commons/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://jakarta.apache.org/commons/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://jakarta.apache.org/commons/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>

    <source><![CDATA[
    // 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);]]></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>
        Added 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>
        Optional syntax for the 'empty' function : empty(obj)
        </li>
        <li>
        Misc : '+' has been overloaded to be use as a String concatenation operator
        </li>

     </ul>

    </section>

    <section name="Releases">
        <p>
        JEXL 1.0 has been released.
        See the <a href="releases.html">releases</a> page for information on obtaining releases.
        </p>
    </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://java.sun.com/products/jsp/index.jsp">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://jakarta.apache.org/commons/el/index.html">EL</a>
          </li>
          <li>
            <a href="http://java.sun.com/products/jsp/jstl/">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://java.sun.com/products/jsp/jstl/1.1/docs/api/index.html">JSTL API</a>.
          </li>
          <li>Apache has a <a href="http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html">JSTL Implementation</a>.</li>
        </ul>
        <subsection name="Velocity">
          <p>
            <a href="http://jakarta.apache.org/velocity">Jakarta Velocity</a> implements 
            a similar expression language. 
          </p>
          <p>
            In particular the <a href="http://jakarta.apache.org/velocity/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://jakarta.apache.org/commons/jelly">Jelly</a>
          </li>
          <li>
           <a href="http://jakarta.apache.org/commons/scxml">Commons SCXML</a>
          </li>
        </ul>
    </section>

 </body>
</document>

