2.3.30 - Apache FreeMarker Manual

Unsupported web browser - Use a modern browser to view this website!

- Home
- Manual
- Java API

- Contribute
- Report a Bug
- Download

Manual
Previous Next

# 2.3.30

Release date: 2020-03-05

Please note that with this version the minimum required Java version was increased from Java 5 to Java 7.

## Changes on the FTL side

- FREEMARKER-107: Added `?with_args(dynamicArguments)` and `?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 `?with_args(...)`.

- 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 `placeholder` wasn'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-rules` to 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 `memberAccessPolicy` property of the object wrapper to `LegacyDefaultMemberAccessPolicy.INSTANCE`.

- Added `freemarker.ext.beans.MemberAccessPolicy` interface, and the `memberAccessPolicy` property to `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.

- Added `freemarker.ext.beans.WhitelistMemberAccessPolicy`, which is a `MemberAccessPolicy` for 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. `WhitelistMemberAccessPolicy` works with `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 `@TemplateAccessible`.

- FREEMARKER-125: FreeMarker now picks up `DecimalFormatSymbols` provided by the `DecimalFormatSymbolsProvider` SPI. This is useful if you need to change the decimal format symbols provided for a locale by Java.

- FREEMARKER-120: `BeansWrapper` (and it's subclasses like `DefaultObjectWrapper`) now has two protected methods that can be overridden to monitor the accessing of members: `invokeMethod` and `readField`.

- Setting `incompatibleImprovements` to 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 `Configuration`, `DefaultObjectWrapper`, and `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 `incompatibleImprovements` to the highest concrete version that's known to be compatible with the application.

- Added `Environment.getDataModelOrSharedVariable(String)`.

- Bug fixed: AST traversal API now can properly traverse the inside of lambda expressions (such as the parameter list)

- Added a new `SimpleHash` constructor, where the caller can provide the `Map` instance used as the backing storage, thus allows controlling the ordering, and other technical aspects (like the initial capacity) of it.

Previous Next