kapok

JavaServer Pages (JSP) technology makes it easy to embed bits of Java code (or scriptlets) in HTML documents. This solution, however, may not be suitable for all HTML content developers, perhaps because they do not know Java and they do not care to learn its syntax. While JavaBeans can be used to encapsulate much of the Java code, using them in JSP pages still requires content developers to have some knowledge of Java syntax.

JSP technology allows you to introduce new custom tags through the tag library facility. As a Java developer, you can extend JSP pages by introducing custom tags that can be deployed and used in an HTML-like syntax. Custom tags also allow you to provide better packaging by improving the separation between business logic and presentation logic.

This article presents a brief overview of custom tags, then it shows:

• How to develop and deploy simple tags
• How to develop and deploy advanced tags: parameterized tags and tags with a body
• How to describe tags with the Tag Library Descriptor (TLD)

Finally, some programming guidelines are also provided.

Overview of Tags

If you have experience with HTML, you already know about the types of tags that can be used. Basically there are two types of tags, and both can have attributes (information about how the tag should do its job):

• Bodyless Tags: A bodyless tag is a tag that has a start tag but does not have a matching end tag. It has the syntax:

  <tagName attributeName="value" 
  anotherAttributeName="anotherValue"/>
  

  Bodyless tags are used to represent certain functions, such as presenting an input field, or displaying an image. Here is an example of a bodyless tag in HTML:

  <IMG SRC="/developer/technicalArticles/xml/WebAppDev3/fig10.gif">

• Tags with a Body: A tag with a body has a start tag and a matching end tag. It has the syntax:

  <tagName attributeName="value" anotherAttributeName="anotherValue"> ...tag body... </tagName>

  
  

  Tags with a body are used to perform operations on the body content, such as formatting. Here is an example of a tag with a body in HTML:

  <H2>Custom Tags</H2>

JSP Custom Tags

JSP custom tags are merely Java classes that implement special interfaces. Once they are developed and deployed, their actions can be called from your HTML using XML syntax. They have a start tag and an end tag. They may or may not have a body. A bodyless tag can be expressed as:

<tagLibrary:tagName />

And, a tag with a body can be expressed as:

<tagLibrary:tagName>
   body
</tagLibrary:tagName>

Again, both types may have attributes that serve to customize the behavior of a tag. The following tag has an attribute called name, which accepts a String value obtained by evaluating the variable yourName:

<mylib:hello name="<%= yourName %>" />

Or, it can be written as a tag with a body as:

<mylib:hello>
  <%= yourName %>
</mylib:hello>

Note: Any data that is a simple string, or can be generated by evaluating a simple expression, should be passed as an attribute and not as body content.

Benefits of Custom Tags

A very important thing to note about JSP custom tags is that they do not offer more functionality than scriptlets, they simply provide better packaging, by helping you improve the separation of business logic and presentation logic. Some of the benefits of custom tags are:

• They can reduce or eliminate scriptlets in your JSP applications. Any necessary parameters to the tag can be passed as attributes or body content, and therefore no Java code is needed to initialize or set component properties.
• They have simpler syntax. Scriptlets are written in Java, but custom tags can be used in an HTML-like syntax.
• They can improve the productivity of nonprogrammer content developers, by allowing them to perform tasks that cannot be done with HTML.
• They are reusable. They save development and testing time. Scritplets are not reusable, unless you call cut-and-paste reuse.

In short, you can use custom tags to accomplish complex tasks the same way you use HTML to create a presentation.

Defining a Tag

A tag is a Java class that implements a specialized interface. It is used to encapsulate the functionality from a JSP page. As we mentioned earlier, a tag can be bodyless or with a body. To define a simple bodyless tag, your class must implement the Tag interface. Developing tags with a body is discussed later. Sample 1 shows the source code for the Tag interface that you must implement:

Sample 1: Tag.java

public interface Tag {
   public final static int SKIP_BODY = 0;
   public final static int EVAL_BODY_INCLUDE = 1;
   public final static int SKIP_PAGE = 5;
   public final static int EVAL_PAGE = 6;

