Newsletter sign-up
View all newsletters

Enterprise Java Newsletter
Stay up to date on the latest tutorials and Java community news posted on JavaWorld

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

JavaWorld.com > Java Standard Edition >

Encapsulate reusable functionality in JSP tags

Build your own custom JSP tag with Tomcat

By Simon Brown, JavaWorld.com, 08/11/00

  • Print
  • Feedback
Like HTML, JavaServer Pages (JSP) use the concept of tags as their building blocks. A handful of tags are available to you as a JSP developer, allowing you to embed Java code, include other documents, and even make use of JavaBeans components. Although those tags are all you need to build Websites with dynamic content, you will probably find yourself duplicating small bits of functionality into your JSP pages after a while. If that is the case, tag libraries may be the answer.

What are tag libraries?

Tag libraries, or taglibs, are a feature of JSP 1.1 that enables you to build libraries of reusable JSP tags. That means you can encapsulate common behavior in your own JSP tag and use it across the JSP pages in your Web apps. The ability to extract common functionality from a JSP page and easily reuse it in other pages and Web applications can be very powerful. But isn't that what JavaBeans were designed for?

JavaBeans are reusable software components. It's true that there are JSP tags that let you use JavaBeans within your pages. The only ability those tags allow you, however, is to bind named, scoped instances, and then get/set those instances' properties. If you need to call methods on your JavaBeans, you need to embed the appropriate Java code inside a scriptlet.

Tags or JavaBeans?

I've established that you can use JavaBeans or JSP tags to encapsulate common functionality. That in essence labels both JavaBeans and tags as reusable software components and raises the question of when one is more appropriate to use over the other. While no hard and fast rules explain that, a couple of factors can be taken into account.

Server-side JavaBeans are nonvisual components, and I generally use them for maintaining session state and business information. A good example would be using a bean to maintain the user's current state in a Web-based mail application.

Tags on the other hand can represent actions on a page, and I tend to use those to hide common functionality that generates dynamic HTML or controls the page in some way.

One of the key differences between JavaBeans and JSP tags is that tags are much more aware of the environment in which they are running. That includes the page context (containing the request, response, and so on) and the servlet context of the Web application in which the tag is running. JSP tags can use those contexts to access the HTTP session information and to also make use of JavaBeans that contain session and/or business state.

An example tag

That's enough about what tags are and how you can use them. The next questions I'll address are what they look like and how to write them. First, I'll present an example, showing how to write a simple JSP tag; then I'll show you how to deploy and use it in your JSP pages.

To keep things simple, I'll use the current reference implementation of the Servlet/JSP specification -- Tomcat from the Apache Group. Tomcat supports the new J2EE Web applications and, to save creating your own, you can use Tomcat's example Web application. That can be found under your Tomcat installation directory (TOMCAT_HOME) in webapps/examples. Further information about Tomcat, including details on where you can download it, can be found in the Resources section.

Displaying a file size

To set the scene, imagine that your Web application lets the user download a file via a hyperlink. Your JSP page could get the filename (or URI) from a JavaBean and generate the hyperlink dynamically. Let's say you realize that some of those files may be very large, and you'd like to display the file size so that the user can make an informed decision as to whether he or she wishes to download the file.

Obviously, a few options are open to you, one being to use the JavaBean to store the file size. Of course that isn't a good option if the contents of the file change frequently. Instead, you would use a custom tag that, given a file's URI, uses its environment to find out how large the file is.

Design and describe the tag

First, you'll need to describe your tag, giving it a name and specifying any attributes it may have. You do that by creating a tag library descriptor (.tld) file -- an XML file that describes your tag library.

For the purpose of that example, I'll create a file called taglib.tld and place it under the web-inf directory. The contents of the file as are follows. 

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN"
                           "http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd">
<taglib>
    <tlibversion>1.0</tlibversion>
    <jspversion>1.1</jspversion>
    <shortname>examples</shortname>
    <uri>http://www.mycompany.com/taglib</uri>
    <info>An example tag library</info>
    <tag>
        <name>size</name>
        <tagclass>examples.SizeTag</tagclass>
        <info>Works out how large a file, pointed to by a URI, is in bytes</info>
        <attribute> 
            <name>uri</name>
            <required>true</required>
            <rtexprvalue>false</rtexprvalue>
        </attribute>
    </tag>
</taglib>


I'll skim over the top of the file and concentrate on the tag library that I am defining. A tag library has a short name, a brief description, and a URI. That doesn't need to be a real URI as it's just an identifier for the library. A tag library can have one or more tags, each tag having a name, some brief commentary about its purpose, and a fully qualified class name. That class name is the name of the Java class that contains the functionality provided by your custom tag. I'll write that class shortly.

My tag has one mandatory (required) attribute called uri, allowing me to specify the URI of the file whose size I want. When using custom tags on a JSP page, you can provide a Java scriptlet as the value of an attribute. The value between the <rtexprvalue> tags indicates that such may be the case and that the JSP engine should evaluate the runtime expression beforehand. For this simple example, I'll just pass a hard-coded URI, so I've set that to false for now.

Build the tag

Once you have described your tag and its attributes, you need to write the class that will provide the functionality. All JSP tags are required to implement the javax.servlet.jsp.tagext.Tag interface. When a tag is used on a page, the JSP engine instantiates the class and begins by calling the various life cycle methods that the interface defines. That includes telling the tag about its environment by referring to a PageContext object.

The following code shows the SizeTag class. There are two places where supporting classes can go but, for the purpose of this example, I'll place the tag under the web-inf/classes directory. There should already be an examples package in which I can place the tag.

  • Print
  • Feedback

Resources