The "incompatible improvements" setting
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.
The incompatible improvements setting exists on the
Configuration level. It can be set on multiple ways:
- Create the
... = new Configuration(Configuration.VERSION_2_3_28)
- Or, alter the
Configurationsingleton where you initialize its other settings like:
- Or, if you are configuring FreeMarker with properties (
- Or, if you are configuring FreeMarker through
FreemarkerServlet, add this
init-paramto it in the
<init-param> <param-name>incompatible_improvements</param-name> <param-value>2.3.28</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
BeansWrapper it's the same, only with different class name of course).
Do not ever use
Configuration.getVersion() to set the "incompatible improvements" setting. Always use a fixed value, like
Configuration.VERSION_2_3_28 . 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.