Velocity - An Introduction

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:

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>

    <servlet>
        <servlet-name>HelloTest</servlet-name>
        <servlet-class>HelloTest</servlet-class>
        <init-param>
            <param-name>properties</param-name>
            <param-value>/WEB-INF/velocity.properties</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>HelloTest</servlet-name>
        <url-pattern>/HelloTest</url-pattern>
    </servlet-mapping>

</web-app>

Sample 1. web.xml

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:

resource.loader = file
file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader
file.resource.loader.path = c:/tomcat/webapps/velocity/WEB-INF/templates
file.resource.loader.cache = true
file.resource.loader.modificationCheckInterval = 2

Sample 2. velocity.properties

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.

import org.apache.velocity.Template;
import org.apache.velocity.servlet.VelocityServlet;
import org.apache.velocity.app.Velocity;
import org.apache.velocity.context.Context;
import javax.servlet.http.*;

public class HelloTest extends VelocityServlet {

    public Template handleRequest( HttpServletRequest request,
                                   HttpServletResponse response,
                                   Context context ) {

        Template template = null;

        try {
            context.put("name", "Velocity Test");
            template = Velocity.getTemplate("hello.vm");
        } catch( Exception e ) {
          System.err.println("Exception caught: " + e.getMessage());
        }

        return template;
    }
}

Sample 4. HelloTest.java

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. 

Running this from http://localhost:8080/velocity/HelloTest will produce a screen that says "Hello Velocity Test".

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.

package com.javaranch.velocity;

public class Customer {

    String customerNumber;
    String name;
    String address;
    String city;
    String state;
    String zip;
    String phone;

    public String getCustomerNumber() {return customerNumber;}
    public void setCustomerNumber(String s) {customerNumber = s;}
    public String getName() {return name;}
    public void setName(String s) {name = s;}
    public String getAddress() {return address;}
    public void setAddress(String s) {address = s;}
    public String getCity() {return city;}
    public void setCity(String s) {city = s;}
    public String getState() {return state;}
    public void setState(String s) {state = s;}
    public String getZip() {return zip;}
    public void setZip(String s) {zip = s;}
    public String getPhone() {return phone;}
    public void setPhone(String s) {phone = s;}
}

Sample 5. Customer.java

Now let's create a test Servlet to create a Customer object and pass it to a template.

import org.apache.velocity.Template;
import org.apache.velocity.servlet.VelocityServlet;
import org.apache.velocity.app.Velocity;
import org.apache.velocity.context.Context;
import javax.servlet.http.*;
import com.javaranch.velocity.Customer;

public class CustomerSearch extends VelocityServlet  {

    public Template handleRequest( HttpServletRequest request,
                                   HttpServletResponse response,
                                   Context context )  {

        Template template = null;
        Customer customer = getCustomer();

        try  {
            context.put("customer", customer);
            template = Velocity.getTemplate("customer.vm");
        }  catch( Exception e )  {
          System.err.println("Exception caught: " + e.getMessage());
        }

        return template;
    }

    private Customer getCustomer()  {
        Customer customer = new Customer();
        customer.setCustomerNumber("ABC123");
        customer.setName("Joe JavaRanch");
        customer.setAddress("123 Rancho Javo");
        customer.setCity("Bueno Ranch");
        customer.setState("CO");
        customer.setZip("63121");
        customer.setPhone("303-555-1212");
        return customer;
    }
}

Sample 6. CustomerSearch.java

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.

<html>
<head><title>Customer Search Results - $customer.customerNumber</title></head>
<body bgcolor="#faf7f1">
    <h1>Customer information for customer number $customer.customerNumber</h1>
    <b>Name:</b> $customer.name<br>
    <b>Address:</b> $customer.address<br>
    <b>City:</b> $customer.city<br>
    <b>State:</b> $customer.state<br>
    <b>Zip:</b> $customer.zip<br>
    <b>Phone:</b> $customer.phone<br>
</body>
<html>

Sample 7. customer.vm

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:

package com.javaranch.velocity;

import java.util.*;
import java.text.*;

public class Invoice {

