01 Goodwill 1/17/02 3:28 PM Page 1
CHAPTER
1
Introducing JSP Custom Tags
and Web Applications
In this chapter, we begin our JSP custom tag discussions. Our goal will be to get a solid
overall picture of the components used in a tag library solution. We will start by describ-
ing Web applications, which act as the container for custom tags. We then move on to
defining custom tags and the steps required when packaging them into libraries. At the
end of this chapter, you should have an understanding of what a tag library is and how
tag library solutions are assembled.
Web Applications
To understand the role of a custom tag library, you need to have an understanding of
Java Web applications. The Java Servlet Specification 2.2 introduced the concept of a
Web application. According to this specification, “A Web Application is a collection of
servlets, html pages, classes, and other resources that can be bundled and run on multi-
ple containers from multiple vendors.” Essentially, a Web application is a collection of
one or more Web components that have been packaged together for the purpose of cre-
ating a complete application that can be easily distributed and deployed into the Web
layer of an enterprise application. The following list contains the common components
that can be packaged in a Web application:
II Servlets
II JSPs
II JSP custom tag libraries
II Utility classes
1
01 Goodwill 1/17/02 3:28 PM Page 2
2 Introducing JSP Custom Tags and Web Applications
II Static documents, including HTML, images, JavaScript, and so on
II Meta information describing the Web application
Directory Structure
All Web applications are packed into a common directory structure. This directory
structure is the container that holds the components of a Web application. The first step
in creating a Web application is creating this structure. Table 1.1 lists the directories for
a sample Web application named wiley, and describes what each directory should con-
tain. Each directory will be created from the of the Servlet/JSP con-
tainer. An example of a using Tomcat 4 would be D:\Jakarta Tomcat
4.0\webapps\.
Table 1.1 Web Application Directory Structure
DIRECTORY CONTAINS
/wiley All JSP and HTML files. This is the root directory of the
Web application.
/wiley/WEB-INF All resources related to the application that are not in
the document root of the application. Your Web
application deployment descriptor is located in this
directory. Note that the WEB-INF directory is not part
of the public document. No files contained in this
directory can be served directly to a client.
/wiley/WEB-INF/classes Servlet and utility classes.
/wiley/WEB-INF/lib Java Archive (JAR) files that the Web application
depends on. You will use this directory to store your
custom tag libraries after they have been packaged.
You will also use this directory to hold your tag library
descriptors (TLDs). We discuss custom tag libraries and
TLDs later in the chapter.
N OT E Web applications allow classes to be stored in both the /WEB-
INF/classes and /WEB-INF/lib directories. The class loader will load classes
from the /classes directory first, followed by the JARs in the /lib directory. If you
have duplicate classes in both the /classes and /lib directories, the classes in
the /classes directory will take precedence.
Web Application Deployment Descriptor
The backbone of any Web application is its deployment descriptor, which describes all
the components in the Web application. The Web application deployment descriptor is
an XML file named web.xml that is located in the //application-
01 Goodwill 1/17/02 3:28 PM Page 3
Web Applications 3
name/WEB-INF/ directory. For the Web application wiley, the web.xml file would be
located in the //wiley/WEB-INF/ directory. The information that can
be described in the deployment descriptor includes the following elements:
II ServletContext init parameters
II Localized content
II Session configuration
II Servlet/JSP definitions
II Servlet/JSP mappings
II Tag library references
II Mime type mappings
II Welcome file list
II Error pages
II Security Realm Configurations
The following code snippet shows an example deployment descriptor that defines a
tag library. We will examine the taglib element in much more detail later in this text:
/customtags
/WEB-INF/lib/customtags.tld
Creating and Packaging a Web Application
Now that we have a good understanding of what makes a Web application, let’s go
through the physical steps required when creating and packaging a Web application.
Each of the required steps are covered in the following list:
1. Decide upon a unique name that identifies your Web application. This name will
be used as part of the Web application URI and as the packaging name.
2. Create the directory structure that we discussed in the previous section, “Direc-
tory Structure,” substituting the name of your Web application for the previously
mentioned wiley Web application name.
01 Goodwill 1/17/02 3:28 PM Page 4
4 Introducing JSP Custom Tags and Web Applications
3. Create an empty web.xml file, and copy this file to the /webappname/WEB-INF/
directory. An example empty web.xml file is the following:
4. Move all of your Web application components, JSPs, servlets, and so on into the
appropriate directories mentioned earlier.
5. Modify the web.xml, if necessary.
That is it. You now have a complete Web application. At this point, you can decide
upon your application deployment mechanism. The simplest form of deployment is to
move your entire Web application directory structure in to a JSP/servlet container. If
you use the Tomcat 4 container, then you would move your directory structure into the
following directory:
/webapps/
The second method of deployment involves packaging your Web application in an
archive file. To do this, you use the standard packaging format for a Web application,
which is a Web ARchive (WAR) file. A WAR file is simply a JAR file with the extension
.war as opposed to .jar. You can create a WAR file by using Java’s archiving tool jar. To
create a WAR file, you simply need to change to the root directory of your Web applica-
tion, and type the following command:
jar cvf webappname.war .
For instance, the command jar cvf wiley.war . will produce an archive file named
wiley.war that contains the entire wiley Web application. Now you can deploy your Web
application by distributing this file.
What Are JSP Custom Tags?
JavaServer Pages (JSP) custom tags encapsulate functional and/or business logic that
can be reused inside a JSP. They give you the ability to insert Extensible Markup Lan-
guage (XML) style tags representing complex business logic into a JSP without having
the JSP code itself become overly complicated. The basic composition of a custom tag
includes an XML tag with optional tag attributes and an optional tag body. Some of the
characteristics that define custom tags are listed here:
II Custom tags have access to all the implicit JSP objects. We will discuss each of
these objects in Chapter 4, “JSP Overview and Architecture.”
II Custom tags can be dynamically configured using tag attributes.
01 Goodwill 1/17/02 3:28 PM Page 5
What Are JSP Custom Tags? 5
II Custom tags can communicate with each other through either nesting or shared
objects.
II Custom tags render complex business logic into a simple XML syntax.
To illustrate the power of using custom tags, the code snippet in Listing 1.1 shows an
example JSP containing two custom tags used to perform a SQL query and iterate over
the results. As you examine this JSP, you should notice the bolded text. These sections
represent the custom tags that will perform the query and iterate over the results. The
tag code used here is obviously much less complicated than the Java code that would be
used to actually perform the same logic:
Custom Tags Demo
SELECT * FROM CONTACTS
UsernameFirst NameLast Name
Listing 1.1 JSP containing two custom tags to perform SQL queries and iterate over the
results.
01 Goodwill 1/17/02 3:28 PM Page 6
6 Introducing JSP Custom Tags and Web Applications
This simple XML notation is possible because the Java code that actually implements
this complex logic is abstracted into a Java class called a tag handler. Every custom tag
has a tag handler. Three types of tag handlers are available: tag handlers without bodies
(simple tags), tag handlers with bodies, and iteration tag handlers. We will focus on each
of these throughout the remainder of this book.
Custom Tag Libraries
Custom tags are usually grouped together into libraries called, plainly enough,
custom tag libraries. A custom tag library is composed of one or more custom tag
handlers with a Tag Library Descriptor (TLD). A TLD is an XML file that defines each
tag handler in a tag library. All tag handlers are required to have an entry in the
TLD.
The steps involved when you’re creating and deploying a custom tag library are part
of a well-defined process. This process can be broken down into the following steps.
1. Create one or more tag handlers containing the logic to be executed when a tag
is encountered. The following code shows a simple tag handler:
import java.io.IOException;
import javax.servlet.jsp.tagext.Tag;
import javax.servlet.jsp.PageContext;
import javax.servlet.jsp.JspWriter;
import javax.servlet.jsp.JspException;
import javax.servlet.jsp.tagext.TagSupport;
public class SimpleTag extends TagSupport {
public int doStartTag()
throws javax.servlet.jsp.JspException {
// Get a JspWriter from the PageContext
JspWriter out = pageContext.getOut();
try {
out.print("Hello from a simple JSP.");
}
catch (IOException e) {
throw new JspException("IOException thrown:" +
e.getMessage());
}
return Tag.EVAL_BODY_INCLUDE;
}
}
01 Goodwill 1/17/02 3:28 PM Page 7
What Are JSP Custom Tags? 7
N OT E For now, you can ignore the details of this tag handler and its TLD.
We will describe these details in subsequent chapters.
2. This tag simply writes the string Hello from a simple JSP. to the client browser
that made the request to the JSP referencing this tag handler.
Describe this tag handler. To do this, you must create a TLD that defines this tag
handler. The TLD used to describe this tag handler can be found in the following
code snippet:
1.0
1.2
chapter1
simple
SimpleTag
JSP
Just a Simple Tag Example
As you can see, this snippet defines a single tag that can be referenced in a JSP
using the name simple. It defines the tag handler named SimpleTag that will be
executed with every occurrence of the simple tag.
3. Publish this tag library to a Web application so that it can be used by a JSP. To
do this, you need to add an entry to the Web application’s web.xml file. The
entry to deploy this library is as follows:
/chapter1
/WEB-INF/lib/chapter1.tld
01 Goodwill 1/17/02 3:28 PM Page 8
8 Introducing JSP Custom Tags and Web Applications
This entry in the web.xml file tells the Web application two things. First, it
defines a URI, using the subelement. The URI represents a unique
key that the Web application can use to look up this tag library. Second, the
entry defines the location of the TLD representing this tag library, using the
subelement.
4. Add a tag to a JSP that references the SimpleTag handler. An example JSP con-
taining a reference to the simple tag is listed here:
Custom Tag Example
Two elements in this JSP are used to reference the SimpleTag handler. The first
is the taglib directive. A taglib directive is a JSP directive that tells the Web
application container which tag libraries this JSP will use and what prefix each
of these tags will be referenced by. The second element is the actual tag ele-
ment. This element represents the SimpleTag handler that is referenced by the
URI /chapter1. The output of this JSP would be an HTML page containing the
text Hello from a simple JSP.
After you have examined these four components, you will see that there is a link
between each of them, starting with simple.jsp. This link is shown in Figure 1.1.
The container uses these links to determine which tag handler should be executed
when a particular tag is encountered. The steps performed by the Web application con-
tainer when it encounters a reference to the simple tag are as follows:
1. The Web application container encounters the tag and parses
out the prefix chp1 and the tag name simple.
2. The container then looks in the list of taglib directives referenced in this JSP for
a prefix attribute with a value of chp1.
3. Once it finds a matching taglib directive, the container gets the value of the
taglib uri attribute. In this case, the uri attribute has a value of /chapter1. The
container looks in the Web application’s web.xml file for a element that
has a equal to /chapter1.
01 Goodwill 1/17/02 3:28 PM Page 9
What Are JSP Custom Tags? 9
4. Once the container finds the matching , it gets the location of the tag
library’s TLD from the subelement. In this case, the TLD is in
a file named chapter1.tld located in the /WEB-INF/lib/ directory of the Web
application.
5. The container then looks in TLD for a named simple. When the container
finds the matching element, it has completed its search and has all the
values it needs to execute the appropriate tag handler, which in this case is the
class SimpleTag.
/chapter1
/WEB-INF/lib/chapter1.tld
Find matching URI
JSP
Tag entry in web.xml.
Custom Tag Example
simple
Look up tag SimpleTag
JSP
handler. Just a Simple Tag Example
Instantiate and execute
the tag handler.
SimpleTag.class
Figure 1.1 Link between custom tag components.
01 Goodwill 1/17/02 3:28 PM Page 10
10 Introducing JSP Custom Tags and Web Applications
Summary
In this chapter, we began our custom tag coverage. We started by describing Java Web
applications, which act as the container for custom tag libraries. We then went on to
describe custom tags and custom tag libraries and their components. We concluded by
describing the steps the container completes when it encounters a custom tag while
processing a JSP. In the next chapter, we will explain how to install and configure the
Tomcat JSP/servlet container, and develop a custom tag application that shows the
power of custom tag libraries.