<!--
   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.
-->
$Id$

                            Commons JEXL Package
                                Version 3.0
                               Release Notes


INTRODUCTION:
=============

JEXL is a library intended to facilitate the implementation of dynamic and scripting features in
applications and frameworks written in Java.

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.

Its goal is to expose scripting features usable by technical operatives or consultants working with enterprise platforms.


  http://commons.apache.org/jexl/


========================================================================================================================
Release 3.0
========================================================================================================================

Version 3.0 is a major release changing the public JEXL API.

Due to binary and source incompatibilities and the scope of modifications, JEXL has moved to the
org.apache.commons.jexl3 package.
However, this is a drop-in replacement through JSR-223 and casual code usage should find easy equivalence between
jexl-2.x and 3.x (besides the package name).
Also note that JEXL 3.0 now requires Java 6.


What's new in 3.0:
==================
* A redesigned API that properly segregates the "public" part and the "internal" parts of JEXL.
* The ability to create JEXL functions in script, closure/variables hoisting included.
* A set of String matching operators (^= startsWith, $= endsWith) and their negative counterparts (!^, !$)
* A range operator (x .. y) to ease writing loops (for(var x : 1 .. 10) ... )

New features in 3.0:
====================
* JEXL-133:     String matching Operator short-hand inspired by CSS3
* JEXL-128:     ObjectContext<> should implement NamespaceResolver
* JEXL-127:     Allow the creation of functions
* JEXL-123:     Redesign API for stability
* JEXL-122:     Move JEXL from org.apache.comms.jexl2 to org.apache.commons.jexl3
* JEXL-136:     Script calls within scripts may fail with number arguments
* JEXL-135:     Using map as script parameter or local variable
* JEXL-134:     Issue with evaluation of concat of variables : \r + \n gives 0
* JEXL-131:     UnifiedJexl parsing may fail with NPE
* JEXL-130:     Ternary Conditional fails for Object values
* JEXL-126:     Decimal numbers literals should be 'double' by default (instead of 'float')

There are no other changes.


========================================================================================================================
Release 2.1.1
========================================================================================================================

Version 2.1.1 is a micro release to fix a regression detected in 2.1:

* JEXL-124:     Array parameters to methods don't work anymore (Jexl 2.1.1)

There are no other changes.


========================================================================================================================
Release 2.1
========================================================================================================================

Version 2.1 is a minor release adding new features and fixing known issues detected in 2.0.

Compatibility with previous releases
====================================
Version 2.1 is binary compatible with 2.0.1.

However it is not source compatible.
New methods have been added to the org.apache.commons.jexl2.Script and org.apache.commons.jexl2.JexlInfo interfaces.
Any source code that implements these interfaces will need to be updated.

What's new in 2.1:
==================
* A more thorough arithmetic (JexlArithmetic) that allows fine control over decimals (scale and precision), a
  new syntax for numeric literals (OGNL inspired Big and Huge notations) and a better type handling keeping the most
  appropriate representation in casual operations.
* The introduction of script variables and parameters that reduce context dependencies and methods; this allows to
  perform checks after script creation (light static checking hints). Plus the ability to call script from scripts.
* A sandoxing feature to restrict and rename what JEXL can access from the environment allowing tighter control over security.
* Extensions to UnifiedJEXL that allow the creation of templates.

New features in 2.1:
====================
* JEXL-114:     Allow scripts to create local variables // Add return keyword
* JEXL-113:     Add functions to extract which variables, parameters and local variables are used to evaluate a script
* JEXL-118:     Provide an IN operator
* JEXL-115:     Add support for asynchronous script execution and cancellation
* JEXL-116:     Add control over classes, methods, constructors and properties allowed in scripts
* JEXL-120:     Add simple template features
* JEXL-119:     Allow indexed properties container resolution in expressions
* JEXL-106:     When divide two BigDecimal values in an expression it results in java.lang.ArithmeticException
* JEXL-102:     Add "jexl2" as a supported name

Bugs Fixed in 2.1:
==================
* JEXL-83:      Make JexlArithmetic immutable (and threadsafe)
* JEXL-24:      Support Long for integer literal instead of Integers
* JEXL-107:     literals and parenthesized expressions can not be used as references
* JEXL-108:     parsing error if i define a empty literal array/map
* JEXL-101:     Vararg methods where the first argument is no vararg can not be called with only the fixed parameters given
* JEXL-105:     Array literals are considered constant even when they are not
* JEXL-104:     NPE in JexlArithmetic when an Array-Expression containing a null is used.
* JEXL-112:     Cannot parse Integer.MIN_VALUE
* JEXL-111:     expression execute error

Bugs fixed in 2.0.1:
====================

* JEXL-100:     Array access expressions fail when evaluated twice and cache is enabled
* JEXL-99:      Documentation of Thread Safety / Invalid code examples on homepage
* JEXL-98:      Quote escaping cannot be escaped


2.0
==================

Bugs fixed in 2.0:
==================

