Common Java Cookbook

Edition: 0.19

Download PDF or Read on Scribd

Download Examples (ZIP)

9.13. Using Velocity in a Web Application

9.13.1. Problem

You are sick of writing JSP and having to wait for pages to compile. You would like to find a way to use Velocity instead of JSP.

9.13.2. Solution

Configure your web application to use the VelocityViewServlet to render your Velocity templates. Download the latest version of the VelocityView project from http://velocity.apache.org/; it is listed under "Velocity Tools 1.1." Put the velocity and velocity-tools jars in the WEB-INF/lib directory, and configure your web application to render templates ending in *.vm with the VelocityViewServlet. Add the following servlet and servlet-mapping elements to your web.xml file as follows:

<!-- Define Velocity template compiler -->
<servlet>
  <servlet-name>velocity</servlet-name>
  <servlet-class>
    org.apache.velocity.tools.view.servlet.VelocityViewServlet
  </servlet-class>
  <load-on-startup>10</load-on-startup>
</servlet>
.....other servlets.....
<!-- Map *.vm files to Velocity -->
<servlet-mapping>
  <servlet-name>velocity</servlet-name>
  <url-pattern>*.vm</url-pattern>
</servlet-mapping>

All requests ending in *.vm are processed by the VelocityViewServlet, which locates the appropriate Velocity template in the document root of your web application. Attributes from the request, session, and application scope will be available as variables in the VelocityContext.

To test this configuration, create a simple Velocity template in the document root of your web application named index.vm, start your servlet container, and attempt to render the template by loading http://<server>/<web-app>/index.vm in a browser. If everything is set up correctly, you should see the rendered template. If the configuration is not correct, you will see the source for your Velocity template.

9.13.3. Discussion

JSP compilation is an annoyance, especially if you are constantly altering and debugging JSP—all that waiting around adds up over the course of a long project. Using Velocity can help improve performance; the simplicity and elegance of Velocity makes parsing and executing a template fast and efficient. If you are looking for a viable alternative to JSP, try Velocity as your view layer, and you might be surprised.

Velocity can be a refreshing break from JSP, and almost any web application framework will work with Velocity. If you are working with an existing web application, there is no need to stop using JSP in lieu of Velocity; you can use both technologies in the same web application. Templates ending in *.jsp will be rendered by the existing JSP servlet, and templates ending in *.vm will be rendered by the VelocityViewServlet.

9.13.4. See Also

VelocityTools also contains a project named VelocityStruts, which provides tools to integrate Velocity with Struts. The VelocityStruts project has tools that duplicate the functionality of the Struts JSP tag libraries—a FormTool corresponds to the html tag library, a MessageTool duplicates the bean:message tag, a TilesTool provides access to the Struts tiles plug-in. It is possible to introduce Velocity into an existing Struts application by simply adding the servlet and serlvet-mapping to web.xml, as shown above. Configure the VelocityViewServlet, and configure an Action to forward to a velocity template; configure the struts tools by following the directions on the VelocityStruts user guide (http://velocity.apache.org/tools/releases/1.4/struts/).


Creative Commons License
Common Java Cookbook by Tim O'Brien is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 United States License.
Permissions beyond the scope of this license may be available at http://www.discursive.com/books/cjcook/reference/jakartackbk-PREFACE-1.html. Copyright 2009. Common Java Cookbook Chunked HTML Output. Some Rights Reserved.