FreeMarker Changelog

New in version 2.3.20

June 28th, 2013
  • Changes on the FTL side:
  • Error message quality improvements:
  • Many error messages are now more helpful, especially for users who are not experienced with FreeMarker. For example, some of the most common user mistakes are recognized and tips are shown to fix them, reducing support costs or the time employees spend to figure them out.
  • It's now ensured that the error location in the template is included in the message returned by TemplateException.getMessage(). The stack trace always showed this information anyway, but some users only see the "message", not the stack trace, and that often didn't contained the location.
  • The template language part of the stack trace is now more detailed, and easier to understand. This is especially helpful in applications that use a complex library of macros and functions.
  • Several smaller bugs were fixed that made the error information wrong or lacking.
  • The layout of the error messages is now more consistent, and generally easier to read.
  • Changes regarding boolean to string conversions and formatting:
  • ?c (computer-language formatting) now works with booleans too, always giving "true" or "false" regardless of the boolean_format. This way it's safe for generating JavaScript in a context where human-readable text is also rendered.
  • If the boolean_format setting is set to anything but the default "true,false" value, boolean values will be automatically converted to string where a string value is expected by the template language, instead of giving an error. This helps you spare those?string-s after boolean values. This is the same logic as with numbers and dates, which were always automatically converted to string, according the corresponding format setting. Except, the provided default boolean format is useless for automatic conversion (but it's still there for ?string, for backward compatibility), hence it must be set manually. (We certainly couldn't come up with a sensible default anyway, as for booleans it depends too much on the application, not to mention the localisation issues.)
  • Exactly like with numbers and dates, automatic conversion doesn't happen in these cases:
  • Comparisons, i.e., someBoolean == 'true' is still an error
  • Method calls where the declared type of the parameter is String but the actual value is a boolean; still an error
  • When the boolean value is used as key in expr[key], it's still an error (there was no automatic conversion there for other types either, as numerical and string keys have different meaning)
  • The opposite direction, i.e., string to boolean conversion; won't happen
  • New built-ins for numbers: abs, is_nan, is_infinite. Like n?abs will give the absolute value of n.
  • New built-in for sequences: join. Like [1, 2, 3]?join(", ") will give the string "1, 2, 3".
  • If you set the incompatible_improvements setting (see here) to 2.3.20 or higher, ?html will escape apostrophe-quotes just like ?xhtml does. Utilizing this is highly recommended, because otherwise if interpolations are used inside attribute values that use apostrophe-quotation () instead of plain quotation mark (), they might produce HTML/XML that's not well-formed. Note that ?html didn't do this because long ago there was no cross-browser way of doing this, but it's not a real concern anymore. Also note that this will be the default behavior starting from 2.4.
  • Bug fix [390] (and other improvements): ?js_string and ?json_string didn't escape the u2028-u2029 line terminators (problem for JavaScript) and the u007F-u009F control characters (maybe a problem in JSON, depending on implementation). Furthermore, the escaping of \, become safer in that now they are escaped whenever it can't be guaranteed that they won't be part of or

