<?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.6.1 Release Notes</title>
  </properties>

  <body>
    <section name="Compatibility with previous release">
      <p>
        Version 3.6.1 is source and binary compatible with 3.6.0.
      </p>
    </section>
    <section name="Compatibility with older releases (&lt; 3.3, 2.x)">
      <p>
        Since 3.3 release, 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 is new in 3.6.1:">
      <p>
        JEXL 3.6.1 is a minor release that fixes some bugs.
        It does not introduce any breaking change.
      </p>
    </section>
    <section name="Bugs fixed in 3.6.1:">
      <p>
        <table>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-452">JEXL-452:</a>
            </td>
            <td>Debug setting in Engine shows class/method/line even when set to false.</td>
          </tr>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-451">JEXL-451:</a>
            </td>
            <td>Restore JexlSandbox permission capabilities on Object.class.</td>
          </tr>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-450">JEXL-450:</a>
            </td>
            <td>Disable instantiation of internal classes in RESTRICTED mode.</td>
          </tr>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-449">JEXL-449:</a>
            </td>
            <td>Inconsistency on nature of curly-bracket syntactic elements regarding annotations.</td>
          </tr>
        </table>
      </p>
    </section>

    <section name="What was new in 3.6.0:">
      <p>
        JEXL 3.6.0 introduces a switch statement and expressions (JEXL-440).
        It is a minor release that does not introduce any breaking change.
      </p>
    </section>
    <section name="New Features in 3.6.0:">
      <p>
        <table>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-440">JEXL-440:</a>
            </td>
            <td>Switch statement &amp; expressions.</td>
          </tr>
        </table>
      </p>
    </section>
    <section name="Bugs fixed in 3.6.0:">
      <p>
        <table>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-437">JEXL-447:</a>
            </td>
            <td>Regression in script-defined functions</td>
          </tr>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-446">JEXL-446:</a>
            </td>
            <td>ClassTool module inspection is too strict</td>
          </tr>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-442">JEXL-442:</a>
            </td>
            <td>Local variables are not resolved in interpolation string expression</td>
          </tr>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-441">JEXL-441:</a>
            </td>
            <td>Tokenization error if "\n" in template expression.</td>
          </tr>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-439">JEXL-439:</a>
            </td>
            <td>When using reference capture, incorrect scoping when local variable redefines a captured symbol</td>
          </tr>
          <tr>
            <td>
              <a href="https://issues.apache.org/jira/browse/JEXL-437">JEXL-437:</a>
            </td>
            <td>Semicolons actually not optional between function calls on separate lines</td>
          </tr>
        </table>
      </p>
    </section>

    <section name="What was new in 3.5:">
      <p>
        A feature that captures variables as references allowing side effect from a lambda to its
        outer scope; this is mimicking JavaScript scoping rule (JEXL-426).
      </p>
    </section>
    <section name="New Features in 3.5:">
      <p>
        <table>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-438">JEXL-438:</a></td>
            <td>Allow parser factory specification.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-428">JEXL-428:</a></td>
            <td>Make Comparable object high priority while comparing.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-427>">JEXL-427:</a></td>
            <td>Avoid coercing logical expressions to boolean.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-426>">JEXL-426:</a></td>
            <td>Enable pass-by-reference for Captured Variables</td>
          </tr>
        </table>
      </p>
    </section>
    <section name="Bugs Fixed in 3.5:">
      <p>
        <table>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-436>">JEXL-436:</a></td>
            <td>The increment (decrement) operator does not check for null operand.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-435>">JEXL-435:</a></td>
            <td>Changed behavior of empty operator overloading action.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-434>">JEXL-434:</a></td>
            <td>The safe-access array operator is not safe.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-433>">JEXL-433:</a></td>
            <td>Debugger does not accept empty return statement.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-432>">JEXL-432:</a></td>
            <td>Namespace functors are not cleared when the classloader is updated.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-431>">JEXL-431:</a></td>
            <td>Parse error with variables declared in a catch clause.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-429>">JEXL-429:</a></td>
            <td>Ternary expression regression.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-425>">JEXL-425:</a></td>
            <td>Multiline format literals does not always return string.</td>
          </tr>
        </table>
      </p>
    </section>

    <section name="What was new in 3.4:">
      <p>
        Features and permissions are easier to define through new methods.
      </p>
      <p>
        Some new syntaxes are introduced ; try/catch/finally (including with resources),
        an array-access safe navigation ((x?[y]), strict equality/inequality operators (===, !==),
        instanceof/!instanceof operators and more permissive structured literals.
      </p>
    </section>

    <section name="New Features in 3.4:">
      <p>
        <table>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-423>">JEXL-423:</a></td>
            <td>Add support for instanceof / !instanceof</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-422>">JEXL-422:</a></td>
            <td>Add strict equality (===) and inequality (!==) operators</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-421>">JEXL-421:</a></td>
            <td>ArrayBuilder: array type should reflect common class of its entries</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-419>">JEXL-419:</a></td>
            <td>Add permission syntax to allow class/method/field</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-418>">JEXL-418:</a></td>
            <td>Add try-catch-finally support</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-408>">JEXL-408:</a></td>
            <td>Using JexlFeatures is tedious</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-404>">JEXL-404:</a></td>
            <td>Support array-access safe navigation (x?[y])</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-401>">JEXL-401:</a></td>
            <td>Captured variables should be read-only</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-398>">JEXL-398:</a></td>
            <td>Allow 'trailing commas' or ellipsis while defining array, map and set literals</td>
          </tr>
        </table>
      </p>
    </section>

    <section name="Bugs Fixed in 3.4:">
      <p>
        <table>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-420>">JEXL-420:</a></td>
            <td>Error while comparing float and string value</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-417>">JEXL-417:</a></td>
            <td>JexlArithmetic looses precision during arithmetic operator execution</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-416>">JEXL-416:</a></td>
            <td>Null-valued pragma throws NPE in 3.3</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-415>">JEXL-415:</a></td>
            <td>Incorrect template eval result</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-414>">JEXL-414:</a></td>
            <td>SoftCache may suffer from race conditions</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-412>">JEXL-412:</a></td>
            <td>Ambiguous syntax between namespace function call and map object definition.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-410>">JEXL-410:</a></td>
            <td>JexlFeatures: ctor does not enable all features</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-409>">JEXL-409:</a></td>
            <td>Disable LEXICAL should disable LEXICAL_SHADE</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-405>">JEXL-405:</a></td>
            <td>Recursive functions corrupt evaluation frame if reassigned</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-403>">JEXL-403:</a></td>
            <td>Exception while evaluating template literal used in array assignment in loop.</td>
          </tr>
          <tr>
            <td><a href="https://issues.apache.org/jira/browse/JEXL-423>">JEXL-402:</a></td>
            <td>parse failed with empty return value.</td>
          </tr>
        </table>
      </p>
    </section>
  </body>
</document>
