In this article you'll learn

• what a custom tag library is,
• why you want to use a custom tag library,
• the composition of a tag library, and
• how to build and use a complete library.

What a Custom Tag Library Is

• be customized via attributes passed from the calling page, either staticly or determined at runtime;
• have access to all the objects available to JSP pages including request, response, in and out;
• modify the response generated by the calling page;
• communicate with each other; you can create and initialize a JavaBeans component, create a variable that refers to that bean in one tag, and then use the bean in another tag;
• be nested within one another, allowing for complex interactions within a JSP page; and
• encapsulate both simple and complex behaviors in an easy to use syntax and greatly simplify the readability of JSP pages.

The Composition of a Tag Library

< ?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
 < jspversion>1.1
 < shortname>oreillySamples
 < info>OReilly Sample Tag library
  < !-A Simple tag -->
  < tag>
    < name>hello
    < tagclass>oreilly.examples.Hello < /tagclass>
  < !--Body content can have a value of 
    empty: no body 
      JSP: body that is evaluated by container, then possibly processed by the tag 
      tagdependent: body is only processed by tag; JSP in body is not evaluated.
   -- >
    < bodycontent>empty
    < info>
 This is a simple hello tag.
    < /info>
  < !-- Optional attributes  -->
  < !- personalized name -->
  < attribute>
      < name>name< /name>
      < required>false< /required>
      < rtexpvalue>false< /rtexpvalue>
  < /attribute>
< /tag>
< /taglib>

package oreilly.examples
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;
/**
 * This is a simple tag example to show how content is added to the
 * output stream when a tag is encountered in a JSP page. 
 */
public class Hello extends TagSupport {
 private String name=null;
    /**
      * Getter/Setter for the attribute name as defined in the tld file 
      * for this tag
      */
public void setName(String value){
    name = value;
}

 public String getName(){
          return(name);
       }
/**
* doStartTag is called by the JSP container when the tag is encountered
*/
    public int doStartTag() {
   try {
        JspWriter out = pageContext.getOut();
        out.println("< table border="\1\">");
      if (name != null)
       out.println("< tr>< td> Hello " + name + " < /td>< /tr>");
        else
       out.println("< tr>< td> Hello World < /td>< /tr>");
   } catch (Exception ex) {
     throw new Error("All is not well in the world.");
   }
   // Must return SKIP_BODY because we are not supporting a body for this 
   // tag.
   return SKIP_BODY;
    }
/**
 * doEndTag is called by the JSP container when the tag is closed
 */
 public int doEndTag(){
    try {
         JspWriter out = pageContext.getOut();
        out.println("< /table>");
    } catch (Exception ex){
      throw new Error("All is not well in the world.");
    }
 }
}

The JSP

Once your TLD and tag handlers are created, you can begin accessing the tags in your JSP. You declare that a JSP page will use tags defined in a tag library by including a taglib directive in the page before any custom tag is used. The prefix attribute is a shortcut to referencing the library throughout the page.
Sample Hello.jsp:
< %@ taglib uri="/oreillySample.tld" prefix="sample" %>
< html>
        < head>
                < title>Your Standard Hello World Demo
        < /head>
        < body bgcolor="#ffffff">
                < hr />
                < sample:hello name="Sue"/>
                < hr />
        < /body>
< /html>
The HTML source output from this JSP would look like:
< html>
        < head>
                < title>Your Standard Hello World Demo< /title>
        < /head>
        < body bgcolor="#ffffff">
                < hr />
        < table border="1">
          < tr>< td> Hello Sue < /td>< /tr>
                < /table>
                < hr />
        < /body>
