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_encodingandurl_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_padandcontains. -
New directive:
attempt/recover -
The
js_stringbuilt-in now escapes>as\>(to avoid</script>). -
The
sortandsort_bybuilt-ins now can sort by date values. Also,sort_bybuilt-in now can sort by the subvarible of a subvariable of a subvariable... etc. for any level depth. (Details...) -
freemarker.template.TemplateExceptionHandler.HTML_DEBUG_HANDLERnow 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 newoutput_encodingspecial variable, and possibly if they want to use the newurlbuilt-in. Note that the FreeMarker API allows you to set settings for each template execution individually (look atTemplate.createProcessingEnvironment(...)). -
New setting:
url_escaping_charset. This is the charset used for calculating the escaped parts (%XX) when you do URL escaping with the newurlbuilt-in. If it is not set, then theurlbuilt-in uses the value of theoutput_encodingsetting, and if that's not set either, then the parameterless version ofurlbuilt-in (${foo?url}) can't be used. -
Using the singleton (static)
Configurationinstance is clearly a bad practice, so related methods are now deprecated, and the Manual was adjusted, and theFreemarkerXmlTaskwas updated as well. -
The
freemarker.template.utility.Constantsclass was added that contains various static final fields that store frequently used constantTemplateModelvalues, asEMPTY_SEQUENCE,ZERO, ...etc. -
When using
SecurityManagerwith 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
InvocationTargetExceptionis now removed from the exception cause trace in certain cases. -
Added a dirty hack that prints
ServletExceptionroot cause inTemplateException's stack trace if that's the direct cause exception of theTemplateException, despite the poorly writtenServletExceptionclass. -
Bugfix: FreeMarker's implementation of
javax.servlet.jsp.PageContext.getSession()was incorrect. ThegetSession()method is a convenience method by which the custom tag can get the currentHttpSessionobject (possiblynullif there is no session). Till now, if the session didn't existed then it has created it automatically, so it never returnednull. This was a bug, so starting from 2.3.1 it never creates the session, just returnsnullif 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 thatgetSession()will do it.) -
Bugfix: The
BeansWrapperdidn'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:
SimpleMethodModelhad incorrectly propagate exceptions sometimes, causing null pointer exception. -
Bugfix: The template execution may used outdated cached values when you have processed the same
Environmentfor 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
IndexOutOfBoundsexception 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 wasnull. -
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
ServletExceptionroot cause inTemplateException's stack trace if that's the direct cause exception of theTemplateException, despite the poorly writtenServletExceptionclass. -
Bugfix:
freemarker.ext.dom.NodeModel.equals(...)has died with null pointer exception if its argument wasnull. -
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.
