Professional Apache Tomcat 5

Professional Apache Tomcat 5

Vivek Chopra

Amit Bakore

Jon Eaves

Ben Galbraith

Sing Li

Chanoch Wiggers

a 559028 FM.qxd 4/22/04 3:54 PM Page i

a 559028 FM.qxd 4/22/04 3:54 PM Page vi

Professional Apache Tomcat 5

Vivek Chopra

Amit Bakore

Jon Eaves

Ben Galbraith

Sing Li

Chanoch Wiggers

a 559028 FM.qxd 4/22/04 3:54 PM Page i

Professional Apache Tomcat 5

Published by

Wiley Publishing, Inc.

10475 Crosspoint Boulevard

Indianapolis, IN 46256

www.wiley.com

Copyright © 2004 by Wiley Publishing, Inc., Indianapolis, Indiana

Published by Wiley Publishing, Inc., Indianapolis, Indiana

Published simultaneously in Canada

Library of Congress Card Number: 2004103742

ISBN: 0-7645-5902-8

Manufactured in the United States of America

10 9 8 7 6 5 4 3 2 1

1B/RR/QV/QU/IN

No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by

any means, electronic, mechanical, photocopying, recording, scanning or otherwise, except as permitted

under Sections 107 or 108 of the 1976 United States Copyright Act, without either the prior written permis￾sion of the Publisher, or authorization through payment of the appropriate per-copy fee to the Copyright

Clearance Center, 222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400, fax (978) 646-8600. Requests to

the Publisher for permission should be addressed to the Legal Department, Wiley Publishing, Inc., 10475

Crosspoint Blvd., Indianapolis, IN 46256, (317) 572-3447, fax (317) 572-4447, E-Mail: permcoordinator@

wiley.com.

LIMIT OF LIABILITY/DISCLAIMER OF WARRANTY: THE PUBLISHER AND THE AUTHOR MAKE

NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE ACCURACY OR COMPLETENESS

OF THE CONTENTS OF THIS WORK AND SPECIFICALLY DISCLAIM ALL WARRANTIES, INCLUDING

WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE. NO WARRANTY

MAY BE CREATED OR EXTENDED BY SALES OR PROMOTIONAL MATERIALS. THE ADVICE AND

STRATEGIES CONTAINED HEREIN MAY NOT BE SUITABLE FOR EVERY SITUATION. THIS WORK IS

SOLD WITH THE UNDERSTANDING THAT THE PUBLISHER IS NOT ENGAGED IN RENDERING

LEGAL, ACCOUNTING, OR OTHER PROFESSIONAL SERVICES. IF PROFESSIONAL ASSISTANCE IS

REQUIRED, THE SERVICES OF A COMPETENT PROFESSIONAL PERSON SHOULD BE SOUGHT.

NEITHER THE PUBLISHER NOR THE AUTHOR SHALL BE LIABLE FOR DAMAGES ARISING HERE￾FROM. THE FACT THAT AN ORGANIZATION OR WEB SITE IS REFERRED TO IN THIS WORK AS A

CITATION AND/OR A POTENTIAL SOURCE OF FURTHER INFORMATION DOES NOT MEAN THAT

THE AUTHOR OR THE PUBLISHER ENDORSES THE INFORMATION THE ORGANIZATION OR WEB

SITE MAY PROVIDE OR RECOMMENDATIONS IT MAY MAKE. FURTHER, READERS SHOULD BE

AWARE THAT INTERNET WEB SITES LISTED IN THIS WORK MAY HAVE CHANGED OR DISAP￾PEARED BETWEEN WHEN THIS WORK WAS WRITTEN AND WHEN IT IS READ.

For general information on our other products and services or to obtain technical support, please contact our

Customer Care Department within the U.S. at (800) 762-2974, outside the U.S. at (317) 572-3993 or fax (317)

572-4002.

Wiley also publishes its books in a variety of electronic formats. Some content that appears in print may not

be available in electronic books.

Trademarks: Wiley, the Wiley Publishing logo, Wrox, the Wrox logo, and Programmer to Programmer are

trademarks or registered trademarks of John Wiley & Sons, Inc., and/or its affiliates. All other trademarks

are the property of their respective owners. Wiley Publishing, Inc., is not associated with any product or

vendor mentioned in this book.

a 559028 FM.qxd 4/22/04 3:54 PM Page ii

About the Authors

Vivek Chopra

Vivek Chopra has over nine years of experience as a software developer, architect, and team lead, and is

currently working on Web Services, J2EE, and middleware technologies. He has worked and consulted

at a number of Silicon Valley companies (including Hewlett-Packard, Sun, and currently Sony) and

startups. He actively writes about technology and has co-authored half a dozen books on topics such as

