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
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
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
... = 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
your configuration, then it's important to know that
BeansWrapper and its subclasses (most
DefaultObjectWrapper) has its own
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
incompatibleImprovements property of the
ObjectWrapper itself, in additionally to that of
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
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.