Tomcat 6 Developer's Guide

Table of Contents

Tomcat 6 Developer's Guide

Credits

About the author

Acknowledgement

About the reviewers

Preface

What this book covers

What you need for this book

Who this book is for

Conventions

Reader feedback

Customer support

Errata

Piracy

Questions

1. Introduction to Tomcat

What's the story behind Tomcat?

What exactly is Tomcat?

JSPs

Servlet container

Why this book?

Gathering our tools

Java Development Kit (JDK) 6.0

Verifying downloaded files

Apache Ant

Subversion

Obtaining the Tomcat source code

Using Subversion

Tomcat source distribution

Getting ready to build Tomcat

Downloading dependencies

Building Tomcat

Starting up your shiny new Tomcat

Eclipse

Summary

2. Servlet API Overview

Java Community Process

Java Enterprise Edition platform

What is an enterprise application?

Simultaneous users

Highly available, reliable, and scalable

Heterogeneous environment

Distributed nature

Java EE architecture

Java based

Generic APIs

Java EE containers and container services

Java EE components and their APIs

Java EE Service APIs

What is a typical Java EE application architecture?

Hypertext Transfer Protocol (HTTP)

Uniform Resource Locator, URL

HTTP methods

GET (HTTP/0.9)

POST (HTTP/1.0)

PUT (HTTP/1.1)

DELETE (HTTP/1.1)

TRACE (HTTP/1.1)

OPTIONS (HTTP/1.1)

HEAD (HTTP/1.0)

HTTP requests

HTTP responses

The response line

Response headers

Spying on HTTP

What is the Servlet API?

Servlet container

Core servlet classes

Servlets

ServletConfig interface

ServletContext interface

Multithreading in servlets

Request

Request parameters and attributes

Protocol and URI details

Reading request data

Connection information

HTTP specific information

Response

Sessions

Filters

Listeners

Web applications

Deployment descriptors

Summary

3. Servlet Container Overview

Component taxonomy

Architectural benefits

Top Level Components

Server

Service

Connectors

Container components

Engine

Virtual host

Basic concepts

Virtual host techniques

IP-based virtual hosting

Name-based virtual hosting

Virtual host aliasing

Context

Context configuration

Wrapper

Nested components

Valve

Realm

Executor

Listener

Manager

Loader

Delegation model

Java EE class loading

Tomcat's additional class loaders

Class reloading in web applications

Logger

Resources

Summary

4. Starting Up Tomcat

Using scripts

Setting up the environment

Executing the requested command

Setting up your project

Modifying the Run/Debug configuration

Bootstrapping Tomcat

Bootstrapping environment variables

Bootstrapping class loading

Bootstrapping the embedded container

Bootstrapping the Tomcat component hierarchy

Commons Digester

The pattern

The rule

The object stack

Using the Digester

The server.xml Digester

Parsing the server.xml file

Initializing the Server

Adding a new web application to Tomcat in Eclipse

Summary

5. The Server and Service Components

Setting up your project

Installing MySQL

Installing the MySQL driver

Enhancing the devguide web application

server.xml

Context fragment

Web application deployment descriptor

The contact list servlet

Additional notes

JNDI service

Basic JNDI concepts

Context

InitialContext

Environment naming context

JNDI URLs

Initializing an InitialContext

Looking up names

Using multiple naming implementations

URL context factory lookup implementation details

References

JNDI resources

Using JNDI

Component developer responsibilities

Using JNDI within a web application component

Publishing logical references

Application deployer responsibilities

Resource definition levels

Binding logical references

StandardServer

Lifecycle

Shutdown

JNDI implementation

Structural relationships

NamingContext

References

Factories

URL context factory

StandardService

Summary

6. The Connector Component

Connector classification

Usage scenario

Tomcat with external web server

mod_jk

mod_proxy

Tomcat in standalone mode

Protocol

Implementation architecture

Apache Portable Runtime Connector

JIO Connector aka Coyote

NIO connector

Connector configuration

Binding attributes

Socket attributes

Thread parameters

The connector subsystem—a structural perspective

Objective 1: Collection point

Objective 2: Establishing relationships

