Date of release: 2011-05-17

It's possibly urgent to update to this version because of a security fix!

Changes on the FTL side

• ?seq_index_of and ?seq_last_index_of now works on collections (freemarker.template.TemplateCollectionModel-s) too, not only on sequences (freemarker.template.TemplateSequenceModel-s).

• ?long now works for date, date-time or time values, and returns the milliseconds since the epoch (as java.util.Date.getTime()).

• To convert numbers (usually Java long-s) to date or date-time and time values, ?number_to_date, ?number_to_time, ?number_to_datetime was added. See more here... (Unfortunately, ?date and like can't be extended to support this due to backward compatibility issues.)

• New built-ins to format numbers with ISO 8601 "extended" format regardless of the current date/time formatting settings, and even regardless of the current time zone setting. For example ${myTimeStamp?iso_utc} will print something like 2010-05-16T23:05:45Z. See more here...

• New special variable, now. This returns the current date-time. Usage examples: "Page generated: ${.now}", "Today is ${.now?date}", "The current time is ${.now?time}".

• ?sort and ?sort_by now supports sorting boolean values.

• When using unsupported or unknown string built-in flags, FreeMarker will now log warnings (maximum 25 times per class-loader, to prevent flooding the log). It's certain that starting from FreeMarker 2.4 these will count as errors.

• Bug fixed [3047201]: Using regular expressions (like with ?match) could cause lockup in multi-threaded environment, also memory leakage when using dynamically generated regular expressions.

• Bug fixed: ?seq_contains, ?seq_index_of and ?seq_last_index_of has failed with non-java.util.List java.util.Collection-s that are wrapped with pure BeansWrapper (not the DefaultObjectWrapper) as TemplateSequenceModel. (See also: getSupportsIndexedAccess() below)

Changes on the Java side

• Security fix: Using carefully crafted template names (template paths) that contain code point 0 ('\u0000'), it was possible to load files from outside the template root directory like if they were FreeMarker templates. The root of the problem is that the underlying native C/C++ part (which belongs to the Java platform or to the OS) interprets the 0 as the end of the string, while Java (and hence FreeMarker and the Servlet container) doesn't. Thus a path that looked safe for FreeMarker become unsafe on the lower level. The problem is present with all ways of loading templates by name (Configuration.getTemplate(...), <#include ...>, <#import ...>).

  You are not affected if you don't allow users to upload templates and also at least one of these stands:

  • In your system users can't provide arbitrary strings as template names (template paths). For example, if users are only allowed to visit the URL-s that belong to the MVC Controller (like they can't visit *.ftl) then they can't suggest arbitrary template names.

  • The template names are part of the path in the Web page URL, and your webserver or Servlet container disallows URL-s that contain %00, or terminate the URL at it before passing it to the servlets.

  • You are using FileTemplateLoader and linking is not allowed in it (by default it isn't allowed).

• FreeMarker now can log its messages directly using SLF4J or Apache Commons Logging. However, it will not use these logger libraries automatically, until 2.4; see more here... But it's recommended to switch to SLF4J now.

• New setting: "auto_flush", Configurable.setAutoFlush(boolean). Sets whether the output Writer is automatically flushed at the end of Template.process(Object, Writer) (and its overloads). The default is true, which corresponds to the earlier behavior. Using false is needed for example when a Web page is composed from several boxes (like portlets, GUI panels, etc.) that aren't inserted with #include (or with similar directives) into a master FreeMarker template, rather they are all processed with a separate Template.process(...) call. In a such scenario the automatic flushes would commit the HTTP response after each box, hence interfering with full-page buffering, and also possibly decreasing performance with too frequent and too early response buffer flushes.

• Added new setting: Configuration.setNewBuiltinClassResolver(TemplateClassResolver), or new_builtin_class_resolver property. This allows you to specify how the new built-in (like in "com.example.SomeClass"?new()) resolves classes and which classes are accessible at all. If you are allowing not-so-much-trusted users to upload templates, you should be definitely interested; see the Java API docs of freemarker.core.Configurable.setSetting and freemareker.template.Configuration.setNewBuiltinClassResolver. Otherwise it's still recommended to set this to TemplateClassResolver.SAFER_RESOLVER (or safer if you are using properties), although that's not 100% backward compatible (see Java API docs) .

• Added freemarker.cache.NullCacheStorage: Setting this as the cache storage in Configuration disables caching.

• Added getSupportsIndexedAccess() to freemarker.ext.beans.CollectionModel, so one can check if TemplateSequenceModel.get(int) will work with a particular CollectionModel instance or not.

• Bug fixed [2992265]: JSP FreeMarkerPageContext.include behaved incorrectly.

• Bug fixed: When using FreeMarker's JSP support with JSP tags that use javax.servlet.jsp.PageContext.pushBody (like some Stripes tags), "ArrayIndexOutOfBoundsException: -1" occurred inside freemarker.ext.jsp.FreeMarkerPageContext.popWriter.

• Bug fixed [3033015]: AllHttpScopesHashModel used WrappingTemplateModel.getDefaultObjectWrapper() for wrapping variables in the page scope, while used the user-specified ObjectWrapper for all other scopes (request, session, etc.). Now it uses the user-specified wrapper in the page scope as well.

• Bug fixed [3128073]: HashAdapther.containsKey(...) returned true for a key that doesn't exist when unwrapping the key has failed. As a side effect of the fix, BeansWrapper.CAN_NOT_UNWRAP is now private; earlier it was public by mistake.

• Big fixed [3151085]: freemarker.jsp.TaglibFactory didn't locate tld files properly. This fix gives better compliance with JSP specification for resolving and loading tld files.

• Bug fixed: Unwrapping null with a BeansWrapper that had a custom null-model didn't result in null. Now both unwrapping null and the custom null-model gives null.

• Log messages doesn't contain line-breaks (CR or LF) anymore and quote paths and other arbitrary text with Java string literal syntax that also escapes < characters as \u003C. These address security concerns related to poor quality log appenders and buggy log readers. This change is mostly noticeable on template processing error entries, which will now quote the exception message. Note that how stack traces (the Throwable objects) are logged is still up to the logging framework you are using.

Other changes

• The DTD-s and XSD-s that are included in freemarker.jar under freemarker/ext/jsp are now under Apache Software License, Version 2. This is also clarified in the LICENSE.txt. Earlier these files had no clear license terms.