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_28)

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

  cfg.setIncompatibleImprovements(Configuration.VERSION_2_3_28)

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

  incompatible_improvements=2.3.28

• 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.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 DefaultObjectWrapper (for BeansWrapper it's the same, only with different class name of course).