Velocity - An Introduction

by Thomas Paul

The Early Years of Servlet Development

I started working on my first servlet application shortly after the Java
Servlet specification was released. It became readily apparent that Servlets
were not designed to separate the Java developer from the HTML developer. In
fact, since the HTML was inside the Java program, even trivial changes to HTML
required the Java programmer to change code, recompile, and in many cases
restart the Servlet engine. We realized that this would make our
applications difficult to maintain so we started looking for other
options. We eventually developed a system based on three major
requirements:

1) The HTML must be kept in a separate file from the Servlet and can be
easily changed without recompiling the Servlet.

2) The HTML must be easily edited with any of the many HTML tools
available.

3) The Servlet must be able to plug dynamic content into the HTML easily.

If Velocity had been around then, we could have saved ourselves a lot of
trouble because Velocity serves exactly this purpose.

The Advantages of Velocity

Velocity is a simple to use, open source web framework designed to be used as
the view component of an MVC architecture. You can use it as a
replacement for JSP or alongside JSP. It fits very well into more complex
frameworks such as Struts or Turbine.

The main advantage of using Velocity over JSP is that Velocity is simple to
use. The Velocity Template Language (VTL) is so constrained in its capabilities
that it helps to enforce separation of business logic from the view. You
won't see any Java classes in a Velocity template (an HTML document with some
Velocity placeholders). In fact, Velocity is so simple to use that you can
teach your HTML team how to use Velocity in just a few hours.

Installing Velocity

Assuming you already have Tomcat installed, create a new web project called
velocity and set up the appropriate WEB-INF directories. Under WEB-INF, in
addition to lib and classes directories, create a directory called
templates.

Velocity is very easy to install.You can get Velocity from the binary
download page of the Apache Jakarta Project. (http://jakarta.apache.org/site/binindex.cgi)
Download the zip or tar file. Inside you will find two jar files named,
velocity-1.3.1.jar and velocity-dep-1.3.1.jar. Extract these two files to
the WEB-INF\lib directory of your velocity web project.

That's it. Velocity is now installed. The Velocity jar files
should always be added to the lib directory for each Velocity project.

A Basic Velocity Program

Instead of going into a long, boring discussion of Velocity, let's look at a
simple example of a Velocity program.We will start by assuming that we have
created a web project called velocity in our Tomcat installation.

We will need to setup our web.xml file in our project's WEB-INF
directory. Here is what it may look like:

This is a fairly typical web.xml file. We have added one parameter
representing the properties file used by Velocity. The properties file
tells Velocity where to find the templates it will use and how to process them.
Here is a sample properties file:

The resource.loader tells Velocity that we will be getting the
templates from files. Other options such as reading them from a jar file
are also available. file.resource.loader.class tells Velocity the name of
the class to use to read the files. file.resource.loader.path tells
Velocity where to look for the templates.
file.resource.loader.cache controls whether the templates will be
cached. For performance reasons you will almost always wish to select
true. file.resource.loader.modificationCheckInterval tells Velocity
to check to see if a template has been changed in two second intervals. Setting
this option to 0 will turn checking off.

A Velocity template is simply an HTML document with some special placeholders
that Velocity will recognize and replace with data you supply in your Java
program. For our simple test, we have a template named hello.vm.(It is
standard practice to name Velocity templates with the extension of
vm.) Place the template in our WEB-INF/templates directory.

<html>
<body>
Hello $name
</body>
<html>

Sample 3. hello.vm

The $name in the document is a placeholder or reference in Velocity
terminology. When we run our Java program using this template $name will
be replaced with the data we supply in our program. Let's look at a
Velocity Servlet.

The code is actually quite simple.Our Servlet extends VelocityServlet which
is the base class for Servlets in Velocity. We override the
handleRequest() method which will be invoked when the Servlet is executed.
Beside the normal HttpServletRequest and HttpServletResponse objects, Velocity
also passes us a Context object. We will place the data we wish to use to fill
the placeholders with into the Context object.In the example, the $name will be
replaced by "Velocity Test". We must return a Template object. In
our example, we are returning the template that we created above.

Using a Java Class in a Template

That was simple so now let's look at something a little more complex.
Although we could fill our Context object with separate Strings for each
placeholder, this isn't always required. We could create a Java class with
the appropriate get methods and pass that to our template.

Let's create a simple Customer class to use in our example. The class
has set and get methods that we can use to access the private Customer
variables.

The Servlet creates a Customer object and puts it into the Context
object. It then returns the customer template. How does the customer
template access the data from the Customer object? The answer is that we
use a simple dot notation.

Each placeholder will invoke the get method from the Customer object.
For example, $customer.name will invoke the getName() method of the Customer
object.

Do you notice what is missing from the template? There is no mention
of the Java class whatsoever. Although we used $customer, that was only
because "customer" was the name used when the Customer object was placed into
the Context object. Because this template doesn't know anything about a
specific Java class, it will work with any Java class as long as it has the
matching get methods.

To test this, update your web.xml file and try running it.

Using the Velocity Template Language

VTL is fairly simple but it does provide some very useful
functionality. There is, for example, an if-then-else structure
available. The most useful VTL command is the #foreach command which
allows you to process through a Collection object. This will allow you to
display a list of data on your HTML page. For a quick example, let's add
a few invoices to the customer page.

First, we will need an invoice object. I have created a very simple
example excluding most of the information you would include in a real invoice
class. However, in addition to the normal get method for each variable, I
have added a special display method that will format the data for output.
Here is the Invoice class:

#foreach will start a loop. The loop will allow us to process
all the data in the ArrayList. $customer.invoices runs the
getInvoices() method of the Customer object which returns an ArrayList.
Each entry in the ArrayList is extracted one at a time and named
$invoice. $invoice.orderDateDisplay will run the
getOrderDateDisplay method of the Invoice object. An iteration of the loop
is terminated with the #end command. When all the entries of the
ArrayList have been processed, we will leave the loop.

Conclusions

Velocity is amazingly easy to use and to integrate into any Servlet
application. Simpler than JSPs, Velocity forces you to separate logic from
content because VTL is so limited in its capabilities. Since velocity uses
placeholders in an HTML document, it is very easy to code your HTML using a
fancy HTML editor. The placeholders simply mark the place in your document
that will get replaced with real data.

Velocity can run standalone outside of a Servlet engine if you like.
You could, for example, use Velocity to read in a file and write out a new file
with the placeholders updated. In addition, Velocity has a suite of tools
that can be used that provide additional functionality.

Overall, Velocity is an extremely nice product. Because it is so
simple and concentrates on a single aspect of your web architecture it can be
easily integrated into almost any web development project.