Objective 3: Accept incoming connections

Objective 4: Maintain a pool of worker threads

Objective 5: Maintain a mapping of request processing components

Objective 6: Insulate the engine from the outside world

Modeling the Request and Response

Coyote and Catalina

Request classes

Coyote Request

Catalina Request

Response classes

HTTP classes

MimeHeaders

Parameters and ParameterMap

Cookies and ServerCookie

Stream classes

InternalInputBuffer

InternalOutputBuffer

InputBuffer

OutputBuffer

ServletInputStream and CoyoteInputStream

ServletOutputStream and CoyoteOutputStream

Helper classes

ByteChunk and CharChunk

MessageBytes

Socket programming

Socket options

SO_TIMEOUT

TCP_NODELAY

SO_LINGER

The connector subsystem—a dynamic perspective

Initializing the Apache Portable Runtime (APR)

Instantiating a Connector

Initializing the Mapper

Receiving a request

Thread notification

End point

Connection handler

ConcurrentLinkedQueue

Http11Processor

CoyoteAdapter

Completing the request

Summary

7. The Engine Component

Containers

Nested components

Engine

Configuring an Engine

Implementation details

StandardEngine

Container interface

ContainerBase abstract class

Parent and child relationships

Nested components

Valve management

Life cycle methods

Listener management

Background processing

Pipeline

Pipeline execution scope

Valve execution order

StandardPipeline

Valve manipulation

Lifecycle methods

Valve

ValveBase

StandardEngineValve

Request Dumper Valve

Request Filter Valve

AccessLogValve

Valve instantiation

AccessLogElement

Named patterns

Valve startup

Valve invocation

Summary

8. The Host Component

Virtual hosts

Tomcat virtual hosts

Virtual hosting scenarios

Case 1: Name-based virtual hosting

Aliasing: Multiple domains to a single set of content

Case 2: IP-based virtual hosting

Configuring a host

StandardHost

HostConfig

Contexts and context fragments

DeployedApplication

Lifecycle events

Deploying context fragments

Deploying WAR files and exploded directories

Periodic events

Examples of name-based virtual hosting

Web Application Deployment Descriptor (web.xml)

Context Fragment (context.xml)

webapp1/index.html

build.xml

Aliasing

Name-based virtual hosting

IP-based virtual hosting

StandardHostValve

The servlet error handling mechanism

Exception processing

Finding a custom error page by exception type

Finding a custom error page by response status code

Setting request attributes

Forwarding to the error resource

Method termination

ErrorReportValve

Error page mechanism example

Summary

9. The Context Component

Aspects of the Context component

The Context aspect

Configuration files

Document base and context path

Context children

WatchedResource

Loader

Resources

ResourceLink

Context parameters

Environment variables

Valves

Manager

Realm

Web application aspect

Configuration files

Web application resources

Resources

Resource cache

Resource retrieval

BaseDirContext

FileDirContext

ProxyDirContext

Looking up resources

Cache lookup

Miscellaneous methods

Shared library mechanism

Manifest file format

URLs and protocol handlers

Accessing resources

Protocol handlers

java.net.URL

java.net.URLStreamHandler

java.net.URLConnection

java.net.URLStreamHandlerFactory

Protocol handler implementation

Locating a stream handler

The jndi protocol

DirContextURLStreamHandlerFactory

DirContextURLStreamHandler

DirContextURLConnection

Java class loading

Advantages of dynamic class loading

Class loader hierarchy

Class loader rules

Implicit and explicit class loading

Tomcat class loading

Implementing a custom class loader

Making a class available

The custom web application class loader

Class loader initialization

ResourceEntry

loadClass()

findClass()

getResource()

Context initialization and startup

Context initialization

Digesting the context fragment

Setting the document base

Context startup

Anti resource locking

Setting up the Context's resources

Setting up the Context's Loader

Publish the work directory

Setting up a servlet context

Validating optional JARs

Naming context

Starting nested components

Configuring the web application aspect

The Mapper

Starting listeners

Starting application filters

Session manager and the background thread

Loading servlets on startup

Request processing

Hot deploying a context

Determining if a reload is necessary