   void setPageContext(PageContext pageContext);
   void setParent(Tag parent);
   Tag getParent();
   int doStartTag() throws JspException;
   int doEndTag() throws JspException;
   void release();
}

All tags must implement the Tag interface (or one of its subinterfaces) as it defines all the methods the JSP runtime engine calls to execute a tag. Table 1 provides a description of the methods in the Tag interface.

My First Tag

Now, let's look at a sample tag that when invoked prints a message to the client.

There are a few steps involved in developing a custom tag. These steps can be summarized as follows:

1. Develop the tag handler
2. Create a tag library descriptor
3. Test the tag

1. Develop the Tag Handler

A tag handler is an object invoked by the JSP runtime to evaluate a custom tag during the execution of a JSP page that references the tag. The methods of the tag handler are called by the implementation class at various points during the evaluation of the tag. Every tag handler must implement a specialized interface. In this example, the simple tag implements the Tag interface as shown in Sample 2.

Sample 2: HelloTag.java

package tags;

import java.io.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public class HelloTag implements Tag {
   private PageContext pageContext;
   private Tag parent;

   public HelloTag() {
      super();
   }

   public int doStartTag() throws JspException {
      try {
         pageContext.getOut().print(
         "This is my first tag!");
      } catch (IOException ioe) {
         throw new JspException("Error: 
         IOException while writing to client" 
         + ioe.getMessage());
      }
      return SKIP_BODY;
   }

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

   public void release() {
   }

   public void setPageContext(PageContext 
   pageContext) {
      this.pageContext = pageContext;
   }

   public void setParent(Tag parent) {
      this.parent = parent;
   }

   public Tag getParent() {
      return parent;
   }
}

The two important methods to note in HelloTag are doStartTag and doEndTag. The doStartTag method is invoked when the start tag is encountered. In this example, this method returns SKIP_BODY because a simple tag has no body. The doEndTag method is invoked when the end tag is encountered. In this example, this method returns SKIP_PAGE because we do not want to evaluate the rest of the page; otherwise it should return EVAL_PAGE.

To compile the HelloTag class, assuming that Tomcat is installed at: c:\tomcat:

• Create a new subdirectory called tags, which is the name of the package containing the HelloTag class. This should be created at: c:\tomcat\webapps\examples\web-inf\classes.
• Save HelloTag.java in the tags subdirectory.
• Compile with the command:

  c:\tomcat\webapps\examples\web-inf\classes\tags> 
  javac -classpath c:\tomcat\lib\servlet.jar 
  HelloTag.java
  

2. Create a Tag Library Descriptor

The next step is to specify how the tag will be used by the JSP runtime that executes it. This can be done by creating a Tag Library Descriptor (TLD), which is an XML document. Sample 3 shows a sample TLD:

Sample 3: mytaglib.tld

<?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">

<!-- a tag library descriptor -->

<taglib>
   <tlibversion>1.0</tlibversion>
   <jspversion>1.1</jspversion>
   <shortname>first</shortname>
   <uri></uri>
   <info>A simple tab library for the 
   examples</info>

  <tag>
    <name>hello</name>
    <tagclass>tags.HelloTag</tagclass>
    <bodycontent>empty</bodycontent>
    <info>Say Hi</info>
  </tag>         
</taglib>

First we specify the tag library version and JSP version. The <shortname> tag specifies how we are going to reference the tag library from the JSP page. The <uri> tag can be used as a unique identifier for your tag library.

In this TLD, we only have one tag named hello whose class is specified using the <tagclass> tag. However, a tag library can have as many tags as you like. The <bodycontent> tells us that this tag will not have a body; otherwise an error will be produced. On the other hand, if you like to evaluate the body of the tag, that value would be:

• tagdependent: meaning that any body of the tag would be handled by the tag itself, and it can be empty.
• JSP: meaning that the JSP container should evaluate any body of the tag, but it can also be empty.

Save mytaglib.tld in the directory: c:\tomcat\webapps\examples\web-inf\jsp.

3. Test the Tag

The final step is to test the tag we have developed. In order to use the tag, we have to reference it, and this can be done in three ways:

