FreeMarker Blog

The official weblog of the FreeMarker project

Tuesday, February 14, 2006

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 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:


<#include "b.ftl"/>

<#macro printFoo y>

<@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:
==> ${} [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.


At Fri Feb 17, 08:15:00 AM GMT+1, Blogger Dániel Dékány said...

Error reporting like this is such a basic thing for any computer language. So, really, there is nothing wonderful about FreeMarker's error reporting. Anyway, it's not a too good quality one, like the message of most syntax errors is really unusable for anybody but a hardcore programmer. So, the wonder is that FreeMarker stand out with this error reporting compared to Velocity. What the hell? It's joke. Did people forget coding, or the ones who can run away when they see ASF/Velocity, or what? And, after several years, Velocity 1.5 will have better error reporting than earlier versions. But as far as I know, it still will not print template-language stack traces, just a single error position...

At Fri Feb 17, 05:05:00 PM GMT+1, Blogger Jonathan Revusky said...

Line-precise error reporting was also one of the two features that the Webwork people mention as being behind their Velocity-FreeMarker migration. The other feature was (your) JSP taglib support.

Though actually, if you google around looking at postings by Velocity refugees explaining their reasons for switching to FreeMarker, it's all over the board really. Some people mention the macro system, others mention the XML processing capabilities, others mention the whitespace handling.

Daniel, Velocity 1.5 retains all the same default behaviors of sweeping errors under the carpet. To get error messages when you misspell a variable for example will require a custom configuration. And, of course, as you point out, the errors will, in the general case, be unsatisfactory because they will not have a full execution trace.

So there is no competition emerging from the Velocity community on this front (or practically any other AFAICS). Still, we could well look at improving the readability of error messages. That said, most professional programming tools output error messages that would be pretty cryptic for non-technical people.

At Mon May 01, 03:00:00 PM GMT+2, Anonymous Anonymous said...

The only thing keeping me from switching to freemarker is the "!" character.
freemarker==better features, but its more of a pain in the butt during actual implementation.

I like returning a null model object to the "new" on crud pages and do not believe that should be an error. I don't believe the "edit" should require a different template.

I wish I could do -->

I like the error reporting on syntax problems, but fields in objects can be null. Just let it be.


Post a Comment

Links to this post:

Create a Link

<< Home