John Topley’s Weblog

Yesterday I spent more time than I would have liked trying to track down a problem with a custom JSP tag library that I was developing. I'd added some attributes to the TLD file and packaged the custom tag as a JAR file ready for use by my test web application. I copied the JAR to the application's WEB-INF/lib directory. When I came to run my JSP, Oracle JDeveloper couldn't compile it. The compiler gave an error message about an invalid element and said that it was unable to load the taghandler class.

I went back to the TLD file and carefully scrutinised it to make sure that it was well-formed XML, which it was. Then I examined the associated tag class, and at this point I thought I'd found the source of the problem because I noticed two typos in some accessor and mutator methods. I corrected these and redeployed, but I still got the error. I roped in a couple of colleagues to help but they couldn't see anything wrong either. The frustration began to build at this point.

Finally I remembered something I'd successfully tried a while ago whilst having a problem with the Jakarta Struts configuration file. I copied the URL from the DOCTYPE at the top of the tag library deployment descriptor and pasted it into a web browser:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN"
  "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">
<taglib>
  <tlib-version>1.0</tlib-version>
  <jsp-version>1.2</jsp-version>
  .
  .
  .

After a while examining the DTD, I saw what was wrong:

<!--
The tag defines a unique tag in this tag library. It has one attribute, id.
The tag element may have several subelements defining:

name          The unique action name

tag-class     The tag handler class implementing javax.servlet.jsp.tagext.Tag

tei-class     An optional subclass of javax.servlet.jsp.tagext.TagExtraInfo

body-content  The body content type

display-name  A short name that is intended to be displayed by tools

small-icon    Optional small-icon that can be used by tools

large-icon    Optional large-icon that can be used by tools

description   Optional tag-specific information

variable      Optional scripting variable information

attribute     All attributes of this action

example       Optional informal description of an example of a use of this tag
-->

—My file had the <example> sub-element immediately after <description>, when it should have been after <attribute>. I think this happened because I'd used a JDeveloper wizard to get the skeleton of the tag started and had then gone back and manually added some attributes. It could be argued that this wouldn't have happened had I read the relevant documentation, but who has time to read all the J2EE specs and be productive? The lesson I took away from yesterday is that:

1. The order of elements in these files is important.
2. When dealing with XML files you can always refer back to the associated DTD (or XSD) to find out the definitive answer on what should go where. Which is of course what they're there for!