FreeMarker 2.03 (Lazarus) README

Freemarker Authors

Freemarker 1 (Classic) was originally written by Benjamin Geer and Mike Bayer. They defined the basic syntax -- and more importantly, the philosophy -- of the tool that is carried on in Freemarker 2. Significant contributions to Freemarker Classic were made by Nicholas Cull, Holger Arendt and others.

Though Freemarker 2 (Lazarus) is virtually a complete rewrite, it is almost entirely backward compatible with Freemarker Classic. The core (parser/compiler) of Freemarker was rewritten by Jonathan Revusky using a popular parser generator tool, JavaCC. Major contributions were made by Attila Szegedi, who, besides refactoring some of the core API's for this release, is the author of the freemarker.ext.* code (a.k.a. the expose package) which previously lived in the contrib directory. Many ideas and feedback were provided by the various participants on the freemarker-devel mailing list. People who are interested in influencing (and even participating in) further Freemarker development are strongly encouraged to subscribe to the freemarker-devel mailing list.

By community consensus, the Lazarus release is under the more liberal BSD-style license. (Freemarker Classic was released under the LGPL.) Benjamin Geer, the main author of Freemarker 1, remains the copyright holder. It was decided that, since we do not currently have a juridical entity (such as the Apache Foundation) to play this role, that Benjamin Geer would continue to be the sole copyright holder. Though various people have contributed to Freemarker development, to have one individual be copyright holder makes future license changes or clarifications simpler.

Freemarker is an ongoing open source project with an active developer community. Check back for updates at http://freemarker.sourceforge.net.


Click here for the manual.

Click here for javadoc-generated documentation.

Note: the classes in freemarker.jar have been compiled with javac with full debug information and no optimization. This is because we want a complete stack trace on any bug reports. You do have the option of rebuilding with optimization="on" and debug="off" by changing the appropriate line in the ant build script.

If you are interested in an application framework that is well integrated with Freemarker, you might want to look into the Niggle Web Application Framework. Niggle leverages Freemarker for the presentation layer but gives you a lot more besides, such as easy integration with SQL/JDBC data sources as well as transparent data validation. By using Niggle, you can get your servlet development off to a running start, since you start in essence with a skeletal web application based on the model-view-controller (MVC) paradigm. Niggle-based web applications tend to be extremely robust and maintainable. (Disclosure note: Niggle was written and is maintained by the author of this document, Jonathan Revusky.)

License Info

This library is free software; you can redistribute it and/or modify it under the terms of the BSD-style license that should be included with the Freemarker distribution.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the accompanying license for more details.


Version history

This is version 2.03, released on 12 June 2002. The main reason for this release is that the last release did full page buffering of output if you set debug mode to false. It really turns out that this was not desirable and had some very bad performance implications, particularly on Windows systems. Also, some API changes were made that will be present in 2.1.x.

Since these API's are changing in 2.1, it was considered that people might as well adjust to them now.

API Changes

The various Template.process() methods take a java.io.Writer rather than a java.io.PrintWriter. Cpnsequently, they also throw java.io.IOException in addition to freemarker.template.TemplateException. So, some java code code will definitely have to be tweaked a bit to compile against this release. It is fairly trivial though. Note that, also, the transform() method in the TemplateTransformModel interface was changed to take a Writer rather than a PrintWriter and also, the transform() method throws IOException as well as TemplateException..

Bug-fixes

Aside from the potential performance problem caused by full-page-buffering in 2.02, there are no bug-fixes to speak of in this release. Nor have there been any changes in the template language syntax.


Version 2.02 was released on 3 June 2002. This was a bug-fix maintenance release in the 2.0x series. New development on FreeMarker is for the 2.1 release. The main bug-fix was an interaction between the newly introduced <break> and <return> instructions and the <compress> and <transform> instructions. Since the latter two instructions buffered output, if you broke out of a loop or returned early from a function, and the block was nested within a compress or a transformation block, the buffered output would be lost. This has been fixed.

There was a glitch where methods in a numerical context were called more than once. This would only be a significant issue if the method call, instead of just returning the value, had side effects in the application. This glitch has been fixed in 2.02

API Changes

Other than a couple of extra convenience methods in the freemarker.template.Template class, there are no API changes between 2.01 and 2.02.

Template Language Changes

By popular appeal, you can now write the \lt, \gt operators without the initial backslash. Thus, lt, gt, lte and gte cannot be used as top-level variable names. Note that true and false cannot be used as top-level variable names either. No use is made of these names in this release, but these are reserved words in the 2.1 branch, used to represent boolean true and false respectively.


Version 2.01 was released on May Day, 2002. This version contains no changes to the template language or bugfixes, since no bugs had been reported against 2.0 final. The main improvement is in error reporting. Now exceptions are much more informative since they come with complete line number and column information.

API Changes

The only API change between 2.0 and 2.01 was the elimination of the CacheListener/CacheEvent API. Now, if the updating of a template file fails, the exception is thrown back to the caller to handle. If you want logging to occur when a template file is updated successfully, you can override the logFileUpdate() method in FileTemplateCache.


FreeMarker 2.0 final was released on 18 April 2002. The changes with respect to the previous release, 2.0 RC3 are fairly minor.

Bugfixes

Changes to the Template language

Changes to the API

Miscellania

The ant build script build.xml now contains a target that builds a .war file containing the Hello, World example and the guestbook. It builds a fmexamples.war. For example, if you are using Tomcat in its out-of-the-box configuration, you would place this under <TOMCAT_HOME>/webapps and then you would use http://localhost:8080/fmexamples/servlet/hello and http://localhost:8080/fmexamples/servlet/guestbook for the Hello, World and Guestbook examples respectively.


FreeMarker 2.0 RC3 was released on 11 April 2002. This release was primarily devoted to fixing bugs that were reported in RC2.

Bugfixes

Changes to the Template Language

API changes


FreeMarker 2.0 RC 2 was released on 4 April 2002. Here is a summary of changes wrt to the first release.

Changes to Template Language

API Changes


The first public release of Freemarker 2.0 was on 18 March 2002. Here is a summary of the changes in the Lazarus release, with respect to the last stable release of Freemarker Classic.

Support for Numerical operations, both arithmetic and boolean, as well as numerical ranges.

API Changes

Syntactical Miscellania


NOTA BENE: Despite the changes delineated above, the Lazarus release is almost entirely backward-compatible with Freemarker Classic. We believe that most existing code and templates that work under Freemarker Classic will continue working under Lazarus, with at most minimal changes. In practice, the most common cases where legacy template code is broken will be where assumptions were made about numbers and strings being equivalent. Note that in Freemarker 2, 2 + 2 does not result in "22". The String "1" and the number 1 are entirely different animals and thus, any code will be broken if it relies on the boolean expression ("1"==1) being true. There is a "classic compatibility mode" that can be set via: Template.setClassCompatibility() that can be set so that Lazarus emulates some of the quirky behavior of FreeMarker Classic. However, any code that relied on the above "features" of Freemarker classic really should be reworked. You are less likely to run into the other incompatibilities that are listed above. If you come across any other anomalies, please do tell us about them.


Document last updated 12 June 2002 by Jonathan Revusky