Custom JSP tags speed Web development

Learn how to build and use custom JSP tag libraries in WDSC for iSeries V5.1.

This tip focuses on how you can build and use custom JSP tag libraries in IBM's WebSphere Development Studio Client...

for iSeries (v5.1) (WDSC). Web application servers such as IBM's WebSphere and Apache Tomcat provide runtime environments for Java servlets and JSPs that use JSP tag libraries.

Basic Java Web application model
Sun Microsystems' JSR 52 defines the Java Servlet version 2.3 and Java Server Page version 1.2 specification defining Java Web applications. The specification is part of Sun's J2EE specification (Java 2 Enterprise Edition) defining enterprise server application support. The specifications are important because they provide open standards that all Java Web application servers implement (WebSphere, Tomcat, WebLogic, JBoss, etc.) making Java Web applications portable across many server platforms.

Custom JSP tags
Custom tags are user-defined JSP tags that add well-defined sets of application behavior in a clean, structured manner to JSPs much like custom CL commands add rich, flexible program behavior to CL programs. When a JSP is translated to a servlet by the JSP compiler, the tag is replaced by a set of Java operations on the tag handler object. This is similar conceptually to how macros work.

Custom JSP tags were first defined in Sun's JSP specification 1.1. Older versions of Web application servers, such as WebSphere 3.02, don't support custom tag libraries. The current JSP specification level is 1.2. The Jakarta Tomcat server version 4.x from Apache supports JSP 1.2. WebSphere version 3.5x and WebSphere 4.x support JSP 1.1.

Like the format of HTML tags, custom JSP tags have elements and attributes that customize a tag's behavior. They can be combined in many ways, including nesting (something CL commands can't do). They also have full access to all the objects in the servlet context.

JSP tags are packaged in tag libraries as a jar file. A Tag Library Descriptor (TLD) file defines all the JSP tags in a given library, along with the parameters each tag supports and where the tag library file is located. The TLD file format has a standard header layout that includes information on the tag library: version, JSP version, short name, URI to uniquely identify the tag library in the application context and a description. In addition, the file will contain one or more tag definitions and listener definitions.

A Web application using the tag library usually stores the tag library in the WEB-INF directory along with the TLD file. Any JSPs using the tag library declare a tag library directive referencing the tag library. Web developers then can use specific JSP tags from the library in the JSP wherever needed.

Custom JSP tag type processing
The tag handler class is responsible for interacting with server side objects in the application (e.g., your existing shopping cart bean) and the JSP page. Tags optionally have attributes that are passed in as name value pairs (name="Jim") to customize the behavior of the tag handler. 

Some tags have "body content" elements that are items declared as part of the page within the tag start and end. This is referred to as the body content of a tag. When processing a tag with body content, the body will usually be either evaluated (for an iteration or condition) or updated (for output on the page).

The release method releases any allocated resources in the tag handler object. The doStart and doEnd tags are invoked when a custom tag is encountered in the page. Return values tell the Web container how to process the JSP page.
  • Return options for doStart: Include the current body content, but don't process it; process the current body content or do not evaluate the body of the JSP page
  • Return options for doEnd: Evaluate the rest of the JSP page, skip the rest of the JSP page
A tag handler implements one of the two basic tag handler interfaces: Tag and BodyTag.