    Date orderDate;
    Date shipDate;
    float invoiceTotal;
    float shipTotal;
    float taxTotal;
    DateFormat df = DateFormat.getDateInstance(DateFormat.LONG);

    public Date getOrderDate() {return orderDate;}
    public String getOrderDateDisplay() {return df.format(orderDate);}
    public void setOrderDate(Date s) {orderDate = s;}

    public Date getShipDate() {return shipDate;}
    public String getShipDateDisplay() {return df.format(shipDate);}
    public void setShipDate(Date s) {shipDate = s;}

    public float getInvoiceTotal() {return invoiceTotal;}
    public String getInvoiceTotalDisplay() {
        return NumberFormat.getCurrencyInstance().format(invoiceTotal);
    }
    public void setInvoiceTotal(float s) {invoiceTotal = s;}

    public float getShipTotal() {return shipTotal;}
    public String getShipTotalDisplay() {
        return NumberFormat.getCurrencyInstance().format(shipTotal);
    }
    public void setShipTotal(float s) {shipTotal = s;}

    public float getTaxTotal() {return taxTotal;}
    public String getTaxTotalDisplay() {
        return NumberFormat.getCurrencyInstance().format(taxTotal);
    }
    public void setTaxTotal(float s) {taxTotal = s;}
}

Sample 8. Invoice.java

We update the Customer class to include an ArrayList to hold invoices and add a couple of methods to add and get the Invoices:

package com.javaranch.velocity;

import java.util.*;

public class Customer2 {
    ?
    ArrayList invoices = new ArrayList();
    ?
    public void addInvoice(Invoice invoice) {invoices.add(invoice);}
    public ArrayList getInvoices() {return invoices;}
}

Sample 9. Customer2.java

The code above is added to the Customer object we created earlier.

Now we need a test Servlet to load the Customer2 object with Invoices and invoke the Velocity Template.

import org.apache.velocity.Template;
import org.apache.velocity.servlet.VelocityServlet;
import org.apache.velocity.app.Velocity;
import org.apache.velocity.context.Context;
import javax.servlet.http.*;
import java.util.*;
import com.javaranch.velocity.*;

public class CustomerSearch2 extends VelocityServlet 
{
    
    public Template handleRequest( HttpServletRequest request,
                                   HttpServletResponse response,
                                   Context context )
    {
        
        Template template = null;
        Customer2 customer = getCustomer();
        
        try
        {
            context.put("customer", customer);
            template = Velocity.getTemplate("customer2.vm");
        }
        catch( Exception e )
        {
          System.err.println("Exception caught: " + e.getMessage());
        }
        
        return template;
    }
    
    private Customer2 getCustomer() {
        Customer2 customer = new Customer2();
        customer.setCustomerNumber("ABC123");
        customer.setName("Joe JavaRanch");
        customer.setAddress("123 Rancho Javo");
        customer.setCity("Bueno Ranch");
        customer.setState("CO");
        customer.setZip("63121");
        customer.setPhone("303-555-1212");
        addInvoices(customer);
        return customer;
    }
    
