The "incompatible improvements" setting - 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

# The "incompatible improvements" setting

## What does it do

This setting specifies the FreeMarker version number where the not 100% backward compatible bug fixes and improvements that you want to enable were already implemented. Usually, it's a bad idea to left it on its default, which is 2.3.0 (maximum backward compatibility).

In new projects you should set this to the fixed FreeMarker version (like `Configuration.VERSION_2_3_28`) that you are actually using when starting the project. In older projects it's also usually better to keep this high , however you should check the changes activated (find them in the API JavaDoc of the `Configuration(Version)` constructor), especially if not only the 3rd version number (the micro version) of "incompatible improvements" setting is increased. Generally, as far as you only increase the last (3rd) version number of this setting, the changes are low risk, and whether you can afford that risk depends on the concrete application. Never use a dynamic value like `Configuration.getVersion()` though, as that way upgrading FreeMarker can break your application!

Bug fixes and improvements that are fully backward compatible, also those that are important security fixes, are enabled regardless of the "incompatible improvements" setting.

An important consequence of setting this setting is that now your application will check if the stated minimum FreeMarker version requirement is met. Like if you set this setting to 2.3.22, but accidentally the application is deployed with FreeMarker 2.3.21, then FreeMarker will fail, telling that a higher version is required. After all, the fixes/improvements you have requested aren't available on a lower version.

## How to set it

The incompatible improvements setting exists on the `Configuration` level. It can be set on multiple ways:

- Create the `freemarker.template.Configuration` object like:

      ... = new Configuration(Configuration.VERSION_2_3_35)

- Or, alter the `Configuration` singleton where you initialize its other settings like:

      cfg.setIncompatibleImprovements(Configuration.VERSION_2_3_35)

- Or, if you are configuring FreeMarker with properties (`*.properties` file or `java.util.Properties` object), add:

      incompatible_improvements=2.3.35

- Or, if you are configuring FreeMarker through `FreemarkerServlet`, add this `init-param` to it in the `web.xml`:

      <init-param>
          <param-name>incompatible_improvements</param-name>
          <param-value>2.3.35</param-value>
      </init-param>

But, if you set the `object_wrapper` setting (same as `Configuration.setObjectWrapper(ObjectWrapper)`) of your configuration, then it's important to know that `BeansWrapper` and its subclasses (most importantly, `DefaultObjectWrapper`) has its own independent `incompatibleImprovements` property, and some fixes/improvements are activated by that, not by `Configuration`'s similar setting. You don't have to be aware of this complication if you aren't setting the `object_wrapper` configuration setting anywhere, because the default `object_wrapper` has the same "incompatible improvements" as of the `Configuration`. But if you are setting the `object_wrapper`, then you must not forget to set the `incompatibleImprovements` property of the `ObjectWrapper` itself, in additionally to that of the `Configuration`. (Note that it's fine to have different "incompatible improvements" for the `Configuration` and for the `ObjectWrapper`, only it should be a conscious decision.) See here how to set it in the case of `DefaultObjectWrapper` (for `BeansWrapper` it's the same, only with different class name of course).

Warning!

Do not ever use `Configuration.getVersion()` to set the "incompatible improvements" setting. Always use a fixed value, like `Configuration.VERSION_2_3_34`. Otherwise your application can break as you upgrade FreeMarker. The whole point of "incompatible improvements" is to protect you from that, while you still always get the fixes/improvements that are backward compatible.

Previous Next