for simple tag handlers that are invoked but don't directly manipulate the JSP body content
(e.g., prints out "Hello World", a formatted date string etc which is added to the JSP page

for more complex handlers that update the JSP body content of the page directly
(e.g., creating new body content on a JSP page such as an order line item table)

Subclasses of BodyTagSupport class can manipulate the body content of the JSP page using the following:
doInitBody - before the body of the tag is evaluated
doAfterBody - after the body of the tag is evaluated

Different tags can share and access the same objects that are stored in the application context. For example, one tag may create a new order and another may ship the order on two JSPs. A tag handler can access the JSP through the PageContext retrieved from the application, request or response objects.

Tags execute in sequence during page processing by the servlet engine. Attributes are passed in. The doStart, doEnd methods are called. If the tag is a subclass of BodyTagSupport, the doInitBody and doAfterBody methods can also be called to provide output to the page content directly.

A Listener is a class that is instantiated and registered with the container to handle specific servlet life cycle events. When an event occurs, the container invokes the registered method to handle the event.

Web development cost, time, risks reduced
WebSphere originally offered built-in proprietary tags for database access. Today the open standard for custom tag libraries has replaced proprietary tags in most Web application servers. Libraries of JSP tags are available from many sources now, including both billable libraries such as IBM, BEA and others and non-billable libraries such as Apache, SourceForge and other organizations. (See references below for more.)

In addition, Java developers can create custom tag libraries for their own business logic, making it easily accessible to Web developers in a reusable form. Packaging Java beans as custom tag libraries in Web applications offers many advantages:

  • It promotes reuse of Java beans for customizable business logic, common functions.
  • The same beans can be reused in multiple user interfaces: Web applications, PDAs, Java applications.
  • Web developers don't have to learn Java to build dynamic Web applications for data and transactions.
  • WDSC Page Designer allows developers to visually use custom JSP tags in JSPs without coding low-level JSP and HTML tags.

Having built JSP applications under JSP 1.0 without custom tag libraries, these tag libraries greatly reduce the cost, time and risks in developing powerful Web applications.

Apache Jakarta Taglibs Project

The Taglibs project is providing a wide variety of standard, open-source JSP tag libraries, including Bean Scripting Framework (BSF) for integrating scripting languages and Java beans, DB Tags integrating database access dynamically, XSL tags for transforming XML documents, IO tags for HTTP, FTP, XRPC and SOAP requests and more.

Jakarta Struts Project

The Struts tag library provides a framework for building internationalized Web applications that implement the Model-View-Controller design pattern. Struts includes a comprehensive set of utility custom tags for handling the following:
  • HTML forms
  • Templates
  • JavaBeans components
  • Logic processing

You can also create your own custom tag libraries as needed to encapsulate reusable business logic in Web applications, for example.

Steps for building and using custom tags in WDSC
  1. Create a tag library of one or more Tag Handler Classes
  2. Create a Tag Library Descriptor file (.tld)
  3. Package the tag library
  4. Copy the tag library to an application's WEB-INF folder
  5. Copy the Tag Library Descriptor to the WEB-INF folder
  6. Add a page directive declaring the Tag library in a JSP
  7. Add JSP tags as needed to the JSP
  8. Testing the Application with the custom JSP tag

If you are using a tag library created by someone else (the Jakarta Taglibs or Struts projects), begin with Step 4.

Using custom tags in WDSC
You work primarily in the Web perspective building a Web application when you use custom JSP tag libraries. Normally I work in the Java perspective when I'm building a tag library. WDSC's dynamic project configuration makes it easy to configure and use tag libraries and other resources during development and testing.

For more detailed information on each specific step, refer to the online help in WDSC. The steps below are a simple example I did to build and use a very limited custom tag. The example tag handler class (DatePrint) prints only a date string within a JSP.

After creating a new Web project in WDSC, I generated the original JSP application I used the tag for using the WDSC Web database application wizard to search, select and view data from DB2. With a limited investment in learning WDSC first, you should be able to generate your own Web database application with the wizard and then follow the process below to create a custom tag and add it to a JSP you created.

1. Create a tag library of one or more Tag Handler Classes
In the Java perspective, I used the New Class wizard and the Java editor to create the following class:

package com.ebt.test.tag1;

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

/* DatePrint
 a sample JSP custom Tag Handler
 This class extends TagSupport to allow writing out in context on a JSP.
 The simple example below only executes doStartTag to write to the 
 page context output device to display a date string
 more complex examples would extend BodyTagSupport instead  2002, all rights reserved

public class DatePrint extends TagSupport {

  * Constructor for DatePrint
 public DatePrint() {

  * @see Tag#doStartTag()
 public int doStartTag() throws JspException {
    try {
      pageContext.getOut().print(getClass().getName() + "tDate: " 
      + new java.util.Date());
    } catch (Exception ex) {
      throw new JspException("failed to write to JSP Page Context tt" + ex);
    return SKIP_BODY;

The source file is stored in the source folder for your Web project and the class is stored under Webapplication/WEB-INF/classes.

2. Create a Tag Library Descriptor file (.tld)
Using the New File wizard I created a text file (et_date1.tld) with the following content for my custom tag definition:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE taglib
 PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN"

<!-- et_date1.tld - test simple tld for a Date handler class -->
<!-- a tag library descriptor -->

 <!-- after this the default space is

 <!-- The version number of this tag library -->

 <!-- The JSP specification version required to function -->

 <!-- The short name of this tag library -->

 <!-- Public URI that uniquely identifies this version of the tag library -->

 <!-- General information about this tag library -->
    A simple tag library for a Date Handler

 <!-- ******************** Defined Custom Tags *************************** -->

 <!-- A simple Tag -->
 <!-- DatePrint tag -->
 Print "DatePrint ran "

The et_date1.tld file should be stored in the Webapplication/WEB-INF directory.

3. Package the tag library
I skipped this step because I was only testing a single tag in the current application. To package a tag library simply go to File > Export on the WDSC menu and create a jar file using the jar wizard.

4. Copy the tag library to an application's WEB-INF folder
I skipped this step because I was using the tag in the same application I created it. Normally you would copy the tag library jar file to the Webapplication/WEB-INF/lib directory of the Web project you want to use it in.

5. Copy the Tag Library Descriptor to the WEB-INF folder
I skipped this step because I was using the tag in the same application I created it. Normally you would copy the tag library descriptor file (TLD) (here et_date1.tld) to the Webapplication/WEB-INF directory of the Web project you want to use it in.

6. Add a page directive declaring the Tag library in a JSP
Opening a generated JSP in my database Web application (here ctw2bempMasterView.jsp) with Page Designer, I added a directive to map the JSP page to the specific tag library descriptor file (et_date1.tld). Page Designer made it easy to find the tag library descriptor file to generate the taglib directive from.

From the Designer menu on the open JSP page in DESIGN view select in sequence:

• Page > Page Properties > JSP Tags to open the JSP tag property page
• Select tag type as JSP directive – taglib > Add
    For the URI, browse to find the TLD file (et_date1.tld) in your project (change the file type to all first)
    the TLD file is in the WEB-INF directory
• For the tag prefix, enter "et1", Click OK twice to close the wizard

In context the, directive is below:
<META name="GENERATOR" content="IBM WebSphere Studio">
<%@taglib uri="WEB-INF/et_date1.tld" prefix="et1"%>
7. Add JSP tags as needed to the JSP
Next I added a custom JSP tag to the JSP page to display the date. Page Designer made it easy to add the tag to the page:

From the Designer menu on the open JSP page in DESIGN view select in sequence:
  • I clicked on a point I wanted to add the JSP tag for DatePrint first
  • On the Designer menu: JSP > Insert Custom (The insert custom tag wizard opens.)
  • I selected my tag library and the DatePrint tag, then closed the wizard. (The tag was added to the page.)
  • Pressed CTL-S to save the updated JSP page

In context the, tag is below:
8. Testing the Application with the custom JSP tag
Testing Web applications is easy in WDSC. I just selected the HTML input page that starts the application (here ctw2bempInputForm.html), hit the right button pop up menu and selected "Run on Server". WDSC automatically configured and started my WebSphere test environment and ran the application.

Summary on custom Tag libraries

Custom tag libraries are a core foundation for building scalable Web applications. Custom tags make it easy to separate Java business logic from Web development cleanly, allow Java beans to be reused across multiple client interfaces, automate and improve Web development productivity especially in tools like WDSC. They also provide a foundation for other frameworks such as Jakarta Struts (an MVC2 implementation of Web applications).

More information:

About the authors: Jim Mason is president of, and he writes, consults, teaches, designs and develops iSeries Web applications using Java, WebSphere, DB2, Lotus Domino and the WebSphere Development Tools for iSeries. David Slater is World Wide Market Manager ofiSeries Application Development at IBM Canada.

This was last published in September 2002

Dig Deeper on Web Tools

Start the conversation

Send me notifications when other members comment.

By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy

Please create a username to comment.