    private void addInvoices(Customer2 customer) {
        Invoice inv = null;
        Date[] datesOrder = {new GregorianCalendar(2004,01,21).getTime(),
            new GregorianCalendar(2003,11,18).getTime(), 
            new GregorianCalendar(2003,11,01).getTime()};
        Date[] datesShip = {new GregorianCalendar(2004,01,28).getTime(),
            new GregorianCalendar(2003,11,20).getTime(),
            new GregorianCalendar(2003,11,15).getTime()};
        float[] invTotals = {231.45f, 456.22f, 86.14f};
        float[] taxTotals = {18.21f, 43.18f, 3.11f};
        float[] shipTotals = {6.54f, 14.38f, 14.32f};
        for (int i=0; i<datesOrder.length; i++) {
            inv = new Invoice();
            inv.setOrderDate(datesOrder[i]);
            inv.setShipDate(datesShip[i]);
            inv.setInvoiceTotal(invTotals[i]);
            inv.setTaxTotal(taxTotals[i]);
            inv.setShipTotal(shipTotals[i]);
            customer.addInvoice(inv);
    }
}

Sample 10. CustomerSearch2.java

Now we need to create the new template.   We will add the #foreach command to process through the ArrayList.

<html>
<head>
    <title>Customer Search Results - $customer.customerNumber</title>
</head>
<body bgcolor="#faf7f1">
<h1>Customer information for customer number $customer.customerNumber</h1>
<b>Name:</b> $customer.name<br>
<b>Address:</b> $customer.address<br>
<b>City:</b> $customer.city<br>
<b>State:</b> $customer.state<br>
<b>Zip:</b> $customer.zip<br>
<b>Phone:</b> $customer.phone<br>
<p>
<h3>Recent Invoices:</h3>
<table border=1 cellspacing="0" cellpadding="5" >
<tr bgcolor="#FFFF00">
    <th>Order Date</th>
    <th>Ship Date</th>
    <th>Shipping Charge</th>
    <th>Tax</th>
    <th>Total Cost</th>
</tr>

#foreach ($invoice in $customer.invoices)
    <tr>
        <td>$invoice.orderDateDisplay</td>
        <td>$invoice.shipDateDisplay</td>
        <td>$invoice.shipTotalDisplay</td>
        <td>$invoice.taxTotalDisplay</td>
        <td>$invoice.invoiceTotalDisplay</td>
    </tr>
#end

</table>
</body>
<html>

Sample 11. customer2.vm

Let's look at this in detail.

#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. 

Discuss this article in The Big Moose Saloon!


Return to Top

Automate the build process of your J2ME project with Antenna

Introduction

I think that most people would agree that Ant is a wonderful build tool for Java applications. I don't always use it, but I try to. If you aren't using Ant and would like to learn how, check out Thomas Paul's article in the March, 2002 newsletter. If you are not convinced of it's usefulness, check out Frank Carver's series of articles on building Small and Simple Web Applications - the Friki way (see the links at the end of this article). I'll wait here.

If you are still here or have returned, then you may be wondering how this all applies to that J2ME project that you are working on. If so, then I'd like to introduce you to Antenna. All those nice conveniences that the Sun Wireless Tool Kit (hereafter referred to as WTK) provides can be done easily from your Ant build script.

Integrating the WTK into your build

Antenna introduces several Ant tasks that perform key functions of the WTK. Antenna relies on the WTK to do the brunt of the work, so you will need to have that installed. As with all optional Ant tasks, you need to let Ant know about them in your build file. Fortunately Ant makes this easy for you:

build.xml

<?xml version="1.0"?>

<project name="J2ME" default="build" basedir="." >
    
    <property name="wtk.home" value="c:\wtk"/>
    <taskdef resource="antenna.properties"/>

As I wrote before, Antenna relies on the WTK to provide the underlying functionality. It does this by using the wtk.home property to find where you have the WTK installed. Antenna defines all tasks in a file called "antenna.properties", which is in antenna-bin-0.9.11.jar. Ant will know what it needs to about the Antenna tasks after you add antenna-bin-0.9.11.jar to your Ant distribution's lib folder.

Automating your jad file

The WtkJad task writes your *.jad and manifest files so that you don't have to. It looks like this:

WtkJad

    <target name="make.jad">
        <wtkjad jadfile="bin/${midlet.name}.jad"
                jarfile="bin/${midlet.name}.jar"
                manifest="bin/MANIFEST.MF"
                name="${midlet.name}"
                vendor="${company.name}"
                version="1.0.0" >

            <midlet name="TinyClass" class="TinyClass" />
            <midlet name="TinyClass2" class="TinyClass2" />
            <midlet name="TinyClass3" class="TinyClass3" />

            <attribute name="districtNo" value="378" />

