Académique Documents
Professionnel Documents
Culture Documents
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
Configuring & Using Apache Tomcat 6 A Tutorial on Installing and Using Jakarta Tomcat for Servlet and JSP Development
Following is a guide to installing and configuring Apache Tomcat 6 for use as a standalone Web server (for development) that supports servlets 2.5 and JSP 2.1. (Note: Apache Tomcat is sometimes referred to as "Jakarta Tomcat" since the Apache Java effort is known as "The Jakarta Project"). This Tomcat tutorial covers version 6.0.10, but the steps are almost the same for any Tomcat 6.0.x version. For coverage of Tomcat 5.5, see the separate Tomcat 5.5 tutorial. For coverage of very old Tomcat versions (Tomcat 5.0.x and Tomcat 4.0.x), please see the Apache Tomcat 5.0 and 4.0 tutorial. Using Tomcat as a deployment server or integrating Tomcat as a plugin within the regular Apache server or a commercial Web server is more complicated than what is described in this tutorial. Although such integration is valuable for a deployment scenario (see http://tomcat.apache.org/tomcat-6.0-doc/), my goal here is to show how to use Tomcat as a development server on your desktop. Regardless of what deployment server you use, you'll want a standalone server on your desktop to use for development. The examples here assume you are using Windows, but they can be easily adapted for MacOS, Linux, Solaris, and other versions of Unix. Except when I refer to specific Windows paths (e.g., C:\blah\blah), I use URL-style forward slashes for path separators (e.g., install_dir/webapps/ROOT). Adapt as necessary. To report errors or omissions in this writeup or to inquire about customized on-site training courses on servlets, JSP, Struts, JSF, Ajax, Java 5, Java 6, and other J2EE technologies, please contact Marty Hall at hall@coreservlets.com.
Executive Summary Most people will just want to download the preconfigured Tomcat version, set JAVA_HOME and CLASSPATH, and they are done. But following is a summary of the steps for people who want to change the configuration or do it themselves. This section gives a summary of the required steps; I give extremely detailed instructions in the following sections. Install the JDK. Make sure JDK 1.5 or 1.6 is installed and your PATH is set so that both "java -version" and "javac -help" give a result. Configure Tomcat. 1. Download the software. Go to http://tomcat.apache.org/download-60.cgi and download and unpack the zip file for the current release build of Tomcat 6.0. 2. Set the JAVA_HOME variable. Set it to refer to the base JDK directory, not the bin subdirectory. 3. Change the port to 80. Edit install_dir/conf/server.xml and change the port attribute of the Connector element from 8080 to 80. 4. Turn on servlet reloading. Edit install_dir/conf/context.xml and change <Context> to <Context reloadable="true" privileged="true"> . 5. Enable the invoker servlet. Go to install_dir/conf/web.xml and uncomment the servlet and servlet-mapping elements that map the invoker servlet to /servlet/*. 6. Turn on directory listings. Go to install_dir/conf/web.xml, find the init-param entry for listings, and change the value from false to true. 7. Set the CATALINA_HOME variable. Optionally, set CATALINA_HOME to refer to the top-level Tomcat installation directory. Not necessary unless you copy the startup scripts instead of making shortcuts to them. 8. Use a preconfigured Tomcat version. Optionally, use a version of Jakarta Tomcat that has all of the above changes already made, and has the test HTML, JSP, and servlet files already bundled. Just unzip the file, set your JAVA_HOME and CLASSPATH variables, and you are ready to go. Test the server. 1. Verify that you can start the server. Double-click install_dir/bin/startup.bat and try accessing http://localhost/. 2. Check that you can access your own HTML & JSP pages. Drop some simple HTML and JSP pages into install_dir/webapps/ROOT and access them with http://localhost/filename. 3. Try Compiling and Deploying Servlets. Set up your development environment. 1. Create a development directory. Put it anywhere except within the Tomcat installation hierarchy.
1 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
2. Make shortcuts to the Tomcat startup & shutdown Scripts. Put shortcuts to install_dir/bin/startup.bat and install_dir/bin/shutdown.bat in your development directory and/or on your desktop. 3. Set your class path. Use the CLASSPATH environment variable or set the path in the project settings of your IDE. Include the current directory ("."), the servlet/JSP JAR files (install_dir/lib/servlet-api.jar, and install_dir/lib/jsp-api.jar, and install_dir/lib/el-api.jar), and your main development directory from Step 1. 4. Bookmark the servlet & JSP javadocs. Add the servlet 2.4 API and the JSP 2.0 API to your bookmarks/favorites list. Compile and test some simple servlets. 1. Test a packageless servlet. Compile a simple servlet, put the .class file in install_dir/webapps/ROOT/WEB-INF/classes, and access it with http://localhost/servlet/ServletName. 2. Test a servlet that uses packages. Compile the servlet, put the .class file in install_dir/webapps/ROOT/WEB-INF/classes/packageName, and access it with http://localhost/servlet/packageName.ServletName . 3. Test a servlet that uses packages and utility classes. Compile a servlet, put both the servlet .class file and the utility file .class file in install_dir/webapps/ROOT/WEB-INF/classes/packageName, and access the servlet with http://localhost/servlet/packageName.ServletName . This third step verifies that the CLASSPATH includes the top level of your development directory. Establish a simplified deployment method. 1. Copy to a shortcut. Make a shortcut to install_dir/webapps/ROOT. Copy packageless .class files directly there. With packages, copy the entire directory there. This is the simplest option for beginners, and the preconfigured Tomcat version already has a development directory with these shortcuts. 2. Use the -d option of javac. Use -d to tell Java where the deployment directory is. 3. Let your IDE take care of deployment. Tell your IDE (Eclipse, NetBeans, JBuilder, etc.) where the deployment directory is and let it copy the necessary files. 4. Use ant or a similar tool. Use the Apache make-like tool to automate copying of files. Get more info. Access the complete set of Tomcat docs, get free JSP and servlet tutorials, read the official servlet and JSP specifications, get JSP-savvy editors and IDEs, look for J2EE jobs, etc.
Install the JDK Your first step is to download and install Java. Tomcat 6.0 requires JDK 1.5 Standard Edition (Java 5) or JDK 1.6 Standard Edition (Java 6). See the following sites for download and installation information. JDK 1.5 (Java 5) for Windows, Linux, and Solaris: http://java.sun.com/javase/downloads/index_jdk5.jsp. Be sure you download the full JDK (J2SE Development Kit), not just the JRE (Java Runtime Environment). The JRE is only for running already-compiled .class files, and lacks a compiler. JDK 1.6 (Java 6) for Windows, Linux, and Solaris: http://java.sun.com/javase/downloads/index.jsp. Be sure you download the full JDK (J2SE Development Kit), not just the JRE (Java Runtime Environment). The JRE is only for running already-compiled .class files, and lacks a compiler. Java for MacOS: http://developer.apple.com/java/download/. Once you've installed Java, confirm that everything including your PATH is configured properly by opening a DOS window and typing "java -version" and "javac -help". You should see a real result both times, not an error message about an unknown command. Or, if you use an IDE, compile and run a simple program to confirm that the IDE knows where you installed Java. For example, if you have JDK 1.5_08, you could set your PATH by putting the following line in your C:\autoexec.bat file. set PATH="C:\Program Files\Java\jdk1.5.0_08\bin";%PATH%
On Windows XP, you could also go to the Start menu, select Control Panel, choose System, click on the Advanced tab, press the Environment Variables button at the bottom, and enter the PATH variable and value directly. On Windows 2000 and NT, you do Start, Settings, Control Panel, System, then Environment. However, you can use C:\autoexec.bat on those versions of Windows also (unless a system administrator has set your PC to ignore it).
2 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
Configure Tomcat Configuring Tomcat involves four main steps and five optional steps: 1. 2. 3. 4. 5. 6. 7. 8. 9. Downloading the Tomcat software. Setting the JAVA_HOME variable. Changing the port from 8080 to 80. Telling Tomcat to reload servlets when they are modified. Enabling the invoker servlet. Turning on directory listings. Setting the CATALINA_HOME variable. (Optional; rarely used) Using a preconfigured version of Tomcat with these changes already made. (Optional; widely used) Using the Windows .exe installer instead of the .zip file. (Not Recommended)
Details of each step are given below. If Tomcat is already running, restart it after performing these steps.
On Windows XP, you could also go to the Start menu, select Control Panel, choose System, click on the Advanced tab, press the Environment Variables button at the bottom, and enter the JAVA_HOME variable and value directly. On Windows 2000 and NT, you do Start, Settings, Control Panel, System, then Environment. However, you can use C:\autoexec.bat on those versions of Windows also (unless a system administrator h as set your PC to ignore it).
You can also: Use my preconfigured Jakarta Tomcat version. Apache Tomcat 6.0.10 with all server.xml, context.xml, and web.xml changes, plus the sample HTML, JSP, and Java files.
3 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
Download my modified server.xml for Tomcat 6.0. From Apache Tomcat 6.0.10, but should work on most versions of Tomcat 6.0. Right-click or shift-click on the link to download the file.
Note that the privileged entry is really to support the invoker servlet (see the following section), so you can omit that entry if you do not use the invoker. You can also: Use my preconfigured Tomcat version. Tomcat 6.0.10 with all server.xml, context.xml, and web.xml changes, plus the sample HTML, JSP, and Java files. Download my modified context.xml for Tomcat 6.0. From Tomcat 6.0.10, but should work on most versions of Tomcat 6.0. Right-click or shift-click on the link to download the file.
4 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
In Tomcat 6 (but not Tomcat 5.5), you also need the privileged="true" entry in the Context element of context.xml. See the previous section for an example. You can also: Use my preconfigured Tomcat version. Tomcat 6.0 with all server.xml, context.xml, and web.xml changes, plus the sample HTML, JSP, and Java files. Download my modified web.xml for Tomcat 6.0. From Tomcat 6.0.10, but should work on most versions of Tomcat 6.0. Right-click or shift-click on the link to download the file.
You can also: Use my preconfigured Tomcat version. Tomcat 6.0 with all server.xml, context.xml, and web.xml changes, plus the sample HTML, JSP, and Java files. Download my modified web.xml for Tomcat 6.0. From Tomcat 6.0.10, but should work on most versions of Tomcat 6.0. Right-click or shift-click on the link to download the file.
5 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
differences: It will prompt you for the desired port. It will ask you what port it should run on, and make the changes in server.xml for you. You will still need to manually edit context.xml and web.xml, however. It will set JAVA_HOME for you. The installer hunts for your Java installation and tries to set JAVA_HOME appropriately. This is a convenience, albeit a minor one. It will setup Start Menu entries. In particular, instead of using startup.bat and shutdown.bat, you can go to the Start Menu, select Apache Tomcat 6.0, select Monitor Tomcat, and select Start or Stop, as shown below. I prefer startup.bat and shutdown.bat so that I can put shortcuts in my development directory (easier to invoke) and/or the desktop (where I can associate keyboard shortcuts).
Test the Server Testing the server involves three steps: 1. Verifying that the server can even start. 2. Checking that you can access your own HTML and JSP pages. 3. Seeing if you can compile and run simple servlets.
6 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
proxy server" checkbox is selected, make sure the "Bypass proxy server for local addresses" box is also selected. On Netscape 6/7, go to the Edit menu, then select Preferences, Advanced, and Proxies. Then enter "localhost" in the textfield labeled "No Proxy for:". On Mozilla Firefox go to Tools, Internet Options, and Connections. Make sure "localhost" is in the textfield labeled "No Proxy for:". Note that this entry is the default with Firefox, so you probably do not need to change it. To halt the server, double click on install_dir/bin/shutdown.bat. I recommend that you make shortcuts to (not copies of) the startup and shutdown scripts and place those shortcuts on the desktop or in your main development directory. If you put them on the desktop, you can assign keyboard shortcuts, which is convenient.
Set Up Your Development Environment The server startup script startup.bat automatically sets the server's CLASSPATH to include the standard servlet and JSP classes and the WEB-INF/classes directory (containing compiled servlets and other .class files) of each Web application. But you need similar settings, or you will be unable to compile servlets in the first place. Configuring your system for servlet development involves the following four steps: 1. 2. 3. 4. Creating a development directory Making shortcuts to the Tomcat startup and shutdown scripts Setting your CLASSPATH Bookmarking the servlet & JSP javadocs
7 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
Eventually, you will organize this development directory into different Web applications. For initial testing of your environment, however, you can just put servlets either directly in the development directory (for packageless servlets) or in a subdirectory that matches the servlet package name. Some developers simply put all their code in the server's deployment directory (within install_dir/webapps). I strongly discourage this practice and instead recommend one of the approaches described in the deployment section. Although developing in the deployment directory seems simpler at the beginning since it requires no copying of files, it significantly complicates matters in the long run. Mixing locations makes it hard to separate an operational version from a version you are testing, makes it difficult to test on multiple servers, and makes organization much more complicated. Besides, your desktop is almost certainly not the final deployment server, so you'll eventually have to develop a good system for deploying anyhow. Note that the preconfigured Tomcat version already contains all the test files, has shortcuts from the development directory to the deployment locations, and has shortcuts to start and stop the server.
8 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
settings are totally IDE-specific and won't be discussed here. Another alternative is to make a .bat file or ant build script whereby -classpath ... is automatically appended onto calls to javac. Windows NT/2000/XP. You could use the autoexec.bat file as above, or you can use system settings. On WinXP, go to the Start menu and select Control Panel, then System, then the Advanced tab, then the Environment Variables button. On Win2K/WinNT, go to the Start menu and select Settings, then Control Panel, then System, then Environment. Either way, enter the CLASSPATH value from the previous bullet.
Compile and Test Some Simple Servlets OK, so your environment is all set. At least you think it is. It would be nice to confirm that hypothesis. Verifying this involves the following three steps: 1. Testing a packageless servlet 2. Testing a servlet that uses packages 3. Testing a servlet that uses packages and utility classes Details on each step are given below.
9 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
should go in the coreservlets directory both during development and when deployed to the server. Once you compile HelloServlet2.java, put HelloServlet2.class in install_dir/webapps/ROOT/WEB-INF/classes/coreservlets. For now, you can simply copy (not move!) the coreservlets subdirectory from the development directory to install_dir/webapps/ROOT/WEB-INF/classes. An upcoming section will provide some other options for the deployment process. Once you have placed the servlet in the proper directory, access it with the URL http://localhost/servlet/coreservlets.HelloServlet2 . You should get a simple HTML page that says "Hello (2)". If the first test succeeded but this test failed, you probably either typed the URL wrong (e.g., used a slash instead of a dot after the package name) or put HelloServlet2.class in the wrong location (e.g., directly in install_dir/webapps/ROOT/WEB-INF/classes directory instead of in the coreservlets subdirectory).
install_dir/shared/classes is a Tomcat-specific location that is supported on few, if any, other servers. 2. It is specific to a Web application. Once you become comfortable with the basics, you will almost certainly divide your projects up into separate Web applications. By putting your code in WEB-INF/classes, you are ready for this, since your code is already part of a Web application (the default one for Tomcat). So, the code can easily move to another Web application, and it will not interfere with any future applications. On the other hand, install_dir/shared/classes results in code that is shared by all Web applications on your server. This is almost never what you want for servlets.
10 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
comfortable with the development process. Note that I do not list the option of putting your code directly in the server's deployment directory. Although this is one of the most common choices among beginners, it scales so poorly to advanced tasks that I recommend you steer clear of it from the start. 1. 2. 3. 4. Copy to a shortcut or symbolic link. Use the -d option of javac. Let your IDE take care of deployment. Use ant or a similar tool.
You could even make a Windows batch file or Unix shell script or alias that makes a command like servletc expand to javac -d install_dir/.../classes. See http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javac.html for more details on -d and other javac options. An advantage of this approach is that it requires no manual copying of class files. Furthermore, the exact same command can be used for classes in different packages since javac automatically puts the class files in subdirectories matching the package names. The main disadvantage of this approach is that it applies only to Java class files; it won't work for deploying HTML and JSP pages, much less entire Web applications.
11 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
Using A Preconfigured Tomcat Version If you prefer not to individually make each of the changes described in this tutorial, you can download a version of Jakarta Tomcat that has all of these changes already made. All you have to do is unzip the file and set your JAVA_HOME and CLASSPATH variables, and you are ready to run. In particular, this Tomcat version: Has the port changed from 8080 to 80 (so you do not have to type the port number in the URL). Has servlet reloading turned on (so you do not have to restart the server if you change a servlet .class file). Has the invoker servlet enabled (so you can invoke servlets with http://localhost/servlet/ServletName, without making changes to web.xml or restarting the server). Includes the sample HTML page, JSP page, servlets, and utility classes needed to test your setup. Includes a sample development directory with shortcuts to ROOT, ROOT/WEB-INF/classes, startup.bat, and shutdown.bat. Includes an autoexec.bat file that sets the PATH, CLASSPATH, and JAVA_HOME variables. Be sure you edit this file to refer to the proper JDK path, and be sure to save your original autoexec.bat file, if you have one.
Deploy Using Custom Web Applications For learning and practicing specific servlet and JSP techniques, it is simplest to use Tomcat's default Web application (ROOT) and to use the "invoker servlet" that lets you run servlets by putting /servlet/ServletName at the end of the URL. When you start developing your real project, however, you almost always use custom Web applications (and never use the invoker servlet). This section gives a quick summary on the use of Web applications in Tomcat. For more details, see the Web application sections of the JSP and servlet training materials page.
Learning
Use default Web application (ROOT on Tomcat) Use default URLs (http:///servlet/ServletName) Advantages Simpler. Just drop the servlet in the right location and test immediately. This is far easier than editing web.xml every time you
Deployment
Use a custom Web application (on Tomcat, a directory in install_dir/webapps with structure similar to ROOT) Register custom URLs in WEB-INF/web.xml Advantages URLs look better. No class names in the URLs.
12 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
create a new servlet. Can test without restarting server or editing web.xml (although Tomcat 6.0 usually notices when web.xml has been modified, and reloads the Web app automatically when it has)
Advanced features (init params, security, filters, etc.) depend on your using registered URLs. The invoker servlet is just a convenience for initial testing; never use it for real applications!
Using custom Web apps involves the following steps: 1. 2. 3. 4. Making a directory whose structure mirrors the structure of the default Web application. Updating your CLASSPATH Using the directory name in the URL Using web.xml to assign custom URLs
1. Make a directory whose structure mirrors the structure of the default Web application.
HTML, JSP, images, style sheets, and other regular Web content goes in the top-level directory (or any subdirectory other than WEB-INF or META-INF). The web.xml file goes in the WEB-INF subdirectory Servlets and other classes go either in WEB-INF/classes (unpackaged servlets) or a subdirectory of WEB-INF/classes that matches the package name. On Tomcat, entire directory is deployed in install_dir/webapps. One of the simplest approaches is to create the Web app in your development directory (e.g., C:\Servlets+JSP), then copy the entire directory to install_dir/webapps whenever you want to test it. Simplify the process by keeping a shortcut to install_dir/webapps in C:\Servlets+JSP. Note that you can also deploy using WAR files instead of regular directories. A WAR file is just a JAR file (which is just a ZIP file) with a .war extension. You can create WAR files using jar, WinZip, or the Windows XP "Create Compressed Folder" R-Mouse option. If you use WAR files, a directory such as myWebApp should become myWebApp.war, and the top-level directory within the WAR file should be WEB-INF (i.e., do not repeat myWebApp within the WAR file).
13 of 14
31-03-2008 16:29
http://www.coreservlets.com/Apache-Tomcat-Tutorial/
<servlet-class>coreservlets.HelloServlet2</servlet-class> < > . 2 > </ </servlet> > <servlet-mapping> < > <servlet-name>Servlet2</servlet-name> < > 2 > <url-pattern>/servlet2</url-pattern> < > 2 > </ </servlet-mapping> > </web-app>
If you deployed HelloServlet2 in the myWebApp application using the invoker servlet, it would go in .../myWebApp/WEB-INF/classes/coreservlets and be invoked with the URL http://localhost/myWebApp/servlet/coreservlets.HelloServlet2. If you used a registered URL of servlet2 as above, the class file would still go in .../myWebApp/WEB-INF/classes/coreservlets, but it would be invoked with the URL http://localhost/myWebApp/servlet2
More Information Online documentation Servlet 2.4 API JSP 2.0 API Servlet and JSP Tutorials Java 6 API Java 5 API Java Programming Tutorials Struts Developer and User Guides Struts API Jakarta Struts Tutorials JSF 1.1 Java API JSF 1.1 Tag Library API JSF 1.2 Java API JSF 1.2 Tag Library API Apache MyFaces Documentation Tutorials on JSF (with Apache MyFaces, Ajax4jsf, Tomahawk, and Facelets) Ajax and GWT Tutorials
14 of 14
31-03-2008 16:29