Apache/open-source software, XML, and Web services. He is also a committer for UDDI4J, an open￾source Java API for UDDI. His other areas of experience and interest include compilers, middleware,

clustering, GNU/Linux, RFID systems, and mobile computing.

Sing Li

Sing Li, bitten by the microcomputer bug since 1978, has grown up with the Microprocessor Age. His

first personal computer was a $99 do-it-yourself Netronics COSMIC ELF computer with 256 bytes of

memory, mail-ordered from the back pages of Popular Electronics magazine. Currently, Sing is a consultant,

system designer, open-source software contributor, and freelance writer specializing in Java technology, as

well as embedded and distributed systems architecture. He writes for several popular technical journals

and e-zines, and is the creator of the “Internet Global Phone,” one of the very first Internet telephones

available. He has authored and co-authored a number of books across diverse technical topics, including

Tomcat, JSP, Servlets, XML, Jini, and JXTA.

Ben Galbraith

Ben Galbraith was introduced to Java in 1999, and has since become something of a Java enthusiast. He

has written dozens of Java/J2EE applications for numerous clients, and has built his share of Web sites.

He actively tinkers on several open-source projects and participates in the Java Community Process. He

has also co-authored a gaggle of books on various Java/XML-related topics, including the one you’re

holding now. He is president of the Utah Java User’s Group (www.ujug.org) and Director of Software

Development for Amirsys (www.amirsys.com).

Jon Eaves

Jon Eaves is the Chief Technology Officer of ThoughtWorks Australia and has more than 15 years of soft￾ware development experience in a wide variety of application domains and languages. He can be

reached at [email protected].

a 559028 FM.qxd 4/22/04 3:54 PM Page iii

Amit Bakore

Amit Bakore is a Sun-certified Web component developer and Java programmer. He works at Veritas

Software R&D center, Pune (India). Earlier, he was a part of the Server Technologies group at Oracle,

Bangalore (India), as a Senior Member Technical Staff. He has been working primarily on Java, J2EE,

XML, and Linux. His areas of interest include open-source technologies and satellite-launching vehicles.

He can be reached at [email protected]. Amit dedicates this work to his parents, Dr.

Ramkrishna and Sau. Vaijayanti.

Chanoch Wiggers

Chanoch Wiggers is a senior developer with Kiwi DMD, U.K., programming with J2EE and VB. He

previously worked as a technical architect with Wrox Press, editing, architecting, and contributing to

Java books.

a 559028 FM.qxd 4/22/04 3:54 PM Page iv

Credits

Acquisitions Editor

Robert Elliott

Development Editor

Kevin Shafer

Production Editor

William A. Barton

Copy Editor

Luann Rouff

Editorial Manager

Kathryn A. Malm

Vice President & Executive Group Publisher

Richard Swadley

Vice President and Executive Publisher

Bob Ipsen

Vice President and Publisher

Joseph B. Wikert

Executive Editorial Director

Mary Bednarek

Project Coordinator

Erin Smith

Graphics and Production Specialists

Beth Brooks, Sean Decker, Lauren Goddard,

Shelley Norris, Lynsey Osborne

Quality Control Technician

Carl W. Pierce

Brian H. Walls

Media Development Specialist

Travis Silvers

Proofreading and Indexing

TECHBOOKS Production Services

a 559028 FM.qxd 4/22/04 3:54 PM Page v

a 559028 FM.qxd 4/22/04 3:54 PM Page vi

Acknowledgments

The behind-the-scenes work undertaken to create this book was as critical as writing the book itself. For

this, we would like to acknowledge the efforts of our editorial team: Bob Elliot (our executive editor),

Kathryn Malm (our editorial manager), and Kevin Shafer (our development editor). In addition, we

certainly couldn’t have done this without the expert help of Rupert Jones, our technical reviewer.

We would also like to acknowledge our respective families for all the support they gave us in this project.

a 559028 FM.qxd 4/22/04 3:54 PM Page vii

a 559028 FM.qxd 4/22/04 3:54 PM Page viii

Contents

Acknowledgments vii

Introduction xxi

Chapter 1: Apache and Jakarta Tomcat 1

Humble Beginnings: The Apache Project 2

The Apache Software Foundation 3

The Jakarta Project 3

Tomcat 4

Other Jakarta Subprojects 4

Distributing Tomcat 5

Comparison with Other Licenses 6

GPL 6

LGPL 7

Other Licenses 7

The Big Picture: J2EE 7

Java APIs 7

The J2EE APIs 8

J2EE Application Servers 9

“Agree on Standards, Compete on Implementation” 10

Tomcat and Application Servers 10

Tomcat and Web Servers 11

Summary 12

Chapter 2: JSP and Servlets 13

First Came CGI 14

Then Servlets Were Born 14

