2.3.17 - Apache FreeMarker Manual

Unsupported web browser - Use a modern browser to view this website!

- Home
- Manual
- Java API

- Contribute
- Report a Bug
- Download

Manual
Previous Next

# 2.3.17

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.

Previous Next