* JEXL-90:	Jexl parser allows invalid expressions, e.g. "a=1 b=2 3"
* JEXL-88:	MethodKey.java - name clash getMostSpecific() with Java 1.5.0
* JEXL-87:	Inconsistent behaviour of arithmetical operations
* JEXL-81:	Introspector does not use ListGetExecutor for List
* JEXL-80:	Lenient mode should not throw exception when {g,s}etting an undefined property
* JEXL-78:	Ternary operator throws Exception when JexlEngine in strict mode
* JEXL-76:	Remove unnecessary class VisitorAdapter
* JEXL-71:	Parsing errors?
* JEXL-67:	Potential NPE in util.introspection.MethodKey
* JEXL-66:	testDottedNames expects map enumeration order
* JEXL-64:	Inconsistent behaviour of dotted names
* JEXL-62:	NPE in Interpreter
* JEXL-59:	ClassMap holds a reference to class
* JEXL-56:	Logging wrongly uses java.util.logging
* JEXL-50:	Div operator does not do integer division
* JEXL-49:	Block statements aren't parsed
* JEXL-48:	NPE during expression evaluation
* JEXL-45:	Unhandled division by zero
* JEXL-42:	NullPointerException evaluating an expression
* JEXL-40:	JEXL fails to find abstract public methods in the base class if overridden by non-public derived types
* JEXL-32:	BigDecimal values are treated as Long values which results in loss of precision
* JEXL-30:	ASTAddNode does not add BigDecimal objects correctly
* JEXL-27:	Cannot assign a value to the property of an object, such as object.prop = value.
* JEXL-26:	ASTArrayAccess messes up on fallback to JexlContext
* JEXL-19:	Ternary conditional not supported
* JEXL-3 :	Static method resolution and changes to context

Other issues fixed (Improvements/New Features):
===============================================

* JEXL-95:	Enhance JSR-223 implementation
* JEXL-94:	Allow stateful namespaces (ns:function)
* JEXL-93:	Add public fields as targets of set/get property
* JEXL-92:	JexlContext API should be more flexible
* JEXL-89:	Drop main() and suite() methods from Test cases
* JEXL-85:	2.0 grammar finishing touches & debugger update
* JEXL-82:	Change foreach syntax
* JEXL-77:	Rename last Velocity originated classes
* JEXL-72:	Remove deprecated classes and methods entirely
* JEXL-70:	Add main class to allow scripts etc to be tested
* JEXL-63:	JSR-223 support
* JEXL-61:	Usage of strong references on Method/Constructor & WeakHashMap usage
* JEXL-60:	Refactor o.a.c.jexl.util and o.a.c.jexl.util.introspection
* JEXL-58:	UnifiedJEXL
* JEXL-57:	Change pom.xml to make it Netbeans Maven2 plugin friendly
* JEXL-55:	JEXL 2.0 redux, attempting to restart the effort to release 2.0
* JEXL-54:	Light performance enhancements
* JEXL-47:	Allow single-line comments with //
* JEXL-43:	Website overview does not mention method calls and new 2.0 features
* JEXL-41:	Allow nested ${} evaluation
* JEXL-35:	Final API requirements
* JEXL-34:	Remove pre and post resolution of variables via the JexlExprResolver classes.
* JEXL-33:	Remove unnecessary throws Exception from various classes
* JEXL-29:	Support non-object-level functions/methods, as size and empty function
* JEXL-25:	Call method with varargs
* JEXL-24:	Support Long for integer literal instead of Integers
* JEXL-21:	operator overloading / hooks on operator processing
* JEXL-16:	allowing quote escaping
* JEXL-15:	Needs definable functions
* JEXL-11:	Don't make null convertible into anything
* JEXL-10:	Make possible checking for unresolved variables

Other Changes:
==============

o Add @since 2.0 tags to code so we can track API additions via Javadoc

Upgrading from JEXL 1.x
=======================

JEXL now requires Java 1.5 or later.

Version 2.0 resides in the org.apache.commons.jexl2 package; part of the version 1.x API is reimplemented as an
add-on source library in the jexl-compat directory; since it can not fully reimplement the original public 1.x, it may
only be used to ease transition in strictly controlled deployments.

The following classes are implemented through the jexl-compat source library:
  * ExpressionFactory
  * ScriptFactory
  * Expression
  * Script
  * JexlContext
  * JexlHelper

Migration notes
===============

When migrating from jexl 1.x to jexl 2.0, the following hints may be helpfull.

The following classes no longer exist:
  * ExpressionFactory, ScriptFactory: create a JexlEngine and use createExpression() or createScript()
  instead.

The following classes have been renamed and replaced:

  * VelMethod <=> JexlMethod
  * VelPropertyGet <=> JexlPropertyGet
  * VelPropertySet <=> JexlPropertySet

The following methods have been removed:

  * Info.getTemplateName() - use Info.getName() instead
  * Expression.addPostResolver() / Expression.addPreResolver() - set ant-like variables in JexlContext, implement
    a specific JexlContext or derive JexlcontextInterpreter/JexlEngine instead

Behavior changes
================

* Public fields are considered when using JexlPropertyGet / JexlPropertySet: Jexl 1.x behavior can be reimplemented
by subclassing UberspectImpl.

*Division (/ operator) behavior change: division between integers no longer casts its operands to double; integer division
    allways results in a integer. The 1.x behavior can be reimplemented by subclassing JexlArithmetic.

New Features:
=============

Assignment expression: a = b (and a.b.c = d)
   * Assigns a variable (ant-like variable or bean-property)

Ternary operator expression: a ? b : c  (and a ?: c)
   * The usual inline conditional shortcut and its 'Elvis' form (a ?: b evaluates as a ? a : b)

Constructor call expression: new('my.class.name', arguments...)
   * Creates a new instance of a class using the most appropriate constructor according
     to the actual arguments

Function namespace: ns:func(arguments...)
   * A function namespace allows the use of class or instance methods in function calls

UnifiedJEXL
   * Adds ${...} and #{...} JSP/EL syntax support on top of the JexlEngine

JSR-223 support
   * Implement JSR-223 Scripting Engine for JEXL script (need BSF-3.0 on Java < 6)

Error and exception handling
   * Configuring the leniency and verbosity of the Jexl engine allows user control over the
     error handling policy