Tomcat 6.

0
Application Developer's Guide
Installation
Installation
In order to use Tomcat 6 for developing web applications, you must first install it (and the
software it depends on). The required steps are outlined in the following subsections.
JDK
Tomcat 6.0 was designed to run on !"# $.0.
%ompatible &'s for many platforms (or lin(s to where they can be found) are available at
http)**+ava.sun.com*+!se*.
Tomcat
,inary downloads of the Tomcat server are available from http)**tomcat.apache.org*download-
60.cgi. This manual assumes you are using the most recent release of Tomcat 6. &etailed
instructions for downloading and installing Tomcat 6 are available here.
In the remainder of this manual, e.ample shell scripts assume that you have set an environment
variable CATALINA_HOME that contains the pathname to the directory in which Tomcat 6 has
been installed. /ptionally, if Tomcat has been configured for multiple instances, each instance
will have its own CATALINA_BASE configured.
Ant
,inary downloads of the Ant build tool are available from
http)**ant.apache.org*bindownload.cgi. This manual assumes you are using 0nt 1.2 or later. The
instructions should also be compatible with later versions, but this has not been tested.
&ownload and install 0nt from the distribution directory mentioned above. Then, add the bin
directory of the 0nt distribution to your PATH environment variable, following the standard
practices for your operating system platform. /nce you have done this, you will be able to
e.ecute the ant shell command directly.
CVS
,esides the required tools described above, you are strongly encouraged to download and install
a source code control system, such as the Concurrent Version System (%3"), to maintain
historical versions of the source files that ma(e up your web application. ,esides the server, you
will also need appropriate client tools to chec( out source code files, and chec( in modified
versions.
&etailed instructions for installing and using source code control applications is beyond the
scope of this manual. 4owever, %3" server and client tools for many platforms (along with
documentation) can be downloaded from http)**www.cvshome.org.
Deployment
Table of Contents
Background
Standard Directory Layout
Shared Library Files
Web Application Deployment Descriptor
Tomcat Context Descriptor
Deployment With Tomcat 6
Background
,efore describing how to organi5e your source code directories, it is useful to e.amine the
runtime organi5ation of a web application. 6rior to the "ervlet 06I "pecification, version !.!,
there was little consistency between server platforms. 4owever, servers that conform to the !.!
(or later) specification are required to accept a Web Application Archive in a standard format,
which is discussed further below.
0 web application is defined as a hierarchy of directories and files in a standard layout. "uch a
hierarchy can be accessed in its 7unpac(ed7 form, where each directory and file e.ists in the
filesystem separately, or in a 7pac(ed7 form (nown as a 8eb 09chive, or 809 file. The former
format is more useful during development, while the latter is used when you distribute your
application to be installed.
The top-level directory of your web application hierarchy is also the document root of your
application. 4ere, you will place the 4T:; files and "6 pages that comprise your application<s
user interface. 8hen the system administrator deploys your application into a particular server,
he or she assigns a context path to your application (a later section of this manual describes
deployment on Tomcat). Thus, if the system administrator assigns your application to the conte.t
path /catalog, then a request =9I referring to /catalog/index.html will retrieve the
index.html file from your document root.
Standard Directory Layout
To facilitate creation of a 8eb 0pplication 0rchive file in the required format, it is convenient to
arrange the 7e.ecutable7 files of your web application (that is, the files that Tomcat actually uses
when e.ecuting your app) in the same organi5ation as required by the 809 format itself. To do
this, you will end up with the following contents in your application<s 7document root7 directory)
*.html, *.jsp, etc. The !T"L and #S$ pages% along &ith other 'iles that must be (isible
to the client bro&ser )such as #a(aScript% stylesheet 'iles% and images* 'or your
application+ ,n larger applications you may choose to di(ide these 'iles into a
subdirectory hierarchy% but 'or smaller apps% it is generally much simpler to maintain only
a single directory 'or these 'iles+
/WEB-INF/web.xml The Web Application Deployment Descriptor 'or your application+
This is an -"L 'ile describing the ser(lets and other components that make up your
application% along &ith any initiali.ation parameters and containermanaged security
constraints that you &ant the ser(er to en'orce 'or you+ This 'ile is discussed in more
detail in the 'ollo&ing subsection+
/WEB-INF/classes/ This directory contains any #a(a class 'iles )and associated
resources* re/uired 'or your application% including both ser(let and nonser(let classes%
that are not combined into #A0 'iles+ ,' your classes are organi.ed into #a(a packages%
you must re'lect this in the directory hierarchy under /WEBIN!/cla""e"/+ For example%
a #a(a class named com.m#com$an#.m#$ac%age.M#Se&'let &ould need to be stored in
a 'ile named /WEBIN!/cla""e"/com/m#com$an#/m#$ac%age/M#Se&'let.cla""+
/WEB-INF/lib/ This directory contains #A0 'iles that contain #a(a class 'iles )and
associated resources* re/uired 'or your application% such as third party class libraries or
#DBC dri(ers+
8hen you install an application into Tomcat (or any other !.!*!.>-compatible server), the classes
in the WEBIN!/cla""e"/ directory, as well as all classes in 09 files found in the WEB
IN!/lib/ directory, are made visible to other classes within your particular web application.
Thus, if you include all of the required library classes in one of these places (be sure to chec(
licenses for redistribution rights for any third party libraries you utili5e), you will simplify the
installation of your web application -- no ad+ustment to the system class path (or installation of
global library files in your server) will be necessary.
:uch of this information was e.tracted from %hapter ? of the "ervlet 06I "pecification, version
!.>, which you should consult for more details.
Shared Library iles
;i(e most servlet containers, Tomcat 6 also supports mechanisms to install library 09 files (or
unpac(ed classes) once, and ma(e them visible to all installed web applications (without having
to be included inside the web application itself. The details of how Tomcat locates and shares
such classes are described in the %lass ;oader 4/8-T/ documentation. The location commonly
used within a Tomcat 6 installation for shared code is $CATALINA_HOME/li. 09 files
placed here are visible both to web applications and internal Tomcat code. This is a good place to
put &,% drivers that are required for both your application or internal Tomcat use (such as for a
&,%9ealm).
/ut of the bo., a standard Tomcat 6 installation includes a variety of pre-installed shared library
files, including)
The Servlet 2.5 and JSP 2.1 A$,s that are 'undamental to &riting ser(lets and
#a(aSer(er $ages+
An XML Parser compliant &ith the #A-$ )(ersion 1+2* A$,s% so your application can
per'orm D3"based or SA-based processing o' -"L documents+
!eb A""lication De"loyment Descri"tor
0s mentioned above, the /WEBIN!/(eb.xml file contains the 8eb 0pplication &eployment
&escriptor for your application. 0s the filename e.tension implies, this file is an @:;
document, and defines everything about your application that a server needs to (now (e.cept the
context path, which is assigned by the system administrator when the application is deployed).
The complete synta. and semantics for the deployment descriptor is defined in %hapter 1> of the
"ervlet 06I "pecification, version !.>. /ver time, it is e.pected that development tools will be
provided that create and edit the deployment descriptor for you. In the meantime, to provide a
starting point, a basic web..ml file is provided. This file includes comments that describe the
purpose of each included element.
NOTE - The "ervlet "pecification includes a &ocument Type &escriptor (&T&) for the web
application deployment descriptor, and Tomcat 6 enforces the rules defined here when
processing your application<s /WEBIN!/(eb.xml file. In particular, you must enter your
descriptor elements (such as )*ilte&+, )"e&'let+, and )"e&'letma$$ing+ in the order
defined by the &T& (see "ection 1>.>).
Tomcat Conte#t Descri"tor
0 *:#T0-IAB*conte.t..ml file can be used to define Tomcat specific configuration options,
such as loggers, data sources, session manager configuration and more. This @:; file must
contain one %onte.t element, which will be considered as if it was the child of the 4ost element
corresponding to the 4ost to which the The Tomcat configuration documentation contains
information on the %onte.t element.
De"loyment !ith Tomcat $
The description below uses the variable name $CATALINA_BAS to re!er the base director"
a#ainst which most relative paths are resolved$ I! "ou have not con!i#ured Tomcat % !or multiple
instances b" settin# a CATALINA_BAS director"& then $CATALINA_BAS will be set to the
value o! $CATALINA_'()& the director" into which "ou have installed Tomcat %$
In order to be e.ecuted, a web application must be deployed on a servlet container. This is true
even during development. 8e will describe using Tomcat 6 to provide the e.ecution
environment. 0 web application can be deployed in Tomcat by one of the following approaches)
Copy unpace! !irectory "ierarc"y into a sub!irectory in !irectory
$CATALINA_BASE/webapps/+ Tomcat &ill assign a context path to your application based
on the subdirectory name you choose+ We &ill use this techni/ue in the b,ild.xml 'ile
that &e construct% because it is the /uickest and easiest approach during de(elopment+
Be sure to restart Tomcat a'ter installing or updating your application+
!rails an" Tomcat# $ Deployment Notes
Things have been busy, and I havenCt had the time to devote to writing updates on either the
%addy, or my wor( in Drails. ,ut enough complaining, to pass the time until I can get some
more quality content here, I wanted to share this little gem that too( me entirely too long to
figure out.
I wanted to be able to deploy my grails applications to a sub conte.t, or sub directory of the root
of my site. This way I could leave my blog at the root of my domain, and categori5e my grails
apps a bit. Ta(e the following e.ample. "uppose I wanted to deploy a bunch of e.ample grails
apps in a subdirectory named Ee.amplesF off of the root of my web host. "omething li(e
http)**GyourserverH*e.amples*Gyour-app-nameH. This is how I was able to finally accomplish it.
Deploy to a Tomcat Su%Conte&t
If youCre a Tomcat guru this is all going to seem elementary, and it is, but it was superbly
difficult for me to mine the information I needed from the web, so ICm sharing what ICve learned
here. If, on the other hand, youCre a Tomcat newbie li(e me, you hopefully have a running
instance of the Tomcat service. If you donCt there are a number of great tutorials, including the
official installation guide.
:ost of the stuff that youCll read out there says that to deploy your grails app, you +ust upload
your I.war file to the Tomcat EwebappsF directory and youCre in business. This is true, but of
course when you do this, you +ust end up with a =9; that loo(s li(e
http)**GyourserverH)J0J0*Gyour-app-nameH. Aow, this is fine if you only intend to deploy a few
apps and you dont mind that application being at the root for your domain*server name. ,ut
weCre trying to put our apps in a sub directory of our site, off of the root.
:y first instinct to accomplish this was to use some of the properties of the grails app itself, and
I found many e.amples which recommended this. "o, I happily set my app.conte.t in
application.properties to the path I wanted.
m%di& $ /"&'/tomcat(eba$$"/exam$le"/M#Exam$leA$$
This wor(s great when I do a grails run-app, I get the app deployed to
http)**localhost)J0J0*e.amples*:y#.ample0pp +ust li(e I wanted. ,ut, when I create a war and
toss it in my Tomcat webapps directory, I still get the same old behavior of the application being
deployed to the root of Tomcat with the same name as the war file. "o how the hec( do I deploy
my war into a sub directory of my Tomcat siteKL
The secret lies in not simply dumping your war file into an e.isting Econte.tF for Tomcat, but
instead creating your own, and pointing that conte.t to your war file. The first step toward this is
to prepare a place for our webapp directories, outside of the Tomcat root webapp directory. I
choose *srv*tomcat-webapps but youCre obviously welcome to put this anywhere you li(e. "o
letCs create the directory where weCre going to deploy our first e.ample app.
m%di& $ /"&'/tomcat(eba$$"/exam$le"/M#Exam$leA$$
Aow, we need to find the %atalina configuration directory for our Tomcat deployment. /n
=buntu, which is the environment ICm using, this is at *etc*tomcat6*%atalina*localhost. 8hat
youCll find there, are a number of @:; files each one describes a Econte.tF. Mou can define
sub-conte.ts by using a special synta. in the filename which is +ust barely mentioned in passing
in the Tomcat docs. Mou can set a multi level conte.t name by using the N character. "o lets
create a new sub-conte.t for our e.ample app at the correct path.
cd /etc/tomcat./Catalina/localho"t
'im exam$le"/M#Exam$leA$$.xml
Aow we need to add the content to this conte.t file which will tell Tomcat where to find the
applications files. 9emember bac( when we created a new directory for our tomcat webapps, this
is where weCll use it.
exam$le"/M#Exam$leA$$.xml
)0xml 'e&"ion123.42 encoding125T!620+
)context anti&e"o,&celoc%ing12*al"e2
docba"e12/"&'/tomcat(eba$$"/exam$le"/M#Exam$leA$$2
$ath12/exam$le"/M#Exam$leA$$2 $&i'ileged12t&,e2+
Aow if you restart Tomcat, and un5ip your war file to *srv*tomcat-
webapps*e.amples*:y#.ample0pp you should be able to navigate to
htt$7//)#o,&"e&'e&+76464/exam$le"/M#Exam$leA$$ and see your applicationL
How to Externalize Your Grails Coni!uration "i#e a $roessional
Drails docs go a long way towards being the only materials you need to learn how to use Drails.
=nfortunately, it can miss a few things that are common use cases.
In any real world production app, you donCt manage your configuration from within your 809
file. 4ow do you have a configuration file deployed out to your production server beside your
809 fileK
:ost of the posts out there about e.ternal configuration all tal( about hard coding e.ternal
config locations into a variable li(e so
grails+con'ig+locations 4 5 6'ile789user!ome:;89app<ame:con'+properties6=
8ell, that suc(s. That is assuming, again, more about production then you really can afford. The
configuration of the production system, isnCt up to the developer. ItCs up to the 9elease :anager
or "ystem 0dmin or a whole team of people besides you. 9ather than force them into
accommodating you, the programmer, you need to ma(e it easy for them to specify
840T#3#9 T4# B=%' T4#M 80AT.
"o here it is, place the following in %onfig.groovy)
de* EN8_NAME 1 2APPNAME_CON!I92
i*:;g&ail".con*ig.location << ;:g&ail".con*ig.location in"tanceo*
Li"t== >
g&ail".con*ig.location 1 ?@
A
i*:S#"tem.geten':EN8_NAME== >
$&intln 2Incl,ding con*ig,&ation *ile "$eci*ied in en'i&onment7 2 B
S#"tem.geten':EN8_NAME=C
g&ail".con*ig.location )) 2*ile72 B S#"tem.geten':EN8_NAME=
A el"e i*:S#"tem.getP&o$e&t#:EN8_NAME== >
$&intln 2Incl,ding con*ig,&ation *ile "$eci*ied on command line7 2 B
S#"tem.getP&o$e&t#:EN8_NAME=C
g&ail".con*ig.location )) 2*ile72 B S#"tem.getP&o$e&t#:EN8_NAME=
A el"e >
$&intln 2No exte&nal con*ig,&ation *ile de*ined.2
A
The (ey points in this method that are not in the docs or blogs to come before me)
,t actually &orks+ ,t appears some de(s don>t bother testing their methods be'ore posting
the code+ ?ou ha(e to initiali.e the grails+con'ig+location as a list i' it isn>t already+ And it
is grails+con'ig+location+ <ot% location5s=+
This method is 'lexible% it allo&s either the con'ig location to be speci'ied in the 3S
@n(ironment or on the command line+ ?ou don>t kno& &hat is a(ailable to you in
productionA
$erhaps the most important7 ,t tells the person starting up the application% &hat
con'iguration the app &ill be using+ There is nothing more 'rustrating than being in the
heat o' a deployment% already stretched to the edge o' your maintenance &indo&% and
being unable to 'ind out &hy your con'iguration changes aren>t taking a''ect+
,t uses println statements instead o' log statements+ ,n my usage% logging &asn>t setup
yet so println it &as+ ,>m sure &ith some 'iddling those could be replaced &ith log
statements+
,' , sound harsh% it>s because ,>(e Bust dealt &ith another stupid Crails issue that should
be a no brainer+ And i' not in the o''icial documentation% the D or E blog posts and a
Stack 3(er'lo& /uestion about this should ha(e pro(ided the C300@CT FFCG,<C
A<SW@0+
mi'e) :i(e 8ille is an opinionated computer programmer living in :ichigan with his wife and
two (ids.