Apache Velocity: Is there a standard way of verifying the correctness of a template from the command line?

Question

Our website uses the Apache Velocity template language. Our Content Management System already checks any generated XML documents for well-formedness. We've been asked to check documents to catch Velocity syntax errors before pushing the files to the live site.

Is there a standard way of verifying the correctness of a Velocity template from the command line?

I am prepared to read in the template path, initialize the Velocity Engine, parse the template, and capture any errors as shown on this page, but if there's a ready made tool that takes a file and a configuration, and spits out any errors, then I'd rather use that.

---

Update

Here's what I ended up doing:

package velocitysample;

import java.io.IOException;
import java.io.StringWriter;
import org.apache.log4j.Logger;
import org.apache.log4j.BasicConfigurator;
import org.apache.velocity.VelocityContext;
import org.apache.velocity.Template;
import org.apache.velocity.app.Velocity;
import org.apache.velocity.exception.ResourceNotFoundException;
import org.apache.velocity.exception.ParseErrorException;
import org.apache.velocity.exception.MethodInvocationException;

public class Main
{
   /** Define a static logger variable so that it references the Logger
    *  instance named "MyApp".
    */
    private static Logger logger = Logger.getLogger(Main.class);


    /**
     * @param args the command line arguments
     */
    public static void main(String[] args)
    {

        /* Set up a simple log4j configuration that logs on the console. */
        BasicConfigurator.configure();


        /* Check to see that a template path was passed on the command line. */
        if (args.length != 1)
        {
            logger.fatal("You must pass the path to a template as a " +
                    "command line argument.");
            return;
        }

        /* Pull the template filename from the command line argument. */
        String fileName = args[0];

        try
        {
            Velocity.setProperty("resource.loader", "file");
            Velocity.setProperty("file.resource.loader.class", "org.apache.velocity.runtime.resource.loader.FileResourceLoader");
            Velocity.setProperty("file.resource.loader.path", "/templates/");
            Velocity.setProperty("file.resource.loader.cache", "false");
            Velocity.setProperty("file.resource.loader.modificationCheckInterval", "0");

            Velocity.init();
        }
        catch (Exception ex)
        {
            logger.fatal("Error initializing the Veolcity engine.", ex);
            return;
        }

        boolean error = false;

        /* Create an empty Velocity context */
        VelocityContext context = new VelocityContext();

        Template template = null;

        try
        {
           template = Velocity.getTemplate(fileName);
        }
        catch( ResourceNotFoundException rnfe )
        {
           logger.error("Couldn't find the template to parse at this path: " +
                   fileName + ".", rnfe);
           error = true;
        }
        catch( ParseErrorException peex )
        {
            logger.error("Error parsing the template located at this path: " +
                    fileName + ".", peex);
            error = true;
        }
        catch( MethodInvocationException mie )
        {
            logger.error("Something invoked in the template (" + fileName +
                    ") threw an Exception while parsing.", mie);
            error = true;
        }
        catch( Exception e )
        {
            logger.error("An unexpected exception was thrown when attempting " +
                    "to parse the template: " + fileName + ".", e);
            error = true;
        }

        if (error)
        {
            return;
        }

        StringWriter sw = new StringWriter();
        try
        {
            template.merge(context, sw);
        } 
        catch (ResourceNotFoundException rnfe)
        {
            logger.error("Couldn't find the template to merge at this path: " +
                   fileName + ".", rnfe);
            error = true;
        } 
        catch (ParseErrorException peex)
        {
            logger.error("Error parsing the template at this path during merge: " +
                    fileName + ".", peex);
            error = true;
        } 
        catch (MethodInvocationException mie)
        {
            logger.error("Something invoked in the template (" + fileName +
                    ") threw an Exception while merging.", mie);
            error = true;
        } 
        catch (IOException ioe)
        {
            logger.error("Error reading the template located at this path from " +
                    "disk: " + fileName + ".", ioe);
            error = true;
        }
        catch( Exception e )
        {
            logger.error("An unexpected exception was thrown when attempting " +
                    "to merge the template: " + fileName + ".", e);
            error = true;
        }

        if (!error)
        {
            logger.info("No syntax errors detected.");
        }
    }
}

Answer 1

There is a tool distributed with Velocity called TemplateTool, which dumps all the references and it can be used to validate the syntax of the template.

However, you must have the context setup correctly to verify any template. So the best verification is to write your own tool with your own context.

Answer 2

To catch Velocity syntax errors, your approach is probably the best.

However, it will ignore invalid macro arguments and non-existent references. In Velocity 1.6 there is a strict mode that you can set which will throw an exception for bad macro parameters (e.g. the wrong number) or for bad references (e.g. $abc.badMethod() ). This assumes you are populating the context of the templates used in your testing tool the same as when the templates are used in production.

Answer 3

In December 2010 someone published a tool for validating Velocity. I tried it out and it works fine. It uses Velocity 1.6.4, but maybe that can be swapped out for a different version if needed.

http://code.google.com/p/velocity-validator/