|< Free Open Study >|| |
In this appendix we'll discuss the basics of how to install and configure Tomcat 4.0, the latest version of the open source JSP and Servlet Reference Implementation.
While there are many servlet and JSP engines available (as of this writing, Sun's "Industry Momentum" page at http://java.sun.com/products/jsp/industry.html lists nearly 40), we have chosen to focus our attention on Tomcat 4.0. Tomcat is produced by the Apache Software Foundation's Jakarta project, and is freely available at http://jakarta.apache.org/tomcat/.
As Tomcat is primarily used by programmers, its open source development model is of particular benefit as it brings the developers and users close together. If you find a bug, you can fix it and submit a patch. If you need a new feature, you can write it yourself, or suggest it to the development team.
Tomcat is also the reference implementation of the JSP and Servlet specifications, version 4.0 supporting the latest Servlet 2.3 and JSP 1.2 versions. Many of the principal developers are employed by Sun Microsystems, who are investing considerable manpower into ensuring that Tomcat 4.0 provides a high-quality, robust web container with excellent performance.
The naming of Tomcat 4.0 components can be a little confusing, with the names Tomcat, Catalina, and Jasper all flying around. So, to avoid any problems with terminology:
Catalina is a servlet container - that is, an environment within which Java servlets can be hosted.
Jasper is the JSP component of Tomcat - in fact, it's just a servlet that understands how to process requests for JSP pages.
Tomcat comprises Catalina, plus Jasper, plus various extra bits and pieces including batch files for starting and stopping the server, some example web applications, and mod_webapp.
mod_webapp is the component that will allow you to connect Tomcat to the Apache web server. Catalina includes a web server of its own, but you may also wish to connect it to an external web server to take advantage of Apache's extra speed when serving static content, or to allow you to run JSP or servlet-based applications alongside applications using other server-side technologies such as PHP. As of this writing mod_webapp is in beta testing, but expect it to become stable soon. In time, connectors for other major web servers should also appear.
These steps describe installing Tomcat 4.0 on a Windows 2000 system, but the steps are pretty generic; the main differences between platforms will be the way in which environment variables are set:
You will need to install the Java 2 Platform, Standard Edition software development kit, if you have not already done so. JDK 1.3 can be downloaded from http://java.sun.com/j2se/1.3/.
Download a suitable Tomcat 4.0 binary distribution from (for example, jakarta-tomcat-4.0.1.zip from http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.0.1/bin/) and unzip it into a suitable directory.
On Windows 2000 you have the alternative of downloading a Windows installer, jakarta-tomcat-4.0.1.exe, and simply double-clicking its icon. Note that installing Tomcat 4 as a Windows service is as easy as ticking a box.
Create CATALINA_HOME and JAVA_HOME environment variables pointing to the directories where you installed the Tomcat and Java 2 SDK files. Typical values are C:\jakarta-tomcat-4.0.1 for CATALINA_HOME and C:\jdk1.3 for JAVA_HOME.
Under Windows 2000, environment variables are set using the System control panel. On the Advanced tab, click on the Environment Variables... button. In the resulting dialog box, add CATALINA_HOME and JAVA_HOME as system variables:
These environment variables allow Tomcat to locate both its own files (using CATALINA_HOME), and the Java 2 SDK components it needs, notably the Java compiler, (using JAVA_HOME).
If you are using Windows 98, environment variables are set by editing the C:\autoexec.bat file. Add the following lines:
set CATALINA_HOME=C:\jakarta-tomcat-4.0.1 set JAVA_HOME=C:\jdk1.3
Under Windows 98 you will also need to increase the environment space available, by right-clicking on your DOS prompt window, selecting Properties, going to the Memory tab, and setting the initial environment to 4096 bytes.
Editing the autoexec.bat file doesn't work the same on Windows Me as it does on Windows 95/98. First, you need to start Microsoft System Information. You can use either of the following methods:
Click Start | Programs | Accessories | System Tools | System Information.
Click Start | Run, and type msinfo32.exe in the Open box, and then click OK
To create a new entry:
Select Tools | System Configuration Utility
Click the Environment tab, and click New
Enter the appropriate information in the Variable Name and Variable Value boxes, and then click OK
To activate the new environment variable select the corresponding check box for this entry, and restart your computer.
Start Tomcat by running the startup.bat batch file (startup.sh on Unix-type systems), which can be found in the <CATALINA_HOME>\bin\ directory (in other words, the bin directory inside the directory where Tomcat is installed). Alternatively, Windows users can run Tomcat from the Start menu. Choose Start | Programs | Apache Tomcat 4 | Start Tomcat.
Tomcat will start up and print some status messages:
If you have installed Tomcat 4.0 as a service on Windows 2000, it is controlled instead by the Services utility within Administrative Tools.
We now have Tomcat 4.0 up and running, using its internal web server (on port 8080). Point your web browser at http://localhost:8080/. You should see the default Tomcat home page:
Spend some time exploring the examples and documentation provided with Tomcat.
To shut down Tomcat, run the shutdown.bat batch file (shutdown.sh on Unix-type systems), again from the <CATALINA_HOME>\bin\ directory. Again, Windows users can accomplish the same task from the Start menu. Choose Start | Programs | Apache Tomcat 4 | Stop Tomcat.
Looking inside our Tomcat installation directory we find a few text files, and various directories:
Contains Windows batch files and Unix shell scripts for starting and stopping Tomcat, and for other purposes, together with the bootstrap.jar JAR file needed for the first stage of starting Tomcat.
Not created by default, but if it exists any .class files it contains will be visible to all web applications.
Contains Java code needed by all parts of Tomcat: JAR files in the common\lib\ directory, and .class files in common\classes\. Notable among the JAR files is servlet.jar, which contains the classes defined by the Servlet 2.3 and JSP 1.2 specifications. You will need to have servlet.jar listed in your CLASSPATH environment variable when compiling classes (for example, servlets) that use these APIs.
Contains Tomcat's configuration files, notably server.xml (dealt with in the Tomcat 4.0 Configuration section below) and the server-wide web.xml.
Note that settings in the server-wide web.xml file apply to the whole server, but that this behavior is not mandated by the Servlet specification. Applications making use of it will not be portable to other servlet containers.
Populated with various JAR files required by web applications, including parts of the JSP engine. You can add your own JAR files here and they will be visible to all web applications.
Contains Tomcat's log files. Logging is configured in server.xml.
Contains the files comprising Catalina, and other required libraries: JAR files in server\lib\, and .class files in server\classes\.
Contains the source code for Tomcat, along with the documentation (interspersed with the source code).
The location where Tomcat looks for web applications to deploy. Any WAR file placed here, or any expanded web application directory structure stored within the directory, will automatically be deployed when Tomcat starts up.
The URL path under which the application is deployed will correspond to the name of the WAR file or directory; for example, if you place a myapplication.war file or a myapplication directory within webapps, Tomcat will automatically deploy it as http://localhost:8080/myapplication/.
The automatic deployment settings may not suit your application, in which case you may prefer to store the application outside the webapps\ directory and configure it as desired using server.xml.
Used by Tomcat to store temporary files, notably the .java source files and compiled .class files created when processing JSP pages.
The Tomcat documentation has improved vastly compared to early versions and should be your first stop if you need to configure Tomcat in any way. However, there are a few steps that are sufficiently common that we cover them here.
There are two ways to tell Tomcat to deploy a web application:
As mentioned above, you can deploy an application simply by placing a WAR file or an expanded web application directory structure in the webapps directory.
However, the default settings may not be suitable for your application, in which case it will be necessary to edit <CATALINA_HOME>\conf\server.xml and add a <Context> element for your application.
The default server.xml file is well commented, and you should read these to familiarize yourself with the contents of this file. Various additional elements, not shown or described here but included in the default server.xml, provide for logging and other similar functionality, and define authentication realms. The default server.xml also includes commented-out sections illustrating how to set up a secure (HTTPS) connector, and to set up database-driven authentication realms. It also includes elements that work together with the mod_webapp Apache module.
The outline structure of server.xml is as follows:
<Server> <Service> <Connector/> <Engine> <Host> <Context/> </Host> </Engine> </Service> </Server>
At the top level is a <Server> element, representing the entire Java Virtual Machine:
<Server port="8005" shutdown="SHUTDOWN" debug="0">
The <Server> element may contain one or more <Service> elements. A <Service> element represents a collection of one or more <Connector> elements that share a single 'container' (and therefore the web applications visible within that container). Normally, that container is an <Engine> element:
A <Connector> represents an endpoint by which requests are received and responses are returned, passing them on to the associated <Container> (normally an <Engine>) for processing. This <Connector> element creates a non-secure HTTP/1.1 connector, listening on port 8080:
<Connector className="org.apache.catalina.connector.http.HttpConnector" port="8080" minProcessors="5" maxProcessors="75" acceptCount="10" debug="0"/>
An <Engine> element represents the Catalina object that processes every request, passing them on to the appropriate <Host>:
<Engine name="Standalone" defaultHost="localhost" debug="0">
The <Host> element is used to define the default virtual host:
<Host name="localhost" debug="0" appBase="webapps">
A <Context> element is used to define an individual web application:
<Context path="/examples" docBase="examples" debug="0" reloadable="true"> </Context>
The attributes of the <Context> element are:
Determines the URL prefix where the application will be deployed. In the example above, the application will be found at http://localhost:8080/examples/.
Specifies the whereabouts of the WAR file or expanded web application directory structure for the application. Since a relative file path is specified here, Tomcat will look in its webapps directory (this was configured in the <Host> element, above) but an absolute file path can also be used.
Specifies the level of debugging information that will be produced for this application.
Intimates whether the container should check for changes to files that would require it to reload the application. When deploying your application in a production environment, setting its value to false will improve performance, as Tomcat will not have to perform these checks.
</Host> </Engine> </Service> <!-- Snip details of service for the mod_webapp connector --> </Server>
Tomcat 4.0's default configuration includes a web application that allows web applications to be deployed, undeployed, and reloaded while Tomcat is running. This application is installed by default in the manager web application, and contains four commands:
List all web applications currently deployed in this virtual host.
Deploy the web application specified by the war request parameter, at the context path given by the path parameter.
Reloads all the Java classes in the specified web application. This works even if automatic class reloading is disabled.
Shuts down and undeploys the specified web application.
When specifying a web application to the deploy command, the value of the war request path must have one of these forms:
The absolute path to the directory containing the unpacked web application
A URL specifying the absolute path to the WAR file
A URL specifying the location of the HTTP-accessible WAR file
Before you can use the manager application you need to set up a user in tomcat-users.xml with the role manager:
<tomcat-users> <user name="tomcat" password="tomcat" roles="tomcat" /> <user name="role1" password="tomcat" roles="role1" /> <user name="both" password="tomcat" roles="tomcat,role1" /> <user name="admin" password="adminpassword" roles="manager" /> </tomcat-users>
With this addition, the manager application works just fine:
If you need help with Tomcat 4.0, and this appendix and the documentation just haven't helped, your first port of call should be the Tomcat web site, http://jakarta.apache.org/tomcat/. There are two mailing lists dedicated to Tomcat issues:
This is where you can ask questions on configuring and using Tomcat. The Tomcat developers should be on hand to help out as necessary.
This is where the developers themselves lurk. If you decide to get stuck in with contributing to improving Tomcat itself, this is where the action is.
bin directory, Tomcat 4.0, 5
classes directory, Tomcat 4.0, 6
common directory, Tomcat 4.0, 6
conf directory, Tomcat 4.0, 6
debug attribute, <Context> element, 8
docBase attribute, <Context> element, 8
J2SE (Java 2 Platform, Standard Edition)
Jakarta see Tomcat 4.0.
lib directory, Tomcat 4.0, 6
logs directory, Tomcat 4.0, 6
manager web application, Tomcat 4.0
path attribute, <Context> element, 8
references to web sites
reloadable attribute, <Context> element, 8
server directory, Tomcat 4.0, 6
src directory, Tomcat 4.0, 6
Sun's Industry Momentum page
Tomcat see also Tomcat 4.0.
tomcat-users.xml, Tomcat 4.0
webapps directory, Tomcat 4.0, 6
work directory, Tomcat 4.0, 6
|< Free Open Study >|| |