1. Reference the tag library descriptor of an unpacked tag library. For example:

   <@ taglib uri="/WEB-INF/jsp/mytaglib.tld" 
   prefix="first" %>
   

2. Reference a JAR file containing a tag library. For example:

   <@ taglib uri="/WEB-INF/myJARfile.jar" 
   prefix='first" %>
   

3. Define a reference to the tag library descriptor from the web-application descriptor (web.xml) and define a short name to reference the tag library from the JSP. To do this, open the file: c:\tomcat\webapps\examples\web-inf\web.xml and add the following lines before the end line, which is <web-app>:

   <taglib> <taglib-uri>mytags</taglib-uri> <taglib-location>/WEB-INF/jsp/ mytaglib.tld</taglib-location> </taglib>

   
   

Now, write a JSP and use the first syntax. Sample 4 shows an example:

Sample 4: Hello.jsp

<%@ taglib uri="/WEB-INF/jsp/mytaglib.tld"
 prefix="first" %>
<HTML>
<HEAD>
<TITLE>Hello Tag</TITLE>
</HEAD>

<BODY bgcolor="#ffffcc">

<B>My first tag prints</B>:

<first:hello/>

</BODY>
</HTML>

The taglib is used to tell the JSP runtime where to find the descriptor for our tag library, and the prefix specifies how we will refer to tags in this library. With this in place, the JSP runtime will recognize any usage of our tag throughout the JSP, as long as we precede our tag name with the prefix first as in <first:hello/>.

Alternatively, you can use the second reference option by creating a JAR file. Or, you can use the third reference option simply by replacing the first line in Sample 4 with the following line:

<%@ taglib uri="mytags" prefix="first" %>

Basically, we have used the mytags name, which was added to web.xml, to reference the tag library. For the rest of the examples in this article, this reference will be used.

Now, if you request Hello.jsp from a browser, you would see something similar to Figure 1.

Figure 1: First Custom Tag

The custom tag developed in Sample 4 is a simple tag, the goal of it was just to give you a flavor of the effort involved in developing custom tags. You may have noticed that even this simple tag required us to implement a number of methods, some of which have very simple implementations. To minimize the effort involved, the JSP designers provided a template to be used for implementing simple tags. The template is the TagSupport abstract class. It is a convenience class that provides default implementations for all the methods in the Tag interface.

Therefore, an easier way to write simple tags is to extend the TagSupport class rather than implementing the Tag interface. You can think of the TagSupport abstract class as an adapter. Having said that, the HelloTag class in Sample 4 can be easily written as shown in Sample 5.

Sample 5: Extending the TagSupport class

package tags;

