JSP Quick-Start Guide for Windows

Linking Apache and Tomcat with JK2

Now that you've got Apache and Tomcat running side by side, you need to link them together so that Apache can process JSP requests by handing them off to Tomcat. Several ways of doing this have come and gone with past Tomcat versions, but the latest and greatest is JK2, a combination of an Apache module (mod_jk2) and a Tomcat connector plug-in. JK2 was written to be more modular, offer better performance, and be easier to configure than its popular predecessor, JK.

Documentation of Apache-Tomcat connectors has been very sketchy in the past, but the team is slowly getting its act together these days. Reasonably complete documentation is available on the Tomcat Website, but it's still very technical and not very beginner-friendly. Don't fret, though -- I'll walk you through the process.

The Elusive mod_jk2

JK2 comes in two parts: a connector plug-in for Tomcat and an Apache module. The connector plug-in is included with every copy of Tomcat. The other half of the equation, the Apache module called mod_jk2, is a different story.

Because Apache 2.0 is in a constant state of flux, older versions of the mod_jk2 module will usually not be compatible with newer versions of Apache 2.0. In general, you need a copy of mod_jk2 that was compiled after the Apache 2.0 release you want to use it with. The Jakarta team always try to maintain a downloadable copy of mod_jk2 that is compatible with the latest Apache 2.0 release on their Web site.

At this time, the latest release of mod_jk2 is available from the Apache download server. The file is called jakarta-tomcat-connectors-jk2.0.4-win32-apache2.0.49.zip. Download the file, extract it to a temporary directory, and find the mod_jk2.so file in the modules subdirectory. Copy this file to the modules subdirectory of your Apache 2.0 installation (C:\Program Files\Apache Group\Apache2\modules). Find the file called workers2.properties.sample, copy it to the conf subdirectory of your Apache 2.0 installation, and rename it to workers2.properties.

With the module and its configuration file in place, you need to tell Apache to load it. Open Apache's httpd.conf configuration file from the Start Menu as before, and add this line to the bottom of the list of LoadModule lines:

LoadModule jk2_module modules/mod_jk2.so

Save this change and restart your Apache server. If you've done everything right to this point, it should restart without complaint. If you open the Apache Service Monitor from the Windows System Tray icon, the name of the running service should include "mod_jk2" in the status bar.

Configuring mod_jk2

With mod_jk2 in place, you now need to tell it what URLs you want it to forward to Tomcat for processing. Open the workers2.properties file that you placed in Apache's conf directory in WordPad (Notepad won't display it properly, since it contains UNIX-style line breaks).

In this file, you'll see three lines that look like this:

# Map the Tomcat examples webapp to the Web server uri space
[uri:/examples/*]
group=lb

This demonstrates how to configure mod_jk2 to forward all requests for files in a particular directory and subdirectories (/examples/ in this case) to Tomcat. Unfortunately, Tomcat 5.0 doesn't have an /examples/ directory set up by default (previous versions did), so we need to adjust this a little. Replace the above lines with the following:

# Map the Tomcat jsp-examples webapp to the Web server uri space
[uri:/jsp-examples/*]
group=lb

# Map the Tomcat servlet-examples webapp to the Web server uri space
[uri:/servlets-examples/*]
group=lb

Save your changes, restart Apache, then try loading http://localhost/jsp-examples/ (http://localhost:8080/jsp-examples/ if you are running Apache on port 8080). You should see the list of JSP examples provided by default in a Tomcat installation -- and you're accessing them through Apache!

A Simple JSP

Okay, playing with the examples can be fun (spoiler: the two colours you're looking for are Black and Cyan), but the real test is to set up a JSP of your own and make it run.

Open NotePad or your favourite text editor, and type in the following:

<hr />This example brought to you by JSP and sitepoint.com!

Save the file as theEnd.html in a new subdirectory of Tomcat's webapps folder called sitepoint. Create a second new file in NotePad and type in the following:

<%@ page language="Java" %>  
<html>  
<head>  
<title>A Simple JSP</title>  
</head>  
<body>  
<p>  
<%  
 String num = request.getParameter("num");  
 if (num == null) { // No number specified  
   // Display the form  
%>  
 <form action="<%= HttpUtils.getRequestURL(request) %>">  
   What should I count to? <input type="text" size="2" name="num" />  
   <input type="submit" />  
 </form>  
<%  
 } else for (int i=1; i<=Integer.parseInt(num); i++) {  
%>  
 Counting: <%= i %><br />  
<%  
 }  
%>  
</p>  
<%@ include file="theEnd.html" %>  
</body>  
</html>

Save this as count.jsp in your new sitepoint directory alongside theEnd.html.

Now, to make these two files visible, you need to create a Java Web application to contain them. Doing this is nice and simple. Create a subdirectory of your new sitepoint directory called WEB-INF. In that subdirectory, create a text file called web.xml and type the following into it:

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

Save the file and then restart Tomcat to allow it to become aware of the new Web application. You can then view the page through Tomcat with the URL http://localhost:8080/sitepoint/count.jsp (or http://localhost:8000/sitepoint/count.jsp if you're running Tomcat on port 8000).

To make your new Web application visible through Apache, you'll need to make mod_jk2 aware of it. Open up the workers2.properties file we looked at earlier and add this to the bottom of the file:

[uri:/sitepoint/*]
group=lb

With this change saved, restart Apache, then open http://localhost/sitepoint/count.jsp (as before, add :8080 if you have Apache running on port 8080). There you have it: your first working JSP in Apache!

Where to from here?

If you've worked in PHP or another scripting language before, then the simple example above may have left you a little underwhelmed. "That's it?" you may ask. "I went to all that trouble just to do something I could have done in 30 seconds with PHP?" Of course not! As a simple example, the above does not make use of any of the more powerful features of JSP, most of which require a fairly thorough understanding of the Java programming language to use.

Thus, your first step should be to learn Java if you haven't already. There are plenty of good books out there, but if you're in a hurry or on a budget, my article Getting Started with Java and its successors should get you going.

Once you're up to speed on Java (and I don't mean to trivialize that -- it will take some work), you can turn your attention to Java Servlets, and then JavaServer Pages. My article, Java Servlets, should get you going with the former; as for the latter, an 8-part tutorial series, The JSP Files, is now available on sitepoint.com to teach you all you need to know. Enjoy!

Good luck! If you hit any snags along the way, the SitePoint Forums community is here to help! And if all else fails, you can always contact me through the email link at the top of this article.