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_ofand?seq_last_index_ofnow works on collections (freemarker.template.TemplateCollectionModel-s) too, not only on sequences (freemarker.template.TemplateSequenceModel-s). -
?longnow works for date, date-time or time values, and returns the milliseconds since the epoch (asjava.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_datetimewas added. See more here... (Unfortunately,?dateand 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 like2010-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}". -
?sortand?sort_bynow 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_ofand?seq_last_index_ofhas failed with non-java.util.Listjava.util.Collection-s that are wrapped with pureBeansWrapper(not theDefaultObjectWrapper) asTemplateSequenceModel. (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
FileTemplateLoaderand 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 outputWriteris automatically flushed at the end ofTemplate.process(Object, Writer)(and its overloads). The default istrue, which corresponds to the earlier behavior. Usingfalseis 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 separateTemplate.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), ornew_builtin_class_resolverproperty. This allows you to specify how thenewbuilt-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 offreemarker.core.Configurable.setSettingandfreemareker.template.Configuration.setNewBuiltinClassResolver. Otherwise it's still recommended to set this toTemplateClassResolver.SAFER_RESOLVER(orsaferif 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 inConfigurationdisables caching. -
Added
getSupportsIndexedAccess()tofreemarker.ext.beans.CollectionModel, so one can check ifTemplateSequenceModel.get(int)will work with a particularCollectionModelinstance or not. -
Bug fixed [2992265]: JSP
FreeMarkerPageContext.includebehaved 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 insidefreemarker.ext.jsp.FreeMarkerPageContext.popWriter. -
Bug fixed [3033015]:
AllHttpScopesHashModelusedWrappingTemplateModel.getDefaultObjectWrapper()for wrapping variables in the page scope, while used the user-specifiedObjectWrapperfor all other scopes (request, session, etc.). Now it uses the user-specified wrapper in the page scope as well. -
Bug fixed [3128073]:
HashAdapther.containsKey(...)returnedtruefor a key that doesn't exist when unwrapping the key has failed. As a side effect of the fix,BeansWrapper.CAN_NOT_UNWRAPis now private; earlier it was public by mistake. -
Big fixed [3151085]:
freemarker.jsp.TaglibFactorydidn't locate tld files properly. This fix gives better compliance with JSP specification for resolving and loading tld files. -
Bug fixed: Unwrapping
nullwith aBeansWrapperthat had a custom null-model didn't result innull. Now both unwrappingnulland the custom null-model givesnull. -
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 (theThrowableobjects) 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.jarunderfreemarker/ext/jspare now under Apache Software License, Version 2. This is also clarified in theLICENSE.txt. Earlier these files had no clear license terms.
