Recipe 22.3 Creating a JSP 2.0 TLD for a Classic Tag Handler

Problem

You want to create a JSP 2.0 TLD file for a tag library.

Solution

Create a tag library descriptor with the proper taglib root element, including the taglib's various xmlns attributes and values.

Discussion

If you are using any JSP 2.0 features with your tag library and TLD, such as a function or tag-file element, then you must use the JSP 2.0-style TLD, as shown in Example 22-3.

The JSP 2.0 TLD is backward compatible with elements defined in the JSP 1.2 DTD. Therefore you can use the taglib and tag elements as they are specified in any existing JSP 1.2 TLDs when you upgrade your TLD file to JSP 2.0. For example, the only difference between the TLD in Example 22-3 and the JSP 1.2 TLD in Example 22-2 is the taglib start tag, which must have exactly the same content as shown here.

Example 22-3. The JSP 2.0 TLD file for our classic tag handler

<taglib xmlns="http://java.sun.com/xml/ns/j2ee" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation=
    "http://java.sun.com/xml/ns/j2ee 
    http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_0.xsd"
 version="2.0"
>

<!-- THE REST OF THE XML CONTENT IS ALMOST EXACTLY THE SAME AS THE JSP 1.2 TLD VERSION
EXCEPT FOR <jsp-version>2.0</jsp-version> AND <body-content>scriptless</body-content>. The
"scriptless" value means that the content of the tag can only be template text (such as
HTML content), Expression Language code, or JSP action elements, but not "scripting"
elements such as the JSP code delineated by <% %> -->
    
    <tlib-version>1.0</tlib-version>
    <jsp-version>2.0</jsp-version>
    <short-name>cbck</short-name>
    <uri>com.jspservletcookbook.tags</uri>
    <description>Cookbook custom tags</description>
    
    <tag>

        <name>logo</name>

        <tag-class>com.jspservletcookbook.LogoTag</tag-class>

        <body-content>scriptless</body-content>

        <description>This tag writes a logo inside the JSP.</description>

        <attribute>
            <name>heading</name>
            <required>true</required>
            <rtexprvalue>true</rtexprvalue>
            <description>
              The heading level for the logo; 1 through 6.
            </description>
        </attribute>
        
        <attribute>
            <name>image</name>
            <required>true</required>
            <rtexprvalue>true</rtexprvalue>
            <description>The image name for the logo.</description>
        </attribute>

       <attribute>
            <name>width</name>
            <required>true</required>
            <rtexprvalue>true</rtexprvalue>
            <description>The image width for the logo.</description>
        </attribute>

        <attribute>
            <name>height</name>
            <required>true</required>
            <rtexprvalue>true</rtexprvalue>
            <description>The image height for the logo.</description>
        </attribute>

    </tag>

</taglib>

The JSP 2.0 TLD is based on an XML Schema file, rather than a DTD (the XML Schema file: http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_0.xsd).

XML Schemas allow the definers of XML documents to create more complex elements and attributes than those allowed in DTDs. XML Schemas are also designed to be valid XML documents themselves, which makes it easier to integrate them with XML-based applications.

The taglib element in Example 22-3 has four attributes. The xmlns attribute specifies that the TLD has the same default namespace as all J2EE deployment descriptors: http://java.sun.com/xml/ns/j2ee.

A namespace is a unique identifier that helps avoid the collision of two XML elements of the same name. For example, the taglib element that is part of the http://java.sun.com/xml/ns/j2ee namespace is different from a taglib element that might be defined as part of the http://acme.com namespace. A namespace has to be unique only within its domain (such as an Internet URL); it does not necessarily represent an actual web document.

The xmlns:xsi attribute specifies the namespace for a set of XML elements related to XML Schema instances. The xsi:schemaLocation attribute specifies the location of the XML Schema on which the current XML document is based.

An XML Schema describes a related set of elements and attributes. An XML Schema instance is an XML document that uses the previously defined XML elements and attributes. This concept is similar to a Java class and its object instances.

Finally, the taglib element's version attribute specifies the JSP-specification version on which the tag library is based, as in JSP 2.0.

Recipe 22.3 Creating a JSP 2.0 TLD for a Classic Tag Handler

Problem

Solution

Discussion

Example 22-3. The JSP 2.0 TLD file for our classic tag handler

See Also