New in version 2.3.19 (March 1st, 2012)

  • Changes on the FTL side:
  • Attention: The output of ISO 8601 date/time formatting built-ins, introduced in 2.3.17, was slightly changed. From now on, the time zone offset, when it's displayed and it isn't Z, always includes the minutes. For example, 15:30:15+02 becomes to 15:30:15+02:00 in the template output. Both formats are valid according to ISO 8601 (so anything that expects ISO 8601 date/times should continue working), but only the last format complies with the XML Schema date/time formats, hence this change.
  • New built-in for escaping inside JSON string literals: json_string.
  • Bugfix: Wrong # tags were printed as static text instead of causing parsing error if there was no correct # tag earlier in the same template. Since fixing this would not be 100% backward compatible, the old behavior has remained, unless you set the incompatible_enhancements setting (Configuration.setIncompatibleEnhancements(String)) to "2.3.19" or higher.
  • Changes on the Java side:
  • Attention: This release contains two important security workarounds that unavoidably make it obvious how some applications can be exploited. FreeMarker can't solve these issues on all configurations, so please read the details instead of just updating FreeMarker! Also, these changes are not 100% backward compatible in theory, however it's not probable that they will break anything. The two changes are:
  • The character with character code 0 (\u0000) is not allowed in template paths anymore. When a path contains it, FreeMarker behaves as if the template was not found.
  • This is to fix the security problem where a template path like "secret.txt\u0000.ftl" is used to bypass extension filtering in an application. FreeMarker itself doesn't care about the extension, but some applications decide based on the extension if they will delegate a path to FreeMarker. When they do with such a path, the C/C++ implementation behind the storage mechanism may sees the path as "secret.txt" as the 0 terminates the string in C/C++, and thus load a non-FTL file as a template, returning the file contents to the attacker.
  • Note that some HTTP servers, notably Tomcat and Apache will block URL-s containing 0, but some others, like Jetty, doesn't.
  • ClassTemplateLoader, when it's created with base path "/" (like with new ClassTemplateLoader(someClass, "/")), will not allow template paths that contain colon earlier than any /, and will act like if the template was not found in such case.
  • This is to fix the security problem where a template path like "file:/etc/secret" or "http://example.com/malware.ftl" is interpreted as a full URL by a java.net.URLClassLoader in the class-loader hierarchy. This is a quirk (or bug) of java.net.URLClassLoader.
  • Beware, some frameworks use their own TemplateLoader implementations, and if those are vulnerable, they will remain so after updating FreeMarker too! Note that this exploit only works if the class-loader hierarchy contains an URLClassLoader and the class-loader is used to load templates without adding any prefix before the template path (other than "/").
  • These security issues mostly affect applications where the user (the visitor) can supply arbitrary template paths. This is not the case with properly built MVC applications, as there only the Controller can be addressed directly, and it's the Controller who specifies the template paths. But MVC applications based on JSP Model-2 often expose the MVC Views as URL-s ending with .ftl, thus allowing the user to give arbitrary paths to FreeMarker. Such applications should be secured with a security-constratint in web.xml as shown in the related Manual section. This should be done regardless of the current security fixes.
  • Configuration has new methods: removeTemplateFromCache(...). This will remove the given template for the given locale from the cache, so it will be re-loaded regardless of the template update delay when it's next time requested.
  • BeansWrapper ignores setter methods from now when introspecting classes. They weren't used anyway, so they unnecessarily caused "java.beans.IntrospectionException: type mismatch between read and write methods" errors.
  • TemplateClassResolver.SAFER_RESOLVER now disallows creating freemarker.template.utility.JythonRuntime and freemarker.template.utility.Execute. This change affects the behavior of the new built-in if FreeMarker was configured to use SAFER_RESOLVER, which is not the default until 2.4 and is hence improbable.
  • Bug fixed: Calling varargs methods now indeed works. (Earlier it only worked for overloaded methods.)
  • Bug fixed [1837697] [2831150] [3039096] [3165425]: Jython support now works with Jython 2.2 and 2.5.
  • Bug fixed [3325103]: TemplateException-s and ParseException-s are now serializable.

New in version 2.3.18 (May 23rd, 2011)

  • Bugfix [3304568]: 2.3.17 didn't find TLD-s in WEB-INF\lib\*.jar unless they were explicitly pointed in the web.xml with a taglib element. This bug was introduced in 2.3.17.
  • Added LICENSE.txt and NOTICE.txt to freemarker.jar under META-INF.

New in version 2.3.17 (May 17th, 2011)

  • 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(...), , ).
  • You are not effected 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 , 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 interestered; 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.

New in version 2.3.16 (December 10th, 2009)

  • Fixed a bug that caused incorrect unwrapping of sequences to Java arrays (See bug report)
  • Created a new freemarker.runtime.attempt category and exceptions caught in < #attempt > blocks are logged into it at a DEBUG severity.
  • Fixing the (ages old) problem of RhinoWrapper not working with all versions of Rhino because of binary incompatible change of Rhino's Undefined.instance.
  • Macro names can no longer be changed through the API.

New in version 2.3.15 (December 16th, 2008)

  • Changes on the FTL side:
  • In web pages that are based on the FreemarkerServlet, you can now use < @include_page path="..."/ > to use servlet includes. See: http://freemarker.org/docs/pgui_misc_servlet.html#pgui_misc_servlet_include
  • Changes on the Java side:
  • The BeansWrapper can automatically detect that classes were reloaded by JavaRebel.
  • Fixed a bug that caused null to be returned from Environment.getCurrentEnvironment() while processing autoincludes and autoimports.
  • Fixed a bug that caused getObject(Object) method on POJOs to not be recognized as a general get method.
  • Substantially improved performance of the directive.
  • DeepUnwrap now unwraps custom null model of the current object wrapper into a Java null.

New in version 2.3.14 (September 1st, 2008)

  • Bugfixes and some new features.