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:
- The order of elements in these files is important.
- 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!