import java.io.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public class HelloTag extends TagSupport {

   public int doStartTag() throws JspException {
      try {
         pageContext.getOut().print("This is my 
         first tag!");
      } catch (IOException ioe) {
         throw new JspException("Error: 
         IOException while writing 
        to client" + ioe.getMessage());
      }
      return SKIP_BODY;
   }

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

Parameterized Tags

We have seen how to develop simple tags. Now, let's see how to develop parameterized tags--tags that have attributes. There are two new things that that need to be added to the previous example to handle attributes:

1. Add a set method
2. Add a new tag to mytagslib.tld

Adding a set method and changing the output message results in Sample 5.

Sample 5: A tag with an attribute

package tags;

import java.io.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public class HelloTagParam extends TagSupport {
   private String name;

   
   public void setName(String name) {
      this.name = name;
   }
   

   public int doStartTag() throws JspException {
      try {
         pageContext.getOut().print("Welcome to 
         JSP Tag Programming, " +name);
      } catch (IOException ioe) {
         throw new JspException("Error: 
         IOException 
         while writing to client");
      }
      return SKIP_BODY;
   }

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

The next thing we need to do is add a new tag to mytaglib.tld. The new tag is shown in Sample 6. This snippet of code should be added to mytaglib.tld right before the last line, </taglib>:

Sample 6: revising mytaglib.tld

<tag>
  <name>helloparam</name>
  <tagclass>tags.HelloTagParam</tagclass>
  <bodycontent>empty</bodycontent>
  <info>Tag with Parameter</info>
  <attribute>
     <name>name</name>
     <required>false</required>
     <rtexprvalue>false</rtexprvalue>
         </attribute>
</tag>

We have added a new tag named helloparam. Notice the new <attribute> tag, which specifies that the helloparam tag accepts an attribute whose name is name. The <required> tag is set to false, meaning that the attribute is optional; the <rtexprvalue> tag is set to false specifying that no run time evaluation will be done.

Nothing needs to be added to the web.xml web-application descriptor file since we are using the same tag library: mytaglib.tld.

Now, we can test the new tag. The source code in Sample 7 shows how to test it using a name attribute "JavaDuke".

Sample 7: HelloTagParam.jsp

<%@ taglib uri="mytags" prefix="first" %>
<HTML>
<HEAD>
<TITLE>Hello Tag with Parameter</TITLE>
</HEAD>

<BODY bgcolor="#ffffcc">
<B>My parameterized tag prints</B>:

<P>

<first:helloparam name="JavaDuke"/>

</BODY>
</HTML>

If you request HelloTagParam.jsp from a web browser, you would see an output similar to that in Figure 2.

Figure 2: Testing a parameterized tag

Tag Libraries

A tag library is a collection of JSP custom tags. The Jakarta Taglibs Project provides several useful tag libraries for XML parsing, transformations, email, databases, and other uses. They can be easily downloaded and used.

Here we develop our tag library. As an example, we develop a simple math library that provides two tags, one for adding two numbers, and the other for subtracting one number from another number. Each tag is represented by one class. The source code for the two classes, Add.java and Subtract.java, is shown in Sample 8.

Sample 8: Add.java and Subtract.java

package tags;

import java.io.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public class Add extends TagSupport {
   private int num1, num2;

   public void setNum1(int num1) {
      this.num1 = num1;
   }
   
   public void setNum2(int num2) {
      this.num2 = num2;
   }


   public int doStartTag() throws JspException {
      try {
         pageContext.getOut().print("Welcome
         to First
          Grade Math! ");
         pageContext.getOut().print("The sum of: " +
         num1 + " and " + num2 + " is: " + (
         num1+num2));
      } catch (IOException ioe) {
         throw new JspException("Error:
         IOException
          while writing to client");
      }
      return SKIP_BODY;
   }
}
      
// Subtract.java

package tags;

import java.io.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public class Subtract extends TagSupport {
   private int num1, num2;

   public void setNum1(int num1) {
      this.num1 = num1;
   }
   
   public void setNum2(int num2) {
      this.num2 = num2;
   }


   public int doStartTag() throws JspException {
      try {
         pageContext.getOut().print("Welcome to First
          Grade Math! ");
         pageContext.getOut().print("If you 
         subtract:
          " + num2 + " from " + num1 +
          ", you get: "+ (num1 - num2));
      } catch (IOException ioe) {
         throw new JspException("Error:
          IOException 
         while writing to client");
      }
      return SKIP_BODY;
   }
}

The source code is easy to understand. Notice one thing we have repeated in Add.java and Subract.java is the call to pageContext.getOut.print. A better way to do this would be to get a JspWriter object then then use it to print to the client:

JspWriter out = pageContext.getOut();
out.print("first line");
out.print("second line");

The next step is to revise the tag library descriptor file, mytaglib.tld, and add descriptions to the two new tags. Sample 9 shows the description for the new tags. Add the following snippet of XML to mytaglib.tld, right before the last line.

Sample 9: revising mytaglib.tld

  <tag>
    <name>add</name>
    <tagclass>tags.Add</tagclass>
    <bodycontent>empty</bodycontent>
    <info>Tag with Parameter</info>
    <attribute>
       <name>num1</name>
       <required>true</required>
       <rtexprvalue>false</rtexprvalue>
    </attribute>
    <attribute>
      <name>num2</name>
      <required>true</required>
      <rtexprvalue>false</rtexprvalue>
    </attribute>
  </tag>

  <tag>
    <name>sub</name>
    <tagclass>tags.Subtract</tagclass>
    <bodycontent>empty</bodycontent>
    <info>Tag with Parameter</info>
    <attribute>
       <name>num1</name>
       <required>true</required>
       <rtexprvalue>false</rtexprvalue>
    </attribute>
    <attribute>
      <name>num2</name>
      <required>true</required>
      <rtexprvalue>false</rtexprvalue>
    </attribute>
  </tag>

As you can see, each tag requires two attributes that must be named num1 and num2.

Now, we can test our math tag library using the test driver shown in Sample 10.

Sample 10: math.jsp

<%@ taglib uri="mytags" prefix="math" %>
<HTML>
<HEAD>
<TITLE>Hello Tag with Parameter</TITLE>
</HEAD>

<BODY bgcolor="#ffffcc">
<B>Calling first tag</B>
<P>
<math:add num1="1212" num2="121"/>
<P>
<B>Calling second tag</B>
<P>
<math:sub num1="2123" num2="3"/>

</BODY>
</HTML>

If you request math.jsp from a web browser, you would see an output that is similar to Figure 3.

Figure 3: Testing the math tag library

Tags with a Body

A tag handler for a tag with a body is implemented differently depending on whether the body needs to be evaluated once or multiple times.

• Single Evaluation: if the body needs to be evaluated once, the tag handler should implement the Tag interface, or extend the TagSupport abstract class; the doStartTag method needs to return EVAL_BODY_INCLUDE, and if it does not need to be evaluated at all then it should return BODY_SKIP.
• Multiple Evaluation: if the body needs to be evaluated multiple times, the BodyTag interface should be implemented. The BodyTag interface extends the Tag interface and defines additional methods (setBodyContent, doInitBody, and doAfterBody) that enable a tag handler to inspect and possibly change its body. Alternatively, and similarly to the TagSupport class, you can extend the BodyTagSupport class, which provides default implementations for the methods in the BodyTag interface. Typically, you need to implement doInitBody and doAfterBody methods. The doInitBody is called after the body content is set but before it is evaluated, and the doAfterBody is called after the body content is evaluated.

Single Evaluation

Here is an example of single evaluation where we extend the BodyTagSupport class. This example reads the body content, converts it to lowercase, then writes the output back to the client. Sample 11 shows the source code. The body content is retrieved as a string, converted to lowercase, then written back to the client.

Sample 11: ToLowerCaseTag.java

package tags;

import java.io.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public class ToLowerCaseTag extends BodyTagSupport {

   public int doAfterBody() throws JspException {
      try {
         BodyContent bc = getBodyContent();
         // get the bodycontent as string
         String body = bc.getString();
         // getJspWriter to output content
         JspWriter out = bc.getEnclosingWriter();
         if(body != null) {
            out.print(body.toLowerCase());
         }
      } catch(IOException ioe) {
         throw new JspException("Error:
          "+ioe.getMessage());   
      }
      return SKIP_BODY;
   }
}

The next step is to add a tag to the tag library descriptor file, mytaglib.tld. The new tag descriptor is:

<tag>
  <name>tolowercase</name>
  <tagclass>tags.ToLowerCaseTag</tagclass>
  <bodycontent>JSP</bodycontent>
  <info>To lower case tag</info>
</tag>

Note that when you write a tag with a body, the <bodycontent> tag's value must be either JSP or jspcontent, as discussed earlier.

A test driver for this example is shown in Sample 12.

Sample 12: lowercase.jsp

<%@ taglib uri="mytags" prefix="first" %>
<HTML>
<HEAD>
<TITLE>Body Tag</TITLE>
</HEAD>

<BODY bgcolor="#ffffcc">

<first:tolowercase>
Welcome to JSP Custom Tags Programming.
</first:tolowercase>

</BODY>
</HTML>

If you request lowercase.jsp from a web browser, you would see something similar to Figure 4.

Figure 4: Testing the lowercase tag

Multiple Evaluations

Let's now see an example of a body tag evaluated multiple times. The example accepts a string and prints the string as many times as indicated in the JSP. The source code is shown in Sample 13:

Sample 13: LoopTag.java

package tags;

import java.io.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public class LoopTag extends BodyTagSupport {

   int times = 0;

   BodyContent bodyContent;

   public void setTimes(int times) {

      this.times = times;
   }

   public int doStartTag() throws JspException {
      if (times>0) {
        return EVAL_BODY_TAG;
      } else {
         return SKIP_BODY;
      }
   }

   public void setBodyContent(BodyContent 
   bodyContent) {
      this.bodyContent = bodyContent;
   }

   public int doAfterBody() throws JspException {
      if (times >1) {
        times--;
        return EVAL_BODY_TAG;
      } else {
         return SKIP_BODY;
      }
   }

   public int doEndTag() throws JspException {
      try {
         if(bodyContent != null) {
           bodyContent.writeOut(
           bodyContent.getEnclosingWriter());
         }
      } catch(IOException e) {
        throw new JspException(
        "Error: "+e.getMessage());
      }
      return EVAL_PAGE;
   }
}

In this example, the methods implemented play the following roles:

• The doStartTag method gets called at the start of the tag. It checks if the loop needs to be performed.
• The setBodyContent is called by the JSP container to check for more than one loop.
• The doAfterBody method is called after each evaluation; the number of times the loop needs to be performed is decreased by one, then it returns SKIP_BODY when the number of times is not greater than one.
• The doEndTag method is called at the end of the tag, and the content (if any) is written to the enclosing writer.

Similarly to previous examples, the next step is to add a new tag descriptor to mytaglib.tld. The following lines show what needs to be added:

<tag>
  <name>loop</name>
  <tagclass>tags.LoopTag</tagclass>
  <bodycontent>JSP</bodycontent>
  <info>Tag with body and parameter</info>
  <attribute>
     <name>times</name>
     <required>true</required>
     <rtexprvalue>true</rtexprvalue>
  </attribute>
</tag>

Note that the <rtexprvalue> tag specifies that evaluations will be performed at runtime.

A test driver is shown in Sample 14.

Sample 14: loops.jsp

<%@ taglib uri="mytags" prefix="first" %>
<HTML>
<HEAD>
<TITLE>Body Tag</TITLE>
</HEAD>

<BODY bgcolor="#ffffcc">

<first:loop times="4">
Welcome to Custom Tags Programming.<BR>
</first:loop>

</BODY>
</HTML>

Finally, if you request loops.jsp from a browser, you would see output similar to that in Figure 5.

Figure 5: Testing loops.jsp

Programming Guidelines

Here are a few guidelines to keep in mind when developing JSP tag libraries:

• Keep it simple: if a tag requires several attributes, try to break it up into several tags.
• Make it usable: consult the users of the tags (HTML developers) to achieve a high degree of usability.
• Do not invent a programming language in JSP: do not develop custom tags that allow users to write explicit programs.
• Try not to reinvent the wheel: there are several JSP tag libraries available, such as the Jakarta Taglibs Project. Check to see if what you want is already available so you do not have to reinvent the wheel.

Conclusion

In Web Application Development with JSP and XML Part II: JSP with XML in mind, we have seen how to parse XML documents. But even the untrained eye would have noticed that we have embedded lots of the parsing (or logic) code in JSP. Even though we have used JavaBeans to encapsulate much of the Java code, we still ended up with JavaServer Pages mixing program logic with presentation.

Custom tags help you improve the separation of program logic (parsing and iteration in Part II), and presentation. The various examples in this article show how to develop and deploy simple and advanced custom tags. As an exercise, you may want to rewrite the SAX and DOM examples in Part II as tag libraries. Also, you may wish to look at what the Jakarta Taglibs Project has to offer for XML parsing and XSL transformations. It provides tag libraries for other things as well.

For more information

Javaserver Pages, Dynamically Generated Web Content
Javaserver Pages Tag Libraries
Jakarta Taglibs Project
The Jakarta Taglibs Project--Part I
A Standard Tag Library for JavaServer Pages

About the author

Qusay H. Mahmoud provides Java consulting and training services. He has published dozens of articles on Java, and is the author of Distributed Programming with Java (Manning Publications, 1999).