        </wtkjad>
    </target>

The target has several useful properties. The jadfile property, which is the only required property, tells the WTK what to name your jad file. The jarfile controls the values of the MIDlet-Jar-URL and MIDlet-Jar-Size properties in the jad file. The name property controls the name of your MIDlet suite. Vendor and version controls the jad properties of the same name. The manifest property controls the name and location of the manifest file.

The two elements of the wtkjad task are the midlet and attribute elements. The midlet element allows you to define each MIDlet in your suite. I've shown the name and class attributes, but there is also an icon attribute if you would like to define an icon as well. The attribute element allows you to define any other properties that need to be defined in your jad file. Running the above task will result in the following jad file being built for you:

mysuite.jad

MIDlet-Jar-URL: mysuite.jar
MIDlet-Jar-Size: 1791
MIDlet-Name: mysuite
MIDlet-Vendor: maphillips
MIDlet-Version: 1.0.0
MIDlet-1: TinyClass, , TinyClass
MIDlet-2: TinyClass2, , TinyClass2
MIDlet-3: TinyClass3, , TinyClass3
districtNo: 378

Compile and Preverify

The wtkbuild task extends Ant's javac task and adds a few properties to aid with your J2ME code. One of the big conveniences of this task is that there is no need to add midpapi.zip to your classpath. The task does that for you automatically. Another important, but optional, property is the preverify property. If you set this property to true, then the preverify process will run after your code is compiled. There is also a preverify task and a preverify property of the package task (explained later) so you have several points in which you can have the preverification occur. The wtkbuild task looks like this:

mysuite.jad

    <target name="compile" depends="init">
        <wtkbuild srcdir="src" destdir="classes" preverify="true" />
    </target>

Packaging your code

The wtkpackage task extends Ant's jar task and gives you a little more control over the packaging process. As stated previously, you may preverify during this task, but since we did that during the compile process, there is no need to here. It needs to know the directory you want to jar, the name of the jar file, and the name of the jad file. If you have any external libraries to include, you may do so with the libclasspath attribute. You may also run an obfuscator during the package process, but we'll save that for a separate task. The wtkpackage task looks like this:

mysuite.jad

    <target name="package" depends="compile, make.jad">
        <wtkpackage jarfile="bin/${midlet.name}.jar"
                    jadfile="bin/${midlet.name}.jad"
                    basedir="classes"
                    manifest="bin/MANIFEST.MF"
                    preverify="false"
                    libclasspath="lib"
        />
    </target>

Running the emulator

Running your MIDlet suite is made incredibly easy with the wtkrun task. It needs to know the name and location of the jadfile. It will use the default device of the WTK, but you may also use the device attribute to control this. The default behavior of this task is for Ant to pause while the emulator is running. That will allow you to see anything that the emulator writes to System.out or System.err. If you don't want this behavior, you can set the wait attribute to false. A simple wtkrun task looks like this:

mysuite.jad

    <target name="run" depends="package">
        <wtkrun jadfile="bin/${midlet.name}.jad" device="DefaultColorPhone" wait="true"/>
    </target>

Obfuscation

When you are ready to deploy your code, you may want to obfuscate it. The wtkobfuscate task will take care of it. It can use either the RetroGuard or ProGuard. ProGuard is the default, but you may use the obfuscator attribute to specify which to use. In order for this task to function properly, the jar file for the obfuscator you choose needs to either be in the WTK's bin folder or on your class path. The task looks like this:

mysuite.jad