< /html>
You can see how the tag was evaluated and the contents of the tag inserted into the output stream.
If you wanted to add functionality to our tag to make it more flexible, say to evaluate a body a certain number of times and make the name attribute evaluated at runtime, you can do so fairly easily with a few changes. First you would make the following changes to the TLD file. The tag definition would look like
  < tag>
    < name>hello
    < tagclass>oreilly.examples.Hello < /tagclass>
 < !-- Allow for a body to be included for this tag -->
    < bodycontent>JSP
    < info>
 This is a simple hello tag.
    < /info>
    
    < !-- Optional attributes  -->
    < !-- personalized name -->
    < attribute>
      < name>name< /name>
      < required>false< /required> 
    < rtexpvalue>true< /rtexpvalue>
    < /attribute>
    < !-allow for the jsp coder to specify how many times to iterate -->
    < attribute>
      < name>iterations< /name>
      < required>false< /required> 
    < rtexpvalue>false< /rtexpvalue>
    < /attribute>

< /tag>
Then you must alter the handler class by extending TagBodySupport and implementing the body methods if you wanted different behavior from that provided in the base class implementation. The handler class would now look like
public class Hello extends BodyTagSupport {
 private String name=null;
    private int iterations=1;

 /**
     * Getter/Setter for the attribute name as defined in the tld file 
     * for this tag
     */
 public void setName(String value){
  name = value;
 }

 public String getName(){
  return(name);
 }
 /**
     * Getter/Setter for the attribute iterations as defined in the tld file 
     * for this tag
     */

 public void setIterations(String value){
     try {
       iterations = Integer.parseInt(value);
     } catch(NumberFormatException nfe) {
       iterations = 1;
     } 
   }

 public String getIterations(){
  return(Integer.toString(iterations));
 }

    public int doStartTag() throws JspTagException{
   try {
        JspWriter out = pageContext.getOut();
        out.println("< table border=\"1\">");
      if (name != null)
       out.println("< tr>< td> Hello " + name + " < /td>< /tr>");
        else 
       out.println("< tr>< td> Hello World < td>< /tr>");
   } catch (Exception ex) {
     throw new JspTagException("All is not well in the world." + ex );
   }
   // Evaluate the body if there is one
   return EVAL_BODY_TAG;
    }

 public int doEndTag()throws JspTagException {
    try {
         JspWriter out = pageContext.getOut();
        out.println("< /table>");
    } catch (Exception ex){
      throw new JspTagException("All is not well in the world." + ex);
    }
 }

 public int doAfterBody() throws JspTagException {
    if (iterations-- >= 1) {
      BodyContent body = getBodyContent();
      try {
  // Make sure we put anything in the output stream in the 
  // body to the output stream of the JSP
        JspWriter out = body.getEnclosingWriter();
        out.println(body.getString());
        body.clearBody(); // Clear for next evaluation
      } catch(IOException ioe) {
        throw new JspTagException("Error in Hello tag doAfterBody " + ioe);
      }
      return(EVAL_BODY_TAG);
    } else {
      return(SKIP_BODY); 
 }
}
Now let's make the simple changes in the JSP file. Our sample Hello.jsp looks like
< %@ taglib uri="/oreillySample.tld" prefix="sample" %>
< %!
    // allow a username to be passed in the request
    String userName = request.getParameter("NAME");
% >

< html>
        < head>
                < title>Your Standard Hello World Demo < /title>
        < /head>
        < body bgcolor="#ffffff">
                < hr />
                < sample:hello name="" iterations="2" >
   < tr>< td>Have a nice day< /b>< /td>
   < /sample:hello>
                < hr />
        < /body>
< /html>

If our JSP page was called like hello.jsp?NAME=Sue our output would look like
< html>
        < head>
                < title>Your Standard Hello World Demo
        < / head>
        < body bgcolor="#ffffff">
                < hr />
        < table border="1">
          < tr>< td> Hello Sue < /td>< /tr>
     < tr>< td>< b>Have a nice day< /b>< /td>< /tr>
     < tr>< td>< b>Have a nice day< /b>< /td>< /tr>
                < /table>
                < hr />
        < /body>
< /html>
This simple example is but a small glimpse at the power of custom tag libraries. We examined how to create and use a simple tag library and then easily extend its functionality. The next article will examine some of the advanced features of tags, including defining scripting variables and cooperating tags. It will also go through working examples of each.