Feature in spotlight: Error reporting

Max Rydahl Andersen, a Hibernate developer tells us "A story about FreeMarker and Velocity" on the Hibernate groupblog. It is later covered on TheServerSide.com as well. Looks like that the one feature among all things that particularly convinced Max to abandon Velocity and start using FreeMarker was - drumroll - error reporting. Now, error reporting is not a functionality that's usually prominently displayed on a product's feature sheet, yet if done right it is invaluable for time efficient problem solving when things go wrong.

So, what's it all about?

Well, it works like this: when FreeMarker encounters an error, it'll not only pinpoint the exact column and line where the error occurred, but it will display a full template stack trace containing all macro invocations and includes that led to the point of exception. To illustrate it with an example, consider we have two templates, a.ftl and b.ftl:

a.ftl:

<#include "b.ftl"/>

b.ftl:

 
<#macro printFoo y> 
${y.foo} 
</#macro>

<@printFoo bar/> 

Then you'll see this output (assuming your error was that "bar" is a simple string instead of a hash):

Expected hash. y evaluated instead to freemarker.template.SimpleScalar
on line 2, column 3 in b.ftl. 
Quoting problematic instruction: 
---------- 
==> ${y.foo} [on line 2, column 1 in b.ftl] 
in user-directive printFoo [on line 5, column 1 in b.ftl] 
in include "b.ftl" [on line 1, column 1 in a.ftl] 
---------- 

So you can see precisely what template execution path led to the error - invaluable to figure out what's going on when you can have macros and includes invoked from multiple locations.