Servlet Containers 15

Accessing Servlets 16

And on to JSPs . . . 18

JSP Tag Libraries 21

Web Application Architecture 24

Java Site Architecture 25

Summary 27

a 559028 FM.qxd 4/22/04 3:54 PM Page ix

x

Contents

Chapter 3: Tomcat Installation 29

Installing the Java Virtual Machine 29

Installing the Sun JVM on Windows 29

Installing Tomcat 33

Tomcat Windows Installer 33

Finishing the Installation 34

Setting Environment Variables 34

Testing the Installation 34

Installing Tomcat on Windows Using the ZIP File 39

Installing Tomcat on Linux 40

The Tomcat Installation Directory 41

The bin Directory 41

The shared Directory 42

The common Directory 42

The conf Directory 42

The logs Directory 42

The server Directory 42

The webapps Directory 42

The work Directory 43

Troubleshooting and Tips 43

The Port Number Is in Use 43

Running Multiple Instances 44

A Proxy Is Blocking Access 44

Summary 44

Chapter 4: Tomcat Architecture 45

An Overview of Tomcat Architecture 45

The Server 47

The Service 47

The Remaining Classes in the Tomcat Architecture 50

Summary 50

Chapter 5: Basic Tomcat Configuration 51

Tomcat 5 Configuration Essentials 52

Tomcat 5 Web-Based Configurator 53

Enabling Access to Configurator 54

Files in $CATALINA_HOME/conf 58

Basic Server Configuration 60

Server Configuration via the Default server.xml 60

Operating Tomcat in Application Server Configuration 66

a 559028 FM.qxd 4/22/04 3:54 PM Page x

xi

Contents

Web Application Context Definitions 76

Authentication and the tomcat-users.xml File 77

The Default Deployment Descriptor – web.xml 77

How server.xml, Context Descriptors, and web.xml Work Together 81

Fine-Grained Access Control: catalina.policy 84

catalina.properties: Finer-Grained Control over Access Checks 87

Configurator Bootstrapping and the Future of Tomcat Configuration 87

A Final Word on Differentiating Between Configuration and Management 88

Summary 88

Chapter 6: Web Application Configuration 91

The Contents of a Web Application 91

Public Resources 92

The WEB-INF Directory 94

The META-INF Directory 95

The Deployment Descriptor (web.xml) 96

Servlet 2.3-Style Deployment Descriptor 97

Servlet 2.4-Style Deployment Descriptor 110

Summary 125

Chapter 7: Web Application Administration 127

Sample Web Application 128

Tomcat Manager Application 129

Enabling Access to the Manager Application 130

Manager Application Configuration 132

Tomcat Manager: Using HTTP Requests 134

List Deployed Applications 135

Installing/Deploying Applications in Tomcat 4.x 136

Deploying a New Application 136

Installing a New Application 137

Installing/Deploying Applications in Tomcat 5.x 139

Deploying a New Application Remotely 139

Reloading an Existing Application 142

Listing Available JNDI Resources 143

Listing Available Security Roles 144

Listing OS and JVM Properties 144

Stopping an Existing Application 145

Starting a Stopped Application 146

Removing an Installed Application (Tomcat 4.x Only) 146

Undeploying a Web Application 147

a 559028 FM.qxd 4/22/04 3:54 PM Page xi

xii

Contents

Displaying Session Statistics 148

Querying Tomcat Internals Using the JMX Proxy Servlet 149

Setting Tomcat Internals Using the JMX Proxy Servlet 150

Tomcat Manager: Web Interface 150

Displaying Tomcat Server Status 151

Managing Web Applications 151

Deploying a Web Application 153

Tomcat Manager: Managing Applications with Ant 154

Possible Errors 157

Security Considerations 158

Tomcat Deployer 160

Summary 160

Chapter 8: Advanced Tomcat Features 161

Valves — Interception Tomcat-Style 162

Standard Valves 162

Access Log Implementation 163

Scope of Log Files 163

Testing the Access Log Valve 165

Single Sign-On Implementation 166

Multiple Sign-On Without the Single Sign-On Valve 166

Configuring a Single Sign-On Valve 169

Restricting Access via a Request Filter 170

Remote Address Filter 170

Remote Host Filter 170

Configuring Request Filter Valves 171

Request Dumper Valve 172

Persistent Sessions 172

The Need for Persistent Sessions 172

Configuring a Persistent Session Manager 173

JNDI Resource Configuration 176

What Is JNDI? 176

Tomcat and JNDI 177

Typical Tomcat JNDI Resources 178

Configuring Resources via JNDI 179

Configuring a JDBC DataSource 182

Configuring Mail Sessions 184

a 559028 FM.qxd 4/22/04 3:54 PM Page xii