    <target name="obfuscate" depends="package">
        <wtkobfuscate jarfile="bin/${midlet.name}.jar" obfuscator="retroguard"/>
    </target>

Conclusion

Antenna has made my development life much easier. I hope this introduction will make yours easier as well. The Antenna web site has valuable information to make the tool even more useful.

Small and Simple Web Applications - the Friki Way
Part 1
Part 2
Part 3
Part 4
Part 5
Part 6

Discuss this article in The Big Moose Saloon!


Return to Top

Use Custom Tags to Aggregate RSS Feeds into JSP-Based Web Apps

With the abundance of news and blog (Weblog) sites growing continuously, keeping track of what?s going on can be a daunting task. Fortunately, standards such as RSS (Really Simple Syndication) provide an easy way to grab content from a particular site and aggregate it into a news reader application. This means that, rather than looking for news yourself, your news reader monitors sites that you?re interested in and downloads new content as it?s published.

This is a great model and many people have taken the concept to the Web by aggregating other content on their own Websites and offering aggregation services via the Web. In this article, I?ll show you how to use JSP custom tags to implement this type of functionality as a reusable component within your own JSP-based Web applications. Although I?m assuming that you?re comfortable with Java and you have some working knowledge of building Web applications with JavaServer Pages (JSP), I won?t assume any knowledge of JSP custom tags. Before we get started, download the code we'll use in this article here.

RSS and News Aggregators - a Brief History

The RSS standard has been around for the last few years, but only recently has it really started to catch on. One of the reasons behind this is that software like MovableType and Radio Userland have made blogging available to the masses in an affordable package. Where previously, news sections of Websites contained snapshots of a particular company or individual, and were rarely updated, these RSS tools allow us to take a more dynamic approach, providing an easy mechanism by which to add new news items to sites.

Thanks to these tools, and the proliferation of news being presented via the Internet, keeping up to date is a much more difficult task than ever before. For this reason, a standard format was defined to allow news to be syndicated and aggregated through desktop applications called news readers.

The result was that RSS, the Really Simple Syndication format, was born. In essence, RSS is simply an XML document that can be used to describe the content available on a given Website. Typically, ?content? means news items, but other uses of RSS include summarising articles, short stories, and so on. A good example of an RSS feed is the UK news from the BBC. The introduction of the RSS standard format made the aggregation of content much, much easier than before.

Reading RSS Feeds from Java

Since RSS feeds are nothing more than standardised XML documents, reading and processing RSS is fairly easy in any language that provides support for XML. Now that J2SE 1.4 provides integral support for XML, it?s simply a matter of using the appropriate classes to read in the XML document. Once the document has been read, presenting it back to the user in a desktop or Web-based application is then trivial.

For the purpose of this article, I?m going to show how to aggregate content from an RSS feed into your own Web applications. The use of this technique can be applied across a wide range of applications, from corporate intranet sites aggregating content from various departments, to personal Websites aggregating content from friends and family.

Before we talk more about custom tags, let's quickly look at how we will read in the RSS feeds using Java code. Manipulating XML documents in Java code can be tedious and therefore, rather than code against the raw XML, I've chosen to build a very simple object representation of the RSS feed. The first class is called RssFeed, and this represents a given RSS feed that contains a number of items.

package rss;

import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;

public class RssFeed {

 private Collection items = new ArrayList();

 public void addItem(RssItem item) {
   items.add(item);
 }

 public Collection getItems() {
   return Collections.unmodifiableCollection(items);
 }

}

In reality, RSS feeds have other characteristics, but the collection of items is enough for our purposes. Next up is the Java class that represents an item in a RSS feed. Typically, several pieces of information will be presented for each item in the feed; I've chosen to wrap these within an object. The information that?s relevant for each item in this example is its title and a link (URL) back to the full story on the Web.

package rss;

public class RssItem {

 private String title;
 private String link;

 public String getTitle() {
   return title;
 }

 public void setTitle(String title) {
   this.title = title;
 }

 public String getLink() {
   return link;
 }

 public void setLink(String link) {
   this.link = link;
 }

}

The final piece of the puzzle is the class that will actually read the XML document and transform it into our object representation -- the RssReader class. Instead of getting bogged down with the syntax and semantics of reading XML files, the implementation of this class has been omitted. Essentially, all that the read() method does is access the RSS feed at the specified URL and convert each item contained within the feed into an RssItem object.

package rss;

public class RssReader {