Reloading a context

Context example

Deployment descriptor

Source files

HelloWorldServlet.java

Message.java

Listeners

MyServletContextListener.java

MyServletRequestListener.java

MyFilter.java

Summary

10. The Wrapper Component

StandardWrapper

Servlet lifecycle

Loading a servlet

Mappers

Mapping rules

Partial URLs

Tomcat mappers

The connector's mapper

Locating the host and context

Locating the wrapper

Setting up the StandardContext mapper

Request processing

Filters

Filter chain construction

Filter chain invocation

Request dispatcher

Obtaining a request dispatcher

Using a request dispatcher

Forwards

Includes

Wrapper classes

Wrapper class structure

Processing a forward

Including a resource

Examples

Servlets

Declaration

ForwardingServlet.java

Static resources

IncludingServlet.java

TemplateServlet.java

Summary

11. The Manager Component

Session propagation mechanisms

Cookies

URL rewriting

Session

Session identifiers

Session attributes

Session lifetime

Session creation and access

Session validity

Session expiry

Session cleanup

Session lifecycle events

Object binding events

Session lifecycle events

Attribute change events

Session migration events

Session serialization

Serialization

Versioning

Class loading

Serialization in a StandardSession

Session multi threading

Manager

ManagerBase

Session security

Employing a cryptographic Random Number Generator

Generating a session identifier of adequate length

Using an inactive timeout to expire sessions

Generating a session identifier

Session construction

Background processing

Other methods

StandardManager

Manager element attributes

Session identifier generation attributes

Session attributes

Session persistence mechanism

Persistent manager

Persisting sessions

Finding a session

Background processing

Store

FileStore

Summary

Index

Tomcat 6 Developer's Guide

Damodar Chetty

Tomcat 6 Developer's Guide

Copyright © 2009 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, Packt Publishing, nor its dealers or distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

First published: December 2009

Production Reference: 1091209

Published by Packt Publishing Ltd.

32 Lincoln Road

Olton

Birmingham, B27 6PA, UK.

ISBN 978-1-847197-28-3

www.packtpub.com

Cover Image by Vinayak Chittar (<vinayak.chittar@gmail.com>)

Credits

Author

Damodar Chetty

Reviewers

David O'Meara

Michael Besosa

Karl Espe

Alok Gupta

Arun Lakkakula

Giridhar Reddy

David Gordhamer

Chad LaVigne

Vladan Pulec

Raghu Ramakrishnan

Dan Syrstad

Acquisition Editor

Sarah Cullington

Development Editor

Swapna Verlekar

Technical Editor

Akash Johari

Copy Editor

Leonard D'Silva

Editorial Team Leader

Akshara Aware

Project Team Leader

Manjiri Nadkarni

Project Coordinator

Leena Purkait

Indexer

Hemangini Bari

Monica Ajmera

Proofreader

Jeff Orloff

Graphics

Nilesh R. Mohite

Production Coordinator

Shantanu Zagade

Cover Work

Shantanu Zagade

About the author

Damodar Chetty is a lifelong programmer with almost two decades in the computer software industry. During that period he’s worked in a variety of languages, tools, and technologies, journeying from programming in assembly language, all the way through to Java and Ruby, making some interesting side trips along the way.

He has also been fortunate to have worked in a number of Fortune 500 organizations, and to have engaged with a number of world class software engineers, all of which have helped him perfect his craft.

He is also the recipient of the US Department of Interior Information Technology award for 2001.

Damodar has an undergraduate degree in Electronics & Telecommunications Engineering from the University of Bombay and graduate degrees in Management Sciences from the University of Goa and in Computer Engineering from the University of Minnesota.

He is the owner of Software Engineering Solutions, Inc., a provider of Java EE web development consulting services. He is an avid blogger on his web site at www.swengsol.com.

He currently lives in Woodbury, Minnesota with his wife Devi, his children Ashwin and Anita, and a passion for photography.

Acknowledgement

No book is the product of just the author. He just happens to be the one with his name on the cover.

A number of people contributed to the success of this book, and it would take more space than I have to thank each one individually.

