Recipe 2.1 Deploying an Individual Servlet on Tomcat

Problem

You want to take a compiled servlet and install it in Tomcat to find out if it is working. You are doing a preliminary test and do not want to take the time to build a complete web application for the servlet.

Solution

Copy and paste the class file into Tomcat's default web application (or into a web application that you have already installed), then request it using the invoker servlet. Or use an Ant build.xml file to move the file temporarily into the Tomcat default web application.

Discussion

Sometimes you design a servlet and are anxious to see if the servlet works. Unless the servlet depends on other servlets or components in the application, you can test it on Tomcat by pasting the class file (including its package- related directories) into the default Tomcat web application. By default, this application is located at the path <Tomcat-installation-directory>/webapps/ROOT .

If the fully qualified class name of the servlet is jspservletcookbook.CookieServlet , then here is the entire process for manually getting a single servlet going on Tomcat:

Shut down the Tomcat server by executing the shell script <tomcat-installation-directory>/bin/shutdown or by executing a shell script your server administrator has provided. An alternative is to "stop" the default application by requesting this URL in your browser: http:// localhost:8080/manager/stop?path=/ .
Create the jspservletcookbook directory in the <Tomcat-installation-directory>/webapps/ROOT/WEB-INF/classes directory (make the classes directory if it does not already exist).
Paste the CookieServlet class file into the <Tomcat-installation-directory>/webapps/ROOT/WEB-INF/classes/ jspservletcookbook directory.
Start up the Tomcat server by executing the shell script <Tomcat-installation-directory>/bin/startup or a shell script that your server administrator has provided. An alternative is to start the default application by requesting this URL in your browser: http:// localhost:8080/manager/start?path=/ .
Request the servlet in your browser with the URL http://localhost:8080/servlet/jspservletcookbook.CookieServlet .

By now you are probably saying, "There must be a more elegant alternative to this slow, manual installation of a single servlet!" You are correct, and can use Jakarta Ant to convert this manual process to an automated one.

The build.xml file in Example 2-1 accomplishes the same testing process, assuming you have downloaded and installed Ant as described in Chapter 4. Place this build file in a convenient directory. Create in that directory a global.properties file that is customized according to your needs (see Example 2-2). Change to that directory in a command-line window and type ant . Ant takes care of the rest of the tasks , including starting and stopping Tomcat's default web application.

Example 2-1. Installing a servlet in the default web application

 <project name="Cookbook" default="deploy-servlet" basedir=".">    <taskdef name="start" classname="org.apache.catalina.ant.StartTask" />    <taskdef name="stop" classname="org.apache.catalina.ant.StopTask" /> <!-- Load in some global properties -->    <property file="global.properties" />    <target name="init" description="Initializes some properties.">        <echo message="Initializing properties."/>        <property name="build" value=".\build" />        <property name="src" value=".\src" />         <!-- The context-path is just a slash character when it is the ROOT application;         see the start and stop targets, which already include the slash as part of         the URL pattern -->        <property name="context-path" value="" />    </target>       <target name="prepare" depends="init">        <echo message="Cleaning up the build directory."/>        <delete dir="${build}"/>        <mkdir dir="${build}"/>    </target>    <!-- Set the CLASSPATH to various Tomcat .jar files -->    <path id="classpath">        <fileset dir="${tomcat.dir}/common/lib">            <include name="*.jar" />        </fileset>        <fileset dir="${tomcat.dir}/common/endorsed">             <include name="*.jar" />        </fileset>    </path>    <!-- start the default Tomcat web application -->    <target name="start"       description="Starts the default Web application">        <echo message="Starting the default application...."/>        <start           url="${url}"            username="${username}"            password="${password}"            path="/${context-path}"          />    </target> <!-- stop the default Tomcat web application -->    <target name="stop"       description="Stops the default Web application">        <echo message="Stopping the application...."/>        <stop           url="${url}"            username="${username}"            password="${password}"            path="/${context-path}"         />    </target> <!-- stop the default Tomcat web application, compile your servlet, add it to the default  Web application, then start the default web application -->    <target name="deploy-servlet" depends="prepare"        description=       "Compile the specified servlet, then move it into Tomcat's default        Web application.">        <echo message="Stopping the default Tomcat application...."/>        <antcall target="stop"/>        <echo message="Compiling the servlet...."/>        <javac srcdir="${src}" destdir="${build}">            <include name="${compiled.servlet}.java" />              <classpath refid="classpath"/>        </javac>        <echo message=           "Copying the servlet to Tomcat ROOT web application..."/>        <copy todir="${tomcat.webapps}/WEB-INF/classes">            <fileset dir="${build}" />        </copy>        <echo message="Starting the default application...."/>        <antcall target="start"/>    </target> </project>

The global.properties file that sits in the same directory as build.xml looks like Example 2-2.

Example 2-2. global.properties file for Ant

 tomcat.webapps=k:/jakarta-tomcat-4.1.12/webapps/ROOT tomcat.dir=k:/jakarta-tomcat-4.1.12 url=http://localhost:8080/manager compiled.servlet=CookieServlet username=tomcat password=tomcat

global.properties is just a list of property-name = value pairs. In other words, each line is composed of a string of characters that represents the property name ( optionally including a period character), followed by an "=" sign and another bunch of characters that represents the value.

Jakarta Ant's online manual is located at: http://jakarta.apache.org/ant/manual/index.html.

Here is what build.xml does:

Defines two tasks with a taskDef element, called start and stop . These tasks will be used by the targets start and stop later on in the build.xml file. These tasks allow you to use the Tomcat "manager" application-deployment tool from your Ant files.
Uses a property task to load in the set of properties that are defined in the global.properties file. This means that the property name tomcat.dir is now available for use later on in the build.xml file. The path element uses the tomcat.dir property by including its value (in the example, "k:/jakarta-tomcat-4.1.12") as part of a classpath definition. You get the value of these imported properties by using a reference like ${tomcat.dir} . Any time you want to give the property a different value before executing an Ant file, you can just change the properties file by typing in a new value in a text editor.
Creates an init target that echoes a message to the console and creates three properties ( build , src , and context-path ). The values of these properties are available only after the init target has been executed. For example, if the prepare target does not have "init" as the value of its depends attribute, the deploy-servlet target, which depends on prepare , cannot use the property values defined by init .
Defines a target called prepare .
Builds a reusable classpath (with the ID "classpath") out of all of the JAR files located in a couple of Tomcat directories.
Creates the start and stop targets. These targets echo a message to the console and then call the tasks (such as stop ) that were defined with taskDef elements at the top of the build.xml file. The start and stop targets are actually invoked by the all-in-one target deploy-servlet .
Creates the deploy-servlet target. This target does all the major work inside the build.xml file. Notice that its depends attribute has the value "prepare." This means that prior to executing the instructions contained within the deploy-servlet target, Ant first executes the init and prepare targets. Since the prepare target depends on the init target, deploy-servlet calls prepare , which itself calls it own dependency, the init target. So just by launching the deploy-servlet target, you have triggered a target chain that looks like init prepare deploy-servlet . Using an element called antcall with which a target may explicitly call another target, deploy-servlet calls both the stop and start targets. In this way it can:
1. Stop the default Tomcat application.
2. Compile the servlet using the javac task. The javac task includes the servlet that is specified by the compiled.servlet property, which is set inside the global.properties file.
Copies the compiled servlet to the WEB-INF/classes directory of Tomcat's default web application. The copy task creates this classes directory if it does not already exist.
Starts the default web application so that you can request your servlet in the browser.