Migrating from Velocity

Disclaimer: This page is OLD, and had to be reviewed. Or rather, US Cavarly should be. Thus no links points to it from our homepage anymore.

If you have just discovered FreeMarker and would like to switch to it, but you have existing solutions that use Velocity here are the steps you have to take to convert to FreeMarker. If you wonder why would you want to switch to using FreeMarker, here's a quick summary of FreeMarker vs. Velocity features features.

Convert your templates

To help you convert your templates, we supply you with an automatic template converter, codenamed "US Cavalry". It will read and parse your Velocity templates, then write them out in FreeMarker syntax. It can 100% read any valid Velocity 1.2 template, since it actually uses a modified version of Velocity parser code. Download US Cavalry and launch it from the command line to convert the templates:

USCavalry0_3.tar.gz (431K bytes)
Download via HTTP

Convert your Java code

Once you're through the template conversion process, you have to rewrite your Java code so that it uses FreeMarker instead of Velocity. If you use the latest preview of 2.1 release, then you have to create an instance of freemarker.template.Configuration - it is the central management class in FreeMarker 2.1. You can use it as-is to have templates loaded from the current directory, or pass it an instance of freemarker.cache.TemplateLoader that knows how to load templates from some custom source. From there on, you ask for a freemarker.template.Template by its name, and pass the root data model (this was named "context" in Velocity) to its process() method.

If you're using the last public release, the 2.0.3 version, then the process is a little bit different. Here you create an instance of freemarker.template.FileTemplateCache instead of Configuration, but the rest of the process is similar to the above.

Note that in FreeMarker, you can use a huge variety of data model to Java object mappings. Velocity's approach - namely to map template expressions to direct reflective methods invocations on Java objects - is just one of possibilities in FreeMarker. Since during the migration you'll probably want to stick with this data model mapping (at least for a while), you'll have to run your context objects through an adapter named freemarker.ext.beans.BeansWrapper before placing them into the context. Also note that FreeMarker uses the Java built-in Beans introspection, so - contrary to Velocity - it completely adheres to introspection rules.

Convert your servlets

If you were using Velocity in a servlet environment, you can either use the guidelines set out in previous section "Convert your Java code", to convert your servlet code, or you can try out the full-featured, easily extensible freemarker.ext.servlet.FreemarkerServlet.

Replacing Anakia

If you were using the Velocity's Anakia tool, you'll be pleased to know that there's an equivalent tool in FreeMarker. It has a less poetic name "FreemarkerXmlTask", and it does just what Anakia did - converts XML documents through a template as part of an Ant build process. You'll however find that thanks to the FreeMarker's notion of abstract data models the syntax for dealing with XML documents in FreeMarker is orders of magnitude more intuitive than what Anakia offers you. In our opinion, that is. The "FreemarkerXmlTask" is included in the FreeMarker download.

Alternatively, if the "FreemarkerXmlTask" is not enough feature rich for your job, you can use FMPP.