A special shout out goes to Sarah Cullington, my editor, who is the reason that this book exists. Thank you Sarah for believing in me and for being a wonderful guide through this process. Thank you also to the entire Packt Publishing team for working so diligently to help bring out a high quality product.

No words can express my gratitude to my amazing development cohort, with whom it is my privilege to work. In particular, thanks are due to Michael Besosa, Karl Espe, David Gordhamer, Alok Gupta, Arun Lakkakula, Chad LaVigne, Vladan Pulec, Raghu Ramakrishnan, Giridhar Reddy, and Dan Syrstad. Your encouragement and support were invaluable to me. You guys are the best!

I must also thank the talented team of developers who have contributed to the Apache Tomcat project. This product is truly an engineering marvel, and it was an instructive experience to rummage through its source. It is a credit to this team that the Tomcat mailing lists are not just civil places, but are also full of interesting tips and tricks, and well worth a visit.

Finally, I'd like to acknowledge Joginder Nahil, who provided me with an early taste for the written word.

About the reviewers

David O'Meara is an experienced developer, architect, and technical manager with over 10 years based in Australia and the USA. Primarily focusing on the Java language and related technologies, his experience is mainly based on web, distributed, and integration projects.

He has previously worked on many business domains, but currently devotes the bulk of his time in the maintenance and programming of highly adaptive, semi-autonomous, self-aware bipedal hominids, also known as child raising. The rest of his spare time is often spent answering questions on the JavaRanch, moderating on DZone, or working on open source projects.

Michael Besosa is a Principal Architect at Pearson VUE, Inc.

Karl Espe and Alok Gupta are Web Engineering Leads at Pearson VUE, Inc.

Arun Lakkakula and Giridhar Reddy are Senior Web Software Developers at Pearson VUE, Inc.

David Gordhamer is a Web Software Developer at Pearson VUE, Inc.

Chad LaVigne, Vladan Pulec, Raghu Ramakrishnan, and Dan Syrstad are web development consultants based in Minnesota.

This book is dedicated to:

My wife Devi, every day with you is a joy and a blessing

My children, Ashwin and Anita, you are the lights of my world

My parents, Nagarathnam and Shanmugam, who taught me all that is important

This book would not have been possible without your love and understanding.

Thank you from the bottom of my heart.

Preface

Current books on Tomcat are primarily focused on the application deployer or administrator. As a result, they invariably focus on the issues related to managing a Tomcat installation, configuring the runtime environment, and on deploying web applications.

On the other hand, while books on servlet programming are targeted at Java web developers, they often provide a container-agnostic view of the servlet specification. Tomcat is often a bit player in these books and has very few speaking lines.

This book fills the void between these two approaches.

It will take you on a guided tour of a living implementation of an industrial-strength servlet container.

Along the way, you will learn how various elements of the Servlet 2.5 specification as well as how the HTTP RFCs are implemented.

By the end of your journey, you will have acquired specialist grade skills in a range of technologies that contribute to the arena of Java server-side development.

This book intended to provide Tomcat administrators, deployers, and developers an introduction into the internal workings of the Tomcat servlet container.

At the same time, it provides Java web programmers with a deep appreciation of the Servlet API by exploring its reference implementation—the Tomcat container.

While this book provides you with the conceptual background of all that is necessary to take your skills to the next level, it assumes that the reader has a general understanding of the Java programming language and Java web programming.

What this book covers

Chapter 1—Introduction to Tomcat introduces you to the Tomcat container and provides you with the tools necessary to begin to take it apart. The key objective of this chapter is to allow you to make a current source distribution of Tomcat active in a development environment (Eclipse Galileo) so that you can trace the path that a request takes through the container's code.

Chapter 2—Servlet API Overview provides the prerequisite information necessary to navigate the remainder of the book. It describes the Java Enterprise Edition Platform, the HTTP protocol, and the Servlet API, and serves as a refresher for those who are already familiar with Java EE web development.

Chapter 3—Servlet Container Overview introduces the reader to the Tomcat container. This is the 10,000 foot overview of the container that provides a backdrop to the chapters that follow. All the components of Tomcat are described with just enough detail, so as not to overwhelm the reader with too much information, too early in the process.

