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

        https://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 3.3 Release Notes</title>
  </properties>

  <body>
  <section name="Compatibility with previous releases">
    <p>
    Version 3.3 is source and binary compatible with 3.2.
    </p><p>
    However, the default setting for permissions that determine which packages, classes and methods are accessible
    to scripts has been reduced to a very narrow set. When migrating from previous version of JEXL, this may result
    in breaking your application behavior ; this breaking change requires remediation in your code.
    </p><p>
    Despite the obvious inconvenience - our sincere apologies on the matter -, how much functional and semantic power is
    accessible through scripts has a real impact on your application security and stability ; that potential risk requires
    an informed review and conscious choice on your end.
    </p><p>
    To mitigate the change, you can revert to the previous behavior with one line of code
    (see <a href="apidocs/org/apache/commons/jexl3/introspection/JexlPermissions.html">JexlPermissions</a>,
    <a href="apidocs/org/apache/commons/jexl3/JexlBuilder.html">JexlBuilder</a> and
    <a href="apidocs/org/apache/commons/jexl3/scripting/JexlScriptEngine.html">JexlScriptEngine</a> )  or use this
    opportunity to reduce exposure. Whether Files, URLs, networking, processes, class-loaders or reflection classes
    or whether loops or side-effects are accessible are part of your choice to make.
    </p>
    </section>
    <section name="What's new in 3.3:">
    <p>
    JEXL 3.3 brings the ability to configure permissions on libraries in the manner pioneered
    with the @NoJexl annotation on source code. This is achieved through a crude but light mechanism akin to
    a security manager that controls what JEXL can introspect and thus expose to scripts.
    </p><p>
    Used in conjunction with options (JexlOptions) and features (JexlFeatures), the permissions (JexlPermissions)
    allow fine-tuning the end-user freedom and scripting integration through syntactic and semantic sanitation.
    </p><p>
    JEXL 3.3 also adds some syntactic (ECMAScript) features (let, const, =>, for, ...) to further reduce
    the skill set required to write scripts.
    </p>
    </section>

    <section name="New Features in 3.3:">
    <p>
      <table>
      <tr><td>JEXL-392:</td><td>Enable namespace declaration based on scripts</td></tr>
      <tr><td>JEXL-391:</td><td>Improve in/=~ operator when arguments are arrays and collections</td></tr>
      <tr><td>JEXL-390:</td><td>Pragmas should not be statements</td></tr>
      <tr><td>JEXL-389:</td><td>Improve parsing timings</td></tr>
      <tr><td>JEXL-385:</td><td>Support disabling fortran-style relational operators syntax</td></tr>
      <tr><td>JEXL-382:</td><td>Simplify grammar and lexical state management</td></tr>
      <tr><td>JEXL-380:</td><td>Multiple values per pragma key</td></tr>
      <tr><td>JEXL-379:</td><td>Allow new to use class identifier</td></tr>
      <tr><td>JEXL-373:</td><td>Add support for prefix/postfix increment/decrement operators</td></tr>
      <tr><td>JEXL-372:</td><td>Add support for 'standard' for loop</td></tr>
      <tr><td>JEXL-369:</td><td>Add 'let' and 'const' variable declarations</td></tr>
      <tr><td>JEXL-367:</td><td>Named function and fat-arrow (=>) lambda syntax</td></tr>
      <tr><td>JEXL-366:</td><td>Fail to evaluate string and number comparison</td></tr>
      <tr><td>JEXL-365:</td><td>Lambda expressions</td></tr>
      <tr><td>JEXL-363:</td><td>Allow retrieving captured variables in script</td></tr>
      <tr><td>JEXL-360:</td><td>Add missing bitshift operators ( &gt;&gt;&gt;, &gt;&gt;, &lt;&lt;)</td></tr>
      <tr><td>JEXL-359:</td><td>Allow per-operator arithmetic handling of null arguments</td></tr>
      <tr><td>JEXL-357:</td><td>Configure accessible packages/classes/methods/fields</td></tr>
    </table>
    </p>
    </section>

    <section name="Bugs Fixed in 3.3:">
    <p>
      <table>
        <tr><td>JEXL-386:</td><td>Non-inheritable permissions on interfaces are ignored in an inheritable sandbox</td></tr>
        <tr><td>JEXL-384:</td><td>Improve control over JexlArithmetic null argument handling</td></tr>
        <tr><td>JEXL-378:</td><td>Incremental operator and decremental operator do not honor the side-effect flag</td></tr>
        <tr><td>JEXL-376:</td><td>Introspector captures methods on non-exported classes (modules, java9+)</td></tr>
        <tr><td>JEXL-375:</td><td>Cannot access enums by their name when using sandbox</td></tr>
        <tr><td>JEXL-374:</td><td>No exception if dereferencing null object using safe(false) and antish(false)</td></tr>
        <tr><td>JEXL-371:</td><td>Override of a protected method with public visibility is not callable</td></tr>
        <tr><td>JEXL-370:</td><td>Cannot check if variable is defined using ObjectContext if the value is null</td></tr>
        <tr><td>JEXL-368:</td><td>Namespace functor resolution is not cached</td></tr>
        <tr><td>JEXL-364:</td><td>Evaluator options not propagated in closures</td></tr>
        <tr><td>JEXL-362:</td><td>JexlInfo position reporting is off</td></tr>
        <tr><td>JEXL-361:</td><td>Null may be used as operand silently even in arithmetic strict(true) mode</td></tr>
        <tr><td>JEXL-354:</td><td>#pragma does not handle negative integer or real literals</td></tr>
        <tr><td>JEXL-353:</td><td>Documentation error for not-in/not-match operator</td></tr>
      </table>
    </p>
    </section>
  </body>
</document>