 /**
  * Reads the RSS feed at the specified URL and returns an RssFeed instance
  * representing it.
  */
 public RssFeed read(String url) {
   ... body of method omitted ...
 }

}

This is all the logic we need to read RSS feeds. Let's now take a look at how to hook this into a JSP page.

Reading RSS Feeds from JSP

For the purposes of this article, I?m going to assume that you?ve chosen to build your Web application using Java Web technologies and, specifically, that you?re going to use JavaServer Pages (JSP). One of the great things about this technology is that it makes the injection of dynamic behaviour into your pages easy -- all you need to do is add a little Java here and there. For example, we could use the classes we've just built in a JSP page:

<%
 RssReader reader = new RssReader();
 RssFeed rssFeed = reader.read("http://www.acme.com/rss.xml");
 Iterator it = rssFeed.getItems().iterator();
 while (it.hasNext()) {
   RssItem rssItem = (RssItem)it.next();
%>
   <a href="<%= rssItem.getLink() %>"><%= rssItem.getTitle() %></a>
   <br />
<%
 }
%>

This code grabs the RSS feed from the specified URL and, using the standard java.util.Iterator class, loops over each item displaying a hyperlink back to the full story.

While embedding Java code as a scriptlet is useful, it can soon become problematic -- particularly if you need to reuse that code on other pages within your Web applications. After all, there is no easy way to reuse such code; to simply copy and paste the code throughout your application will eventually lead to maintainability issues, as changes need to be replicated in every occurrence of that script. Ideally, we want to reuse code at the component level, taking a given component and using it wherever necessary. JSP custom tags are the answer.

Wrapping the RSS Reader in a JSP Custom Tag

JSP custom tags are a means to wrap common and recurring logic into a form that?s reusable across the pages of your Web applications. In the current version of the JSP specification (1.2), the behaviour of a custom tag is implemented as a Java class that activates a specific interface, in much the same way you?d implement a servlet, for example. This Java class is generally called the tag handler.

The key difference between custom tags and regular Java classes lies in the way they?re used within JSP pages. Where Java code is simply embedded in the page, custom tags are used with an XML syntax. For example, here?s how the custom tag will be used when we?ve finished building it. Notice that here we have a starting tag, some body content, then the ending tag.

<rss:rssFeed url="http://www.acme.com/rss.xml">
 <a href="<%= rssItem.getLink() %>"><%= rssItem.getTitle() %></a>
 <br />
</rss:rssFeed>

This will achieve exactly the same result as the scriptlet code we saw before -- the tag provides the iteration over each item in the feed. Essentially, the tag is now the looping construct and the body content of the tag is evaluated for each iteration, in the same way that the content of a while loop is evaluated for each iteration. Custom tags provide us with a way to build cleaner, more concise JSP pages that benefit from the advantages of reusing components -- increased maintainability, quality, reliability, and so on.

Building a Tag Handler Class

Now that you have an understanding of why custom tags are useful, let?s take a look at how to build one. As I said before, the behaviour is wrapped up as a regular Java class that implements a specific interface. In the case of custom tags, the interface that must be implemented (at a minimum) is Tag, from the javax.servlet.jsp.tagext package. This interface is fairly straightforward and provides a number of callback methods that will be executed when the tag is used on a JSP page. At runtime, the JSP page creates for a given custom tag a new instance of the tag handler class, and calls the callback methods. This might sound complicated at first, but it becomes fairly straightforward once you?ve built a couple of tags for yourself.

For convenience, the JSP specification also provides a basic implementation of this interface, called TagSupport, which is an ideal starting point from which to build your own tags. The following code snippet shows the start of the source code for the tag handler, including all the necessary imports. It also shows a couple of attributes -- we?ll see where these are used later on.

package tagext;

import java.util.Collection;
import java.util.Iterator;

import javax.servlet.jsp.JspException;
import javax.servlet.jsp.PageContext;
import javax.servlet.jsp.tagext.TagSupport;

import rss.RssFeed;
import rss.RssReader;

public class RssFeedTag extends TagSupport {

 private String url;
 private Iterator iterator;

In the tag usage example I presented earlier, we saw that there was a starting tag, some body content, and the ending tag. These different aspects of the tag are important because they define when the JSP page will fire the callback methods that we write in our tag handler class. The functionality we need to implement is identical to that shown before; we need to read in an RSS feed from a URL, then iterate over each item in the feed so that a hyperlink can be generated. With the TagSupport class, the three callback methods that are available to us are doStartTag(), doAfterBody() and doEndTag(). Let?s look at each of these in turn.

The doStartTag() method is called when the starting tag is encountered on the JSP page, and is called only once for any given custom tag.