Chapter 4—Starting up Tomcat takes a closer look at the startup process for Tomcat. This is also where you will be first introduced to the Apache Digester project—a key component that we will revisit in later chapters. The chapter ends with an example that demonstrates how a web application can be deployed to a dissected Tomcat container living within an Integrated Development Environment.

Chapter 5—The Server and Service Components discusses the Server component and investigates one of its key services—an implementation of the Java Naming and Directory Interface (JNDI) API. We are also introduced to the Lifecycle interface that almost every component within Tomcat implements in order to participate in a standardized event based listener mechanism. To show JNDI in action, our example considers connecting to a MySQL database to retrieve data.

Chapter 6—The Connector Component introduces our first Tomcat luminary, the Coyote Connector. We take a closer look at the standard Java I/O implementation of an HTTP connector. In this chapter, we get a closer look at socket programming, advanced elements of the HTTP protocol, and the internals of the request processing mechanism.

Chapter 7—The Engine Component describes the first request processing 'Container' within Tomcat and gives us an inkling of things to come. We are also introduced to the Pipeline and its Valves, which are the standard request processing mechanism for Tomcat components.

Chapter 8—The Host Component discusses the Tomcat implementation of a Virtual Host. This is the key component responsible for the deployment of web application contexts, as well as for the error page mechanism.

Chapter 9—The Context Component is at the central core of this book. You get an up-close-and-personal look at how a Context is configured, how it accesses its resources, and how it implements its class loading magic.

Chapter 10—The Wrapper Component takes us to the workhorse of the Tomcat component hierarchy. This component wraps an actual servlet, and as a result is close to a web developer's heart. In addition to reviewing the mapping rules dictated by the Servlet API, we also look at the implementation of servlet filters and the request dispatcher mechanism.

Chapter 11—The Session Component discusses how sessions are implemented in Tomcat to enable stateful behavior over the stateless HTTP protocol. In addition to looking at some core concepts, such as Java serialization and entropy gathering for random number generation, we look at the standard memory based session implementation, as well as an implementation that uses files to persist sessions.

What you need for this book

You should have knowledge of the Java programming language and web development on the Java platform.

Who this book is for

This book is written for the following classes of readers:

Web developers who want to take their programming skills to the next level.

Server administrators who want to get a better understanding of the software they manage.

Hobbyists who want to contribute to the Tomcat project.

Academics and students who want to look at a production grade web server and servlet container from the inside out.

Open source auditors who want to understand whether a particular open source project passes audit for usage in highly secure environments or not.

Developers who want to understand how to architect high availability, high performance software.

Conventions

In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning.

Code words in text are shown as follows: You will end up with a file named jdk-6u14-windows-i586.exe on your workstation.

A block of code will be set as follows:

[request-method] [/path/to/resource] [HTTP protocol version]

[request-header=value]+

[blank-line to indicate the end of the request headers]

[POST:request-payload]

When we wish to draw your attention to a particular part of a code block, the relevant lines or items will be shown in bold:

1.0 encoding=UTF-8?>

false reloadable = true privileged = false>

contactsTableCaption global = contactsCaption type = java.lang.String/>

jdbc/swengsolDB global = jdbc/swengsolDB type = javax.sql.DataSource/>

Any command-line input or output is written as follows:

mysql> help contents;

New terms and important words are shown in bold. Words that you see on the screen, in menus or dialog boxes for example, appear in our text like this: Once the installation has completed, run the MySQL Server Instance Configuration Wizard.

Note

Warnings or important notes appear in a box like this.

Note

Tips and tricks appear like this.

Reader feedback

Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of.

To send us general feedback, simply drop an email to <feedback@packtpub.com>, and mention the book title in the subject of your message.

If there is a book that you need and would like to see us publish, please send us a note in the SUGGEST A TITLE form on www.packtpub.com or email .

If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide on www.packtpub.com/authors.

Customer support

Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.

Note

Downloading the example code for the book

Visit http://www.packtpub.com/files/code/7283_Code.zip to directly download the example code.

The downloadable files contain instructions on how to use them.