Storing your taglibs in a local filesystem
is great for in-house development and testing, but it's not a good
permanent solution. Custom taglibs should be widely accessible, which
means they must be distributed in a standard and secure manner. Brett
McLaughlin explains how to JAR your custom taglibs for easier
maintenance, distribution, and installation in any JSP-compliant Web
container.

So far in this series we've kept our custom taglibs in a local
filesystem, where we could easily access and manipulate them. While local
access is great for in-house development and testing, it's not a good
permanent solution. The whole point of custom taglibs is that they should
be widely accessible, which means they must be distributed in a
standardized way that also allows for some essential security measures. In
this installment of JSP best practices, you'll learn how to package
your custom taglibs in a JAR file for safe and easy distribution.

Why use JARs?Custom
taglibs are inherently intended for distribution, whether that takes place
within the rather small circle of a company development team, the wider
circle of affiliate organizations, or the outside network of paying
customers. In any of these cases, housing the taglib on your local
filesystem and making it available from that location is a bad idea.

If your taglib is intended for use by an in-house development team, the
first thing you want to think about upon releasing it is separation of
responsibility. In JSP programming, it is ideal to have two teams working
in parallel: Java developers to write the implementation detail and JSP
page authors to deal with the front end. But experience has shown how
quickly this separation breaks down if it isn't enforced. Housing your
custom taglibs on a locally accessible filesystem sets up a situation
where even good intentions -- such as a JSP page author "correcting" the
TLD file or a Java programmer "tweaking" the HTML -- could wreak havoc
with your development cycle, as well as the end product.

The situation becomes even more critical when you factor in remote
parties such as outside companies and organizations. Any time you allow an
outside party (such as an end user or page author) uncontrolled access to
your code, you're inviting trouble. Suppose, for example, that a user from
an outside company changes your TLD, or goofs up the tag class file. Not
only will you very likely be blamed for the resulting errors, but chances
are you won't be able to locate the individual who made the mistake.
You'll spend twice the time you ought to debugging code that is
essentially the result of a user error. And this type of mistake won't
happen just once -- it'll be a recurring incident as long as you house
your master taglib on a locally accessible filesystem.

Finally, let's consider what could happen if you decide to market and
sell your custom taglibs. Decompiling classes is remarkably easy these
days, which means that someone could easily purchase your code, alter it,
and use it maliciously with your company's name attached. Or, they could
simply repackage it and sell it as their own work. Neither scenario is a
particularly good one. Obfuscating your code (which make decompiling
binary code difficult, and often impossible) is one way to avoid malicious
alteration or theft. Packaging your taglib into a single, discrete unit is
also recommended.

The JSP specification allows us to use the Java platform's JAR facility
for packaging custom taglibs. Once they are JARed, taglibs are available
for broad distribution, maintenance, and installation. And, as you will
see, JARing a taglib isn't all that hard to do.

The resulting JAR file can be passed around to whomever you like --
whether that be the page author down the hall or a company across the
ocean.

Documentation and version
controlAn important part of creating any taglib is
documentation -- you are documenting your code, right? -- and this
is especially true when it comes to packaging taglibs for distribution.
You've probably noticed that the above JAR includes the comment
added manifest, which refers to a special type of file
defined by the JAR specification. A manifest is a text file that
has information about a JAR, and is always included in the same place
within a JAR. If you want to know about the contents or functionality of a
Java archive, the manifest is the first (and best) place to look.

In this case, the manifest includes a version identifier (VID), which
lets you track revisions and upgrades between your work and the JAR files
that end users or page authors have.

The above manifest defines the name of the Java package being
distributed and specifies that the JAR file should be sealed.
Sealing a file ensures that all classes in the
com.newInstance.site.tags package must exist within
the same JAR file. By extension, this prevents a user from creating his
own classes, assigning them to the same package, and overriding or
extending their functionality. Sealing is a good practice for ensuring
consistency and versioning of your code.

Adding the manifest to your
JARThe last step is to provide a name, version, and
provider for your taglib package. The info you provide will be easily
accessible by any JAR tool, and will also make it easier for you to
determine whether you need to upgrade the library for your users.

Listing 4 shows how to add a manifest to a JAR file on creation. The
filename here is manifest.mf, but you can use any filename you
choose.

Creating the taglib
URIAfter you have your JAR file, you'll need to let page
authors know how to link to it from their Web container. As with files in
a filesystem, the easiest way to do this is to create a URI (universal
resource identifier), which lives in a web.xml file. Listing 5 shows a
web.xml entry for identifying a taglib:

As you probably noted, we've placed the JAR file in the target Web
application's WEB-INF/lib directory. All JAR files used by a Web
application should reside in this directory. Rather than making a
reference to a TLD file on the filesystem, as we did before, the web.xml
file now points to the JAR file that contains our taglib.

Wrapping upWith the simple
steps outlined here we've moved our taglib out of the general filesystem
and into the more controlled, distributable environment of a JAR file.
Accessing a taglib in a JAR is identical to accessing one in a filesystem
outside of a JAR: you simply specify the URI in a taglib
directive, and get to work.

In the next several tips, we'll move beyond these JSP basics and look
at some Web-specific JSP functionality. Covering subjects ranging from
working with a database to handling dynamic navigation links, these tips
will put some polish on your Java-based Web sites and Web
applications.

About the
authorBrett McLaughlin has been working in computers since the
Logo days (remember the little triangle?). He currently specializes
in building application infrastructure using Java and Java-related
technologies. He has spent the last several years implementing these
infrastructures at Nextel Communications and Allegiance Telecom Inc.
Brett is one of the co-founders of the Java Apache project Turbine,
which builds a reusable component architecture for Web application
development using Java servlets. He is also a contributor of the
EJBoss project, an open source EJB application server, and Cocoon,
an open source XML Web-publishing engine. Contact Brett at brett@oreilly.com.