 public int doStartTag() throws JspException {
   RssReader reader = new RssReader();
   RssFeed feed = reader.read(url);
   iterator = feed.getItems().iterator();

   if (iterator.hasNext()) {
     pageContext.setAttribute("rssItem", iterator.next());
     return EVAL_BODY_INCLUDE;
   } else {
     return SKIP_BODY;
   }
 }

Since this code is only called once per tag, and is the first of the callback methods to be fired, it?s here that we can read the RSS feed and set up an iterator to loop over the collection of items. If you think of this method as the start of the while loop, the first step is to check that there are items in the collection. If there are, we want to make the first item available for use in the JSP page, so that we can utilise it within the body content of the tag. To do this, we set an attribute on the JSP PageContext to refer to the first item in the collection. Next, we must tell the JSP page that the body content of the tag should be evaluated, which is achieved by returning a constant value of EVAL_BODY_INCLUDE. If, however, there aren?t any items in the collection, we tell the JSP page that it should skip evaluating the body content by returning the constant value of SKIP_BODY.

The next callback method of interest is the doAfterBody() method, which is called after the body content of the tag has been evaluated.

 public int doAfterBody() throws JspException {
   if (iterator.hasNext()) {
     pageContext.setAttribute("rssItem", iterator.next());
     return EVAL_BODY_AGAIN;
   } else {
     return SKIP_BODY;
   }
 }

Once the body content is evaluated, the next step is to see whether there are any more items in the collection. If there are, we want to make the new item available to the JSP page and indicate that the body content should be re-evaluated, by returning a constant value of EVAL_BODY_AGAIN. After this, the doAfterBody() method is called again, to see if yet another evaluation is required. This sequence repeats until there are no more items in the collection, in which case a constant value of SKIP_BODY is returned.

When all the evaluations have been performed, the final callback method is executed.

 public int doEndTag() throws JspException {
   return EVAL_PAGE;
 }

This implementation simply tells the JSP page that the remainder of the page should be processed as normal. In fact, the implementation of the TagSupport class contains the same implementation of this method, meaning we don?t actually need to implement it. However, I?ve shown it here for completeness.

The final method we need to implement is a setter for the URL. If you look back to the example of how the tag will be used on the page, you?ll notice that the URL of the RSS feed is specified as an attribute of the custom tag. To make this information available to the tag handler class, we need to write a setter method in the same way we?d write setter methods for JavaBean properties. Any setter methods that correspond to attributes of a custom tag are called before the callback methods, so that their values are available for use within those callback methods.

 public void setUrl(String url) {
   this.url = url;
 }

}

Compiling the Tag Handler Class

To compile the tag handler class, make sure you have the Servlet and JSP classes in your classpath. If you?re using Tomcat 4, these can be found in the $TOMCAT_HOME/common/lib/servlet.jar file. The resulting class file should be placed under the WEB-INF/classes directory of your Web application, in the appropriate directory/package structure.

Describing the Tag

The next step is to describe the custom tag using an XML file called a tag library descriptor, or TLD file. This step is necessary because it allows us to define how the custom tag will be used on the page, the name of its attributes, and so on. Starting at the top, we have all the usual XML header information:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE taglib
 PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN"
 "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">

Next, we have the start of the tag library definition. Although custom tags are reusable, they must be defined within the context of a tag library -- a collection of one or more tags that are typically related in some way. This block of XML allows us to define the version of our tag library, the required version of JSP, a short name, and a description of the tag library.

<taglib>

 <tlib-version>1.0</tlib-version>
 <jsp-version>1.2</jsp-version>
 <short-name>rss</short-name>
 <description>
   Tags used to present RSS information.
 </description>

Following this is the definition of the tags in the tag library. Here we have only one, which defines the name of the tag as it will be used on a JSP page, the name of the tag handler class, the body content type and, again, a short description.

