2.3.1 - FreeMarker Manual

- Home
- Manual
- Java API

- Contribute
- Report a Bug
- Download

Manual
Previous Next

# 2.3.1

Date of release: 2005-01-04

Maintenance (with some important new features) and bugfix release.

## Possible backward compatibility issue

There is a bugfix that may affect the behavior of you Web application if you use JSP tags in FreeMarker templates: FreeMarker's implementation of `javax.servlet.jsp.PageContext.getSession()` was incorrect. The `getSession()` method is a convenience method by which the custom tag can get the current `HttpSession` object (possibly `null` if there is no session). Till now, if the session didn't existed then it has created it automatically, so it never returned `null`. This was a bug, so starting from 2.3.1 it never creates the session, just returns `null` if it doesn't exist. The old incorrect behavior could cause page rendering to fail if the method is called after the page is partially flushed. But beware, the old behavior has possibly hidden some bugs of the Web application, where it forgot to create the session, so with the new correct behavior you may face malfunction caused by previously cloaked bugs of the Web application. (It's the task of the MVC Controller to create the session, except if the JSP tag that needs a session is written so it creates it automatically, but then it doesn't expects that `getSession()` will do it.)

## Changes on the FTL side

- New built-in: `url`. This built-in can be used for URL escaping. Note, however, that to use this built-in conveniently, the software that encapsulates FreeMarker has to be 2.3.1 aware (programmers will find more info bellow...).

- New special variables: `output_encoding` and `url_escaping_charset`. Note, however, that to use these, the software that encapsulates FreeMarker has to be 2.3.1 aware (programmers will find more info bellow...).

- New built-ins for sequences: `seq_contains`, `seq_index_of`, `seq_last_index_of`.

- New built-ins for strings: `left_pad`, `right_pad` and `contains`.

- New directive: `attempt`/`recover`

- The `js_string` built-in now escapes `>` as `\>` (to avoid `</script>`).

- The `sort` and `sort_by` built-ins now can sort by date values. Also, `sort_by` built-in now can sort by the subvarible of a subvariable of a subvariable... etc. for any level depth. (Details...)

- `freemarker.template.TemplateExceptionHandler.HTML_DEBUG_HANDLER` now prints more HTML-context-proof messages.

## Changes on the Java side

- New setting: `output_encoding`. This setting is used for informing FreeMarker about the charset that the enclosing software (as a Web application framework) uses for the output of FreeMarker. It's undefined by default, and although it is not strictly required to set it, the enclosing software should do so. This setting must be set if templates want to use the new `output_encoding` special variable, and possibly if they want to use the new `url` built-in. Note that the FreeMarker API allows you to set settings for each template execution individually (look at `Template.createProcessingEnvironment(...)`).

- New setting: `url_escaping_charset`. This is the charset used for calculating the escaped parts (`%XX`) when you do URL escaping with the new `url` built-in. If it is not set, then the `url` built-in uses the value of the `output_encoding` setting, and if that's not set either, then the parameterless version of `url` built-in (`${foo?url}`) can't be used.

- Using the singleton (static) `Configuration` instance is clearly a bad practice, so related methods are now deprecated, and the Manual was adjusted, and the `FreemarkerXmlTask` was updated as well.

- The `freemarker.template.utility.Constants` class was added that contains various static final fields that store frequently used constant `TemplateModel` values, as `EMPTY_SEQUENCE`, `ZERO`, ...etc.

- When using `SecurityManager` with FreeMarker, accessing system properties may caused AccessControlException. Now such exceptions are catched and logged with warning level, and the default value of the property is returned.

- The needles `InvocationTargetException` is now removed from the exception cause trace in certain cases.

- Added a dirty hack that prints `ServletException` root cause in `TemplateException`'s stack trace if that's the direct cause exception of the `TemplateException`, despite the poorly written `ServletException` class.

- Bugfix: FreeMarker's implementation of `javax.servlet.jsp.PageContext.getSession()` was incorrect. The `getSession()` method is a convenience method by which the custom tag can get the current `HttpSession` object (possibly `null` if there is no session). Till now, if the session didn't existed then it has created it automatically, so it never returned `null`. This was a bug, so starting from 2.3.1 it never creates the session, just returns `null` if it doesn't exist. The old incorrect behavior could cause page rendering to fail if the method is called after the page is partially flushed. But beware, the old behavior has possibly hidden some bugs of the Web application, where it forgot to create the session, so with the new correct behavior you may face malfunction caused by previously cloaked bugs of the Web application. (It's the task of the MVC Controller to create the session, except if the JSP tag that needs a session is written so it creates it automatically, but then it doesn't expects that `getSession()` will do it.)

- Bugfix: The `BeansWrapper` didn't always handled properly the case of a Java class having both a public static field and a public static method with the same name.

- Bugfix: `SimpleMethodModel` had incorrectly propagate exceptions sometimes, causing null pointer exception.

- Bugfix: The template execution may used outdated cached values when you have processed the same `Environment` for multiple times, and changed settings between the two processings. Note that this could happen only in single-thread environment, where such setting modifications are allowed.

- Bugfix: Some of the string built-ins has died with `IndexOutOfBounds` exception if the template author has forgotten to specify required parameters. Now they die with more helpful error messages.

- Bugfix: `freemarker.ext.dom.NodeModel.equals(...)` has died with null pointer exception if its argument was `null`.

- Bugfix: The cause exception of `TemplateException`-s was sometimes printed twice in stack traces with J2SE 1.4 or later.

- Bugfix: The `StringUtil.FTLStringLiteralEnc(String)` method was finished.

## Other changes

- Fixes and improvements in the Manual and in the API JavaDoc.

## The history of the releases before the final version

### Differences between the preview release and final release

- Added a dirty hack that prints `ServletException` root cause in `TemplateException`'s stack trace if that's the direct cause exception of the `TemplateException`, despite the poorly written `ServletException` class.

- Bugfix: `freemarker.ext.dom.NodeModel.equals(...)` has died with null pointer exception if its argument was `null`.

- Bugfix: The cause exception of `TemplateException`-s was sometimes printed twice in stack traces with J2SE 1.4 or later.

- More minor improvements in the Manual.

Previous Next