The Java Developers Almanac 1.4


Order this book from Amazon.

   
Home > List of Packages > javax.servlet.jsp.tagext  [1 examples]

e1070. The Quintessential Custom Tag

A custom tag handler must implement the Tag interface. This interface is implemented by many convenient support classes from which a custom tag handler can extend. As a JSP page is executed and the custom tag is encountered, the doStartTag() of the tag handler is executed. If that method does not throw an exception, the tag handler's doEndTag() method is then called.

The JSP container may create many instances of the tag handler but guarantees that an instance services only one request at a time. A JSP container also typically reuses a tag handler instance and so instance variables should be appropriately reset if necessary.

This example implements a tag handler for the simplest type of tag - - one without attributes or a body. This custom tag simply prints the current time and day.

    package com.mycompany;
    
    import javax.servlet.jsp.*;
    import javax.servlet.jsp.tagext.*;
    
    // This tag simply emits the current date and time.
    public class MyTagHandler extends TagSupport {
        public int doStartTag() throws JspException {
            try {
                // Print the current date and time
                pageContext.getOut().print(""+new java.util.Date());
            } catch (java.io.IOException e) {
                throw new JspTagException("MyTag: "+e.getMessage());
            }
            return SKIP_BODY;
        }
    
        public int doEndTag() {
            return EVAL_PAGE;
        }
    }

A web application wishing to use the custom tag must not only include the custom tag's class file but also its Tag Library Descriptor (TLD) as well. The TLD is a file that contains information about one or more custom tags and is needed by a JSP container to process pages that use a custom tag. Here's the TLD file (mytaglib.tld) for the custom tag:

    <?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">
    <taglib>
      <%-- Version of this tag library; it should have the form 123 or 123.456 --%>
      <tlib-version>0.96</tlib-version>
    
      <%-- The required version of JSP for this tag library --%>
      <jsp-version>1.2</jsp-version>
    
      <%-- The preferred prefix for this tag library --%>
      <short-name>my</short-name>
    
      <%-- This is the URI that uniquely identifies this tag library.
           The URI does not have to exist; it is merely an identifier --%>
      <uri>http://com.mycompany/taglib/mytaglib</uri>
    
      <%-- This name is used by tools to represent this tag library --%>
      <display-name>My Tag Library</display-name>
    
      <description>This is a description of the tag library.</description>
    
      <tag>
        <%-- Name of tag in this library --%>
        <name>simple</name>
        <tag-class>com.mycompany.MyTagHandler</tag-class>
    
        <%-- Specify that the tag must not have a body --%>
        <body-content>empty</body-content>
        <description>
            This is a description of the tag.
        </description>
      </tag>
    </taglib>
Here's an example of a JSP page that uses the custom tag. The TLD file is assumed to be in WEB-INF/tld and the MyTagHandler.class file in WEB-INF/classes/com/mycompany:
    <%@ taglib uri="/WEB-INF/tld/mytaglib.tld" prefix="my" %>
    
    <my:simple/>

© 2002 Addison-Wesley.