Java Servlets - Part 1

Deploying a Servlet

In its default configuration, Tomcat expects you to place compiled Servlets in the webapps\ROOT\WEB-INF\classes subdirectory of the Tomcat installation directory to deploy them. Place your compiled MyServlet.class file in that directory, then (assuming Tomcat is running on your local computer) load http://localhost:8080/servlet/MyServlet. If you did everything right, you should see a Web page a lot like this one:

If you have Apache installed to interface with Tomcat using mod_jk, you should also be able to view your Servlet with http://localhost/servlet/MyServlet (or http://localhost:8000/servlet/MyServlet if you have configured Apache to run on port 8000).

Most of the time, that's all you need to do to deploy a Servlet! There are some situations, however, where you'd like to make your Servlet available from a different address. One common case is when you assign a package name to a Servlet. For example, consider what would happen if placed the MyServlet class in the package com.sitepoint.web by adding the line

package com.sitepoint.web;

to the top of the MyServlet.java file. To deploy the MyServlet.class file, you would place it in webapps\ROOT\WEB-INF\classes\com\sitepoint\web (recall that the locations of .class files must reflect their package names), and load it with its fully-qualified class name (http://localhost:8080/servlet/com.sitepoint.web.MyServlet). Already this is a fairly ugly URL, and things can get a lot messier with log package or class names.

For this reason, you may want to assign an alternate name to your Servlet. This is done with the web.xml file in the WEB-INF directory (e.g. webapps\ROOT\WEB-INF\web.xml). This is an XML file that lets you configure the Servlets you have deployed. Since XML files are plain text, you can simply open it in Notepad to make the required changes. When you first install Tomcat, web.xml doesn't contain any configuration information:

<?xml version="1.0" encoding="ISO-8859-1"?>    
<!DOCTYPE web-app    
   PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"    
   "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">    
<web-app>    
</web-app>

By adding tags between <web-app> and </web-app>, you can add configuration information for your servlets. Here's how to assign the name 'my' to MyServlet:

<web-app>    
 <servlet>    
   <servlet-name>    
     my    
   </servlet-name>    
   <servlet-class>    
     MyServlet    
   </servlet-class>    
 </servlet>    
</web-app>

If you save the above changes, then shutdown and restart Tomcat, you will be able to access your Servlet as http://localhost:8080/servlet/my. This may not seem like a big deal, but when your Servlet's class name is 25 characters in length and is deeply nested in a package, you'll appreciate being able to give it a nice, short name.

Assigning your Servlet a name also lets you use that name to specify additional configuration parameters for your Servlet. The <servlet-mapping> tag, for instance, lets you map your Servlet to any URL or URL pattern on your server:

<web-app>    
 <servlet>    
   <servlet-name>    
     my    
   </servlet-name>    
   <servlet-class>    
     MyServlet    
   </servlet-class>    
 </servlet>    
 <servlet-mapping>    
   <servlet-name>    
     my    
   </servlet-name>    
   <url-pattern>    
     /my.html    
   </url-pattern>    
 </servlet-mapping>    
</web-app>

The above code will let you access you Servlet as http://localhost:8080/my.html -- completely hiding the fact that you're using a Servlet at all! You can also specify a <url-pattern> with a wildcard character such as /my/*, which would use your Servlet to display any URL that started with "http://localhost:8080/my/", or *.blah, which would map all requests for filenames ending in .blah to your Servlet. Since the HttpServletRequest object that your Servlet receives lets your Servlet examine the URL that was requested, you could conceivably map a single Servlet to /* and have it handle every request on your Website, sending different responses depending on the URL requested!

If you have Apache set up as your main Web server using mod_jk to forward requests for Servlets and JavaServer Pages (JSPs) to Tomcat, you'll find that <url-pattern> doesn't work as expected. This is because, by default, Apache will only forward requests for files ending in .jsp or files in the /servlet directory to Tomcat for processing. To forward additional URL patterns to Tomcat, you must use the JkMount directive in your Apache configuration file. Make sure you do this after the line where you Include Tomcat's mod_jk.conf-auto file (which loads the module required for JkMount to work). For example, to map /my/*.blah (all .blah files in the /my directory) to Tomcat, you would add the following:

JkMount /my/*.blah ajp13

Note that we specify the more efficient ajp13 protocol for communication between Apache and Tomcat for this mapping (Tomcat's mod_jk.conf-auto file currently uses the older, less efficient ajp12 for its default mappings). With that change made, restart Tomcat and Apache and your mapping should now work through your Apache server.

As you can see, all this deployment and configuration of Servlets is a fairly messy business when done by standard methods. Commercial Web servers like those I mentioned in the introduction often provide nice, graphical administration interfaces that make all these low-level modifications for you in the background. The format of the web.xml file, however, is defined in the Servlet standard, and is supported by all Servlet-enabled servers, even if easier methods are provided for managing the settings it contains.