Velocity or FreeMarker?

Two open source Java-based template engines compared

Page 3 of 3

Velocity and FreeMarker

Velocity and FreeMarker are the two template engines that seem to enjoy the most widespread use. Both are general-purpose template engines, so if you want to evaluate them for use in your projects you should look at a number of criteria. In the next sections I'll compare Velocity and FreeMarker in terms of power, ease of use, and performance.

In some cases these criteria juxtapose each other; for instance, power often diminishes ease of use. The ideal balance between these is of course subjective. You may require a level of fine-grained control that justifies many Off switches, whereas someone else could be happy with just one On/Off button.


A simple "Hello World!" template is no problem for any template engine. The more interesting features can be found in Velocity and FreeMarker's inclusion and macro functions. Another important consideration is the way the template engine allows you to manipulate variable data while merging data and the template. Table 2 compares the features found in FreeMarker and Velocity.

Table 2. FreeMarker and Velocity compared

Iteration Yes Yes
Conditional processing Yes Yes
Macros Yes Yes
Includes other templates Yes Yes
Parses included templates Yes Yes
Executes embedded Java code No Only if the objects are available in the context supplied to Velocity

FreeMarker is stricter than Velocity. Velocity allows references to non-existing properties, and will even do so silently if the template designer wishes. FreeMarker is more formal and will generate a null pointer exception and at least log it. The macro capabilities of FreeMarker are more sophisticated: macros can be called recursively. In general, FreeMarker offers more functionality to template designers, such as breaking out of loops, detecting if the current iteration is the last in a loop, and comparing date and time values. FreeMarker also allows you to use multiple namespaces for variables, which is handy for structuring libraries of macros. On the other hand, you may not require so much sophistication from a template engine, and the learning curve for FreeMarker is a little steeper than the one for Velocity.

You can enhance Velocity with components that provide specialized functionality. For example, Texen embeds Velocity in an Ant task, and Anakia can be used to transform XML documents.

Ease of use

A number of factors contribute to ease of use. I'll look at three: ease of install, consistency of the API, and the quality of the documentation.

Installing both Velocity and FreeMarker is easy: just download the current version and install it in your directory of choice. This procedure should look familiar to anyone who has ever included a library in a project. Velocity depends on a number of other libraries, which are included in the distribution.

The API documentation of both Velocity and FreeMarker is available in API doc format. Both come with an overview of the template language, which is aimed at template designers, and a developer's guide, which is aimed at programmers who want to use the template engine as an application component. The basic usage pattern of both is very simple: instantiate an engine or template, feed it the data, and call a parse function to create the output. Both template engines support the use of the Writer interface to write the output to, giving you a wide range of options to capture the output.

FreeMarker also offers a conversion tool to convert Velocity templates to FreeMarker templates. This will save you a lot of time if you end up migrating from Velocity to FreeMarker.

Both FreeMarker and Velocity sport resource loaders, which are classes providing functionality to load templates and other resources from a number of locations like the file system or an HTTP server. These can be useful when building an application that uses a large number of templates that are stored in some organized manner. Applications that use only one or two templates can just as easily do their own resource management and pass the template as a String to the engine.


The performance of any template engine depends on the surrounding application as much as the template engine itself. An application can help the template engine achieve maximum throughput. Consider caching the contents of templates in memory, especially if you're not using the engine's inclusion feature.

I did not concern myself with the surrounding application while doing performance measurement because I wanted to focus on the performance of the template engine itself. I measured performance as elapsed wall time to accomplish a certain task. Since a template engine will always have a certain overhead associated with instantiation and initialization I tried to isolate the startup overhead from the measurements. Most overhead was encountered during the first parse of a template.

I performed a number of different tests, trying to cover most usage scenarios for a template engine. I ran all the tests using the IntelliJ IDEA 5.1 on Windows XP, using the Sun JRE v5. The relevant hardware specs are the CPU (AMD Mobile Athlon 3000+) and memory (512 MB of RAM). No special JVM parameters were used.

Both engines can be quite fast, so I measured not just the creation of a single output document, but the creation of thousands of outputs. To skip the overhead I started measuring just before the first call to parse the template. I measured in milliseconds, using the System.currentTimeMillis() call. Results are shown in Table 3.

Table 3. Performance measurement

Hello World! 110 141
Big Template 11647 32317

In conclusion

Both FreeMarker and Velocity are very capable template engines. Velocity seems to enjoy a larger user base, probably due to the fact that it is part of the Apache project. As I've shown in this article, though, FreeMarker is the more sophisticated and faster of the two. In basic operations both template engines are almost similar, providing an API that is easy to understand.

Both Velocity and FreeMarker are fairly easy to integrate into an application and offer good performance on small templates. Velocity slows down when parsing larger templates, which you might take into account when choosing a template engine for your project.

Jeroen van Bergen started working in information technology in 1993. He has worked in the fields of billing, systems integration, and order management in the telecommunication industry. He has been programming in Java since 2000. Jeroen is at the moment mainly interested in workflow, Java-XML binding, and automatic document generation using Velocity and XSL:FO.

Learn more about this topic

| 1 2 3 Page 3