2.3.1

Page Contents

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.