Introduction

\elcome to or 1ovcat !or/.. 1his book dissects 1omcat 4.1.12 and 5.0.18 and
explains the internal workings o its ree, open source, and most popular serlet
container code-named Catalina. 1omcat is a complex system, consisting o many
dierent components. 1hose who want to learn how 1omcat works oten do
know where to start. \hat this book does is proide the big picture and then
build a simpler ersion o each component to make understanding that
component easier. Only ater that will the real component be explained.
\ou should start by reading this Introduction as it explains the structure o
the book and gies you the brie outline o the applications built. 1he section,
"Preparing Required Sotware", gies you detailed instructions on what sotware
you need to download, how to make a directory structure or your code, etc.
Who 1his Book Is for
1his book is or anyone working with the Jaa technology.
- 1his book is or you i you are a serlet,JSP programmer or a 1omcat
user and you are interested in knowing how a serlet container works.
- It is or you i you want to join the 1omcat deelopment team because
you need to irst learn how the existing code works.
- I you hae neer been inoled in web deelopment but you hae
interest in sotware deelopment in general, then you can learn rom ths
book how a large application such as 1omcat was designed and
deeloped.
- I you need to conigure and customize 1omcat, you should read this
book.
1o understand the discussion in this book, you need to understand object-
oriented programming in Jaa as well as serlet programming. I you are not
amiliar with the latter, there are a plethora o books on serlets, including my
own ]ara for tbe !eb ritb errtet., ]P, ava ]. 1o make the material easier to
understand, each chapter starts with background inormation that will be
required to understand the topic in discussion.
2
How A Servlet Container Works
A serlet container is a complex system. loweer, basically there are three
things that a serlet container does to serice a request or a serlet:
- Creating a request object and populate it with inormation that may be
used by the inoked serlet, such as parameters, headers, cookies, query
string, URI, etc. A request object is an instance o the
javax.servlet.ServletRequest interace or the
javax.servlet.http.ServletRequest interace.
- Creating a response object that the inoked serlet uses to send the
response to the web client. A response object is an instance o the
javax.servlet.ServletResponse interace or the
javax.servlet.http.ServletResponse interace.
- Inoking the service method o the serlet, passing the request and
response objects. lere the serlet reads the alues rom the request object
and writes to the response object.
As you read the chapters, you will ind detailed discussions o Catalina serlet
container.
Catalina Block Diagram
Catalina is a ery sophisticated piece o sotware, which was elegantly designed
and deeloped. It is also modular too. Based on the tasks mentioned in the
section "low A Serlet Container \orks", you can iew Catalina as consisting
o two main modules: the connector and the container.
Iigure I.J: Catalina's main modules
1he block diagram in ligure I.1 is, o course, simplistic. Later in the ollowing
chapters you will uneil all smaller components one by one.
Now, back to ligure I.1, the connector is there to covvect a request with the
container. Its job is to construct a request object and a response object or each
l11P request it receies. It then passes processing to the container. 1he
3
container receies the request and response objects rom the connector and is
responsible or inoking the serlet's service method.
Bear in mind though, that the description aboe is only the tip o the
iceberg. 1here are a lot o things that a container does. lor example, beore it
can inoke a serlet's service method, it must load the serlet, authenticate the
user ,i required,, update the session or that user, etc. It's not surprising then
that a container uses many dierent modules or processing. lor example, the
manager module is or processing user sessions, the loader is or loading serlet
classess, etc.
1omcat 4 and S
1his book coers both 1omcat 4 and 5. lere are some o the dierences
between the two:
- 1omcat 5 supports Serlet 2.4 and JSP 2.0 speciications, 1omcat 4
supports Serlet 2.3 and JSP 1.2.
- 1omcat 5 has a more eicient deault connector than 1omcat 4.
- 1omcat 5 shares a thread or background processing whereas 1omcat 4's
components all hae their own threads or background processing.
1hereore, 1omcat 5 uses less resources in this regard.
- 1omcat 5 does not need a mapper component to ind a child component,
thereore simpliying the code.
Overview of Lach Chapter
1here are 20 chapters in this book. 1he irst two chapters sere as an
introduction. Chapter 1 explains how an l11P serer works and Chapter 2
eatures a simple serlet container. 1he next two chapters ocus on the
connector and Chapters 5 to 20 coer each o the components in the container.
1he ollowing is the summary o each o the chapters.
Note
lor each chapter, there is an accompanying application similar to the
component being explained.
Chapter 1 starts this book by presenting a simple l11P serer. 1o build a
working l11P serer, you need to know the internal workings o two classes in
the java.net package: Socket and ServerSocket. 1here is suicient
4
background inormation in this chapter about these two classes or you to
understand how the accompanying application works.
Chapter 2 explains how simple serlet containers work. 1his chapter comes
with two serlet container applications that can serice requests or static
resources as well as ery simple serlets. In particular, you will learn how you can
create request and response objects and pass them to the requested serlet's
service method. 1here is also a serlet that can be run inside the serlet
containers and that you can inoke rom a web browser.
Chapter 3 presents a simpliied ersion o 1omcat 4's deault connector.
1he application built in this chapter seres as a learning tool to understand the
connector discussed in Chapter 4.
Chapter 4 presents 1omcat 4's deault connector. 1his connector has been
deprecated in aor o a aster connector called Coyote. Neertheless, the deault
connector is simpler and easier to understand.
Chapter 5 discusses the container module. A container is represented by the
org.apache.catalina.Container interace and there are our types o
containers: engine, host, context, and wrapper. 1his chapter oers two
applications that work with contexts and wrappers.
Chapter 6 explains the Lifecycle interace. 1his interace deines the
liecycle o a Catalina component and proides an elegant way o notiying other
components o eents that occur in that component. In addition, the
Lifecycle interace proides an elegant mechanism or starting and stopping
all the components in Catalina by one single start,stop.
Chapter coers loggers, which are components used or recording error
messages and other messages.
Chapter 8 explains about loaders. A loader is an important Catalina module
responsible or loading serlet and other classes that a web application uses. 1his
chapter also shows how application reloading is achieed.
Chapter 9 discusses the manager, the component that manages sessions in
session management. It explains the arious types o managers and how a
manager can persist session objects into a store. At the end o the chapter, you
will learn how to build an application that uses a StandardManager instance
to run a serlet that uses session objects to store alues.
Chapter 10 coers web application security constraints or restricting access
to certain contents. \ou will learn entities related to security such as principals,
roles, login conig, authenticators, etc. \ou will also write two applications that
S
install an authenticator ale in the StandardContext object and uses basic
authentication to authenticate users.
Chapter 11 explains in detail the
org.apache.catalina.core.StandardWrapper class that represents a
serlet in a web application. In particular, this chapter explains how ilters and a
serlet's service method are inoked. 1he application accompanying this
chapter uses StandardWrapper instances to represents serlets.
Chapter 12 coers the
org.apache.catalina.core.StandardContext class that represents a
web application. In particular this chapter discusses how a StandardContext
object is conigured, what happens in it or each incoming l11P request, how it
supports automatic reloading, and how 1omcat 5 shares a thread that executes
periodic tasks in its associated components.
Chapter 13 presents the two other containers: host and engine. \ou can also
ind the standard implementation o these two containers:
org.apache.catalina.core.StandardHost and
org.apache.catalina.core.StandardEngine.
Chapter 14 oers the serer and serice components. A serer proides an
elegant start and stop mechanism or the whole serlet container, a serice
seres as a holder or a container and one or more connectors. 1he application
accompanying this chapter shows how to use a serer and a serice.
Chapters 15 explains the coniguration o a web application through
Digester, an exciting open source project rom the Apache Sotware loundation.
lor those not initiated, this chapter presents a section that gently introduces the
digester library and how to use it to conert the nodes in an XML document to
Jaa objects. It then explains the ContextConig object that conigures a
StandardContext instance.
Chapter 16 explains the shutdown hook that 1omcat uses to always get a
chance to do clean-up regardless how the user stops it ,i.e. either appropriately
by sending a shutdown command or inappropriately by simply closing the
console.,
Chapter 1 discusses the starting and stopping o 1omcat through the use o
batch iles and shell scripts.
Chapter 18 presents the deployer, the component responsible or deploying
and installing web applications.
6
Chapter 19 discusses a special interace, ContainerServlet, to gie a
serlet access to the Catalina internal objects. In particular, it discusses the
Manager application that you can use to manage deployed applications.
Chapter 20 discusses JMX and how 1omcat make its internal objects
manageable by creating MBeans or those objects.
1he Application for Lach Chapter
Lach chapter comes with one or more applications that ocus on a speciic
component in Catalina. Normally you'll ind the simpliied ersion o the
component being explained or code that explains how to use a Catalina
component. All classes and interaces in the chapters' applications reside in the
ex[chapter number].pyrmont package or its subpackages. lor example,
the classes in the application in Chapter 1 are part o the ex01.pyrmont
package.
Preparing the Required Software
1he applications accompanying this book run with J2SL ersion J.4. 1he zipped
source iles can be downloaded rom the authors' web site
www.brainysotware.com. It contains the source code or 1omcat 4.1.12 and the
applications used in this book. Assuming you hae installed J2SL 1.4 and your
path enironment ariable includes the location o the JDK, ollow these steps:
1. Lxtract the zip iles. All extracted iles will reside in a new directory called
How1omcatWorks. low1omcat\orks is your working directory. 1here
will be seeral subdirectories under low1omcat\orks, including lib
,containing all needed libraries,, src ,containing the source iles,, webroot
,containing an l1ML ile and three sample serlets,, and webapps
,containing sample applications,.
2. Change directory to the working directory and compile the jaa iles. I
you are using \indows, run the win-compile.bat ile. I your computer
is a Linux machine, type the ollowing: ,don't orget to chmod the ile i
necessary,
./linux-compile.sh
Note
More inormation can be ound in the Readme.txt ile included in the ZIP ile.