Release date: 2020-02-16 + release process
Please note that with this version the minimum required Java version was increased from Java 5 to Java 7.
Changes on the FTL side
?with_args_last(dynamicArguments)to add parameters dynamically to directive (like macro), function and method calls. Actually, this built-in returns a directive or macro or function that has different parameter defaults. See more here...
FREEMARKER-107: Added new special variable,
.args. This evaluates to a hash in macros, and to a sequence in functions, which contains all the arguments. This is useful for operations that act on all the arguments uniformly, like for example to pass the arguments to
Macro catch-all parameters (aka. varargs parameters), when capture arguments passed by name (as opposed to by position), now keep the original order of arguments. Earlier the order wasn't predictable.
Bug fixed: In
<#escape placeholder as escExpression>, the
placeholderwasn't substituted inside lambda expressions inside
escExpression. Fortunately it's very unlikely that anyone wanted to use lambdas there (given the few built-ins that accept lambdas).
Changes on the Java side
The minimum required Java version was increased from Java 5 to Java 7.
FREEMARKER-124: Made the default filtering of class members more restrictive (when you are using
BeansWrapper, or its subclasses like
DefaultObjectWrapper). This is not strictly backward compatible, but unlikely to break any real-world applications; see
src/main/resources/freemarker/ext/beans/DefaultMemberAccessPolicy-rulesto see what was changed. This change was made for security reasons, but the default behavior will never be safe enough if untrusted users will edit templates; see in the FAQ. In the unlikely case this change breaks your application, then you can still use the old behavior by setting the
memberAccessPolicyproperty of the object wrapper to
freemarker.ext.beans.MemberAccessPolicyinterface, and the
BeansWrapper, and subclasses like
DefaultObjectWrapper. This allows users to implement their own program logic to decide what members of classes will be exposed to the templates. See See the FreeMarker Java API documentation for more details.
freemarker.ext.beans.WhitelistMemberAccessPolicy, which is a
MemberAccessPolicyfor use cases where you want to allow editing templates to users who shouldn't have the same rights as the developers (the same rights as the Java application). Earlier, the only out of the box solution for that was
SimpleObjectWrapper, but that's too restrictive for most applications where FreeMarker is used.
DefaultObjectWrapper(or any other
BeansWrapper), allowing you to use all features of it, but it will only allow accessing members that were explicitly listed by the developers, or was annotated with
FREEMARKER-125: FreeMarker now picks up
DecimalFormatSymbolsprovided by the
DecimalFormatSymbolsProviderSPI. This is useful if you need to change the decimal format symbols provided for a locale by Java.
BeansWrapper(and it's subclasses like
DefaultObjectWrapper) now has two protected methods that can be overridden to monitor the accessing of members:
incompatibleImprovementsto the instance returned by
Configuration.getVersion()will now be logged as an error, but for backward compatibility it will still work. This applies to said setting of
BeansWrapper. The typical bad pattern is this:
new Configuration(Configuration.getVersion()). Doing that defeats the purpose of
incompatibleImprovements, and makes upgrading FreeMarker a potentially breaking change. Furthermore, doing this probably won't be allowed starting from 2.4.0, and will throw exception. So if above mistake is present in your application, it should be fixed by setting
incompatibleImprovementsto the highest concrete version that's known to be compatible with the application.
Bug fixed: AST traversal API now can properly traverse the inside of lambda expressions (such as the parameter list)
Added a new
SimpleHashconstructor, where the caller can provide the
Mapinstance used as the backing storage, thus allows controlling the ordering, and other technical aspects (like the initial capacity) of it.