 <tag>
   <name>rssFeed</name>
   <tag-class>tagext.RssFeedTag</tag-class>
   <body-content>JSP</body-content>
   <description>
     A tag to present a headlines/titles of items from an RSS feed.
   </description>

Of these, the body content probably needs some more explanation. The JSP specification provides several body content types that can be defined for custom tags, with the two most useful being empty and JSP. A body content type of empty indicates that the custom tag will be used without body content on the page, which is handy when you simply want the tag to perform some sort of action. On the other hand, a body content type of JSP indicates that there will be regular JSP constructs used between the start and end tags. This is what we?re using in this example, because we?d like the body content to be evaluated for each item in the RSS feed.

The next part of the XML file describes the scripting variable that will be introduced into the page within the body content of the tag. In the tag handler code, we get the next RSS item from the collection, then place the reference to that object in the page context under the name rssItem. One of the things custom tags can do is make these attributes available as scripting variables on the JSP page, so they can be accessed with the request-time expression syntax of <%= ? %>. Here, we specify the name and type of the variable, along with a scope of NESTED to indicate that the variable should only be accessible between the starting and ending tags.

   <variable>
     <name-given>rssItem</name-given>
     <variable-class>rss.RssItem</variable-class>
     <scope>NESTED</scope>
   </variable>

The final aspect of the tag to describe is its attributes. In this example there is only a single attribute, called url, which is used to indicate the source of the RSS feed. To ensure that the tag works as expected, we've stated that this attribute must be supplied when the tag is used. The rtexprvalue element of the attribute tag says that the value of the attribute must be statically defined in the JSP page. In other words, the value of the attribute isn't the result of a request-time expression.

   <attribute>
     <name>url</name>
     <required>true</required>
     <rtexprvalue>false</rtexprvalue>
   </attribute>
 </tag>

</taglib>

Using the Tag

For the purposes of this example, let's assume that the TLD file has been saved as rss.tld under the WEB-INF directory of your Web application. To use a custom tag, you first need to tell the JSP page where to find the description of that tag. This is achieved through the taglib directive, with the uri attribute pointing to the TLD file that represents the tag library, and the prefix attribute stating how the tags in that tag library will be identified and used on the page. Then, using the same syntax as before, we can use the tag to read the RSS feed provided by any Website, and generate a set of hyperlinks to the current news stories on that site.

<%@ taglib uri="/WEB-INF/rss.tld" prefix="rss" %>

<rss:rssItems url="http://www.sitepoint.com/rss.php">
 <a href="<%= rssItem.getLink() %>"><%= rssItem.getTitle() %></a>
 <br />
</rss:rssItems>

Future Enhancements

The tag presented here is fairly simple in its implementation, and there are many enhancements that could be made. For example, every time the JSP page is requested, the tag opens up an HTTP connection to retrieve the contents of the RSS feed. While this is okay for a low traffic site, a better solution would be to cache the feed on a regular basis. This would avoid the performance penalty associated with opening a network connection for every page request.

Also, the tag doesn't take into account what happens if a network error occurs. For example, the Website might be down or may not be functioning correctly. In any case, you would probably want to add some error handling, perhaps to display a message to alert users that the feed isn't currently available.

Summary

In this article we've looked at what RSS is, how to read RSS feeds, and how to integrate this functionality into a JSP-based Web application. Although we could have built this functionality directly into the JSP page using Java code scriptlets, developing a JSP custom tag has allowed us to build a more maintainable component with the added advantage that it?s reusable, too.

Building the tag handler class and writing the TLD file does involve slightly more work than would embedding Java code into the page. However, I believe that the benefits in maintainability and reusability easily justify the additional effort involved.

Discuss this article in The Big Moose Saloon!


Return to Top

Following are the scheduled book promotions remaining in March and early April:

Starting Date	Book	Author(s)	Publisher	JavaRanch Forum
March 9	JavaServer Pages, Third Edition	Hans Bergsten	O'Reilly	JSP
March 16	Tapestry in Action	Howard M. Lewis Ship	Manning	Other Java Products and Servers
March 23	.NET & J2EE Interoperability	Dwight Peltzer	McGraw-Hill Osborne Media	Java in General (advanced)
March 30	Professional Jakarta Struts	James Goodwill and Richard Hightower	Wrox	Struts and Other Frameworks
April 6	Whizlabs SCBCD Exam Simulator	Val and Seema R	Whizlabs	EJB Certification (SCBCD)
April 13	Struts Survival Guide	Srikanth Shenoy and Nithin Mallya	ObjectSource Publications	Struts and Other Frameworks

Return to Top