By: Kevin Yank

October 22nd, 2004

Reader Rating: 9

JavaServer Pages (JSP) is a server-side technology that allows developers to create Web-based applications that use Java components. In some respects, it can be compared to server-side scripting languages such as ASP and PHP. JSP is similar to PHP in the C-style syntax of the Java language, but JSP was also designed to be extendable using components like ASP.

When it comes right down to it, however, JSP is a technology like no other. Extremely fast, platform independent, highly scaleable with built-in support for distributed processing, compatible with all major Web servers, and FREE for most uses, one might wonder why JSP isn't used more than it is.

Well, as I see it, there are two main reasons for that:

• To take full advantage of JSP, a developer must first be comfortable working in the Java programming language. Unfortunately, this can be quite an ask for Web developers who like to concentrate on design and dabble in a scripting language or two when necessary. There are lots of good online tutorials and books out there for people interested in learning Java, but the process can be time consuming and, depending on the individual, quite challenging, due to the nature of Java as a pure object-oriented language.
• Setting up a server environment to develop and test JSPs can be a confusing task, especially since most of the documents written to guide users through the process are steeped in technical mumbo jumbo that assumes you already know JSP inside and out. If you're just getting started with JSPs, you want a step-by-step guide to getting a server up and running in short order so that you can concentrate on learning the language, and worry about the details of server configuration later.

In this article, I'll attempt to remedy the latter point by guiding you through the process of setting up a JSP-enabled Web server on a Windows PC. Hopefully, this will give you the head start you need to jump into the world of JSP development. I'll take you as far as getting a basic JSP page working on your server, and then you can dive into our JSP article series, The JSP Files [1] fully equipped!

Downloading and Installing Apache Server

While there are some great commercial servers out there for testing JSP pages (including IBM WebSphere, BEA WebLogic, and others), these can be beyond the reach of the average Web developer who just wants to add a new skill to his or her repertoire. Also, many of these require Windows NT/2000/XP server to run, while many developers are working with Windows 95/98/ME systems. For this reason, the server I recommend for people getting started with JSP is Apache Server. By hooking it up to the Jakarta Project's Tomcat Server (which we'll install in the next section), we can give it the ability to handle JSP pages, as well as related technologies like Java Servlets and Enterprise Java Beans (EJBs)!

Now, if you've already got Apache running, you don't have to reinstall it. This will be good news to people who are already using Apache to run PHP scripts or whatnot, because you'll be able to simply add JSP support to your existing server without disrupting whatever else you have set up. If you've got another Web server installed on your computer, don't worry -- I'll show you how to install Apache in such a way that it doesn't interfere with your existing server. If you've already installed Apache, however, you can skip straight to the next section.

Now, you'll need to go to The Apache HTTP Server Project's Web site [2] to download the latest stable release of Apache Server for Win32. As of this writing, the current version is 2.0.52 (the filename is apache_2.0.52-win32-x86-no_ssl.msi), and can be downloaded from the following address: http://httpd.apache.org/download.cgi [3].

Run the downloaded file as you would any Windows installer (don't let the .msi file extension fool you -- you can run it!). Answer the questions it asks to the best of your ability; the documentation available at the Apache Server Website should answer any questions you may have. When you are asked how Apache should be run -- as a Windows service for all users or in standalone mode, choose the recommended option to run it as a Windows service.

In the rest of this tutorial, I'll assume you allowed the Apache install program to install to C:\Program Files\Apache Group\Apache2.

Once installation is complete, the installer will attempt to launch Apache Server service that it installed. If you already have a Web server installed (e.g. Microsoft Internet Information Services), this will produce an error message complaining that there was no installed service named "Apache2". In addition, the Windows System Tray monitor program that is installed will indicate "No services installed" when you hover your mouse over its icon. Fixing this if it happens to you is not difficult; just follow along and we'll take care of it.

Whether you experienced the problem just described or not, you'll want to tweak some server settings. On your start menu, choose Programs, Apache HTTP Server 2.0.52, Configure Apache Server, Edit the Apache httpd.conf Configuration File. Search for a line in the file that reads Listen 80. If you've already got another Web server running on your computer (and you experienced the problem starting the server described above), chances are port 80 is already in use, and you'll need to pick a different port for Apache to use. The most common port for a second Web server is 8080, so change the line to Listen 8080 instead. If you don't already have a Web server on your system, you can leave this line alone.

A little lower down, you'll see a line that contains the command ServerName. This should have been set during installation, but uncomment the line if it happens to be commented out, and ensure that it is set to 127.0.0.1:8080 (where 8080 is the Listen port you set in the previous paragraph) unless your server has a fixed IP address or hostname, in which case you can use that instead (use 127.0.0.1:8080 if you're not sure, or if you only plan to use the server for testing purposes on your own machine).

That does it for httpd.conf for now. You can save your changes and close the editor. You're now ready to fire up Apache and make sure that it's working. If the installer encountered difficulty starting the server initially (i.e. if you received the 'no installed service named "Apache2"' error), you'll first need to install the service. To do this, you'll need to open the Command Prompt (see my Cheat Sheet [4] if you're not familiar with the prompt).

To install the Apache Server service, you need to run the Apache.exe program (with the -k install parameter) that resides in the bin subdirectory of your Apache2 installation directory. Here are the commands that did the trick on my computer (commands shown in bold):

C:\Documents and Settings\Kevin>d:

D:\>cd \Apache\Apache2

C:\Apache\Apache2>bin\apache.exe -k install

C:\Apache\Apache2>exit

With the httpd.conf file properly configured and the service installed, we can start (or re-start) the server. On the Start menu, choose Programs, Apache HTTP Server 2.0.52, Control Apache Server, Restart. The Apache Server Monitor in the Windows System Tray should change to show a green arrow instead of a red square, indicating the server is now running. Open your Web browser and type http://localhost (or http://localhost:8080 if you changed the Listen line in httpd.conf above) in the address field and press Enter.

A Web page with the Powered by Apache logo at the bottom should appear, explaining that Apache is correctly installed. Congratulations, you've successfully installed Apache!

Downloading and Installing Tomcat

Since Apache doesn't support JSP out of the box, we need to add something else to the mix to provide that support. Unfortunately, JSP is too complicated to be supported by a simple Apache module; thus, we need to install an entirely new program to provide that support, then instruct Apache to forward requests for JSP pages to that program (note: this may sound like CGI, but it isn't; just wait and see). The program we'll be using is called Tomcat, and is also written by the Apache Group.

Tomcat is in fact a simple Web server in its own right. It doesn't support any of the advanced features of Apache, however; that's not its job! By linking Tomcat and Apache together, you get a system that provides full support for JSP (thanks to Tomcat) while maintaining the performance and expandability (PHP, Perl, SSL, etc.) of Apache.

Your first step should be to download and install the Java Development Kit (JDK) from Sun. This is required both to run Tomcat (which is a Java program), and for Tomcat to be able to compile JSPs for use. The current Windows version of the JDK, also called the Java 2 Standard Edition (J2SE) JDK, as of this writing is version 5.0, and is available for download here [5] (be sure to download the JDK, not the JRE!). Download and install this ~44MB package as you would any Windows program. I'll assume you've installed it in C:\jdk1.5.0. Be sure to add the C:\jdk1.5.0\bin directory to your system PATH. If you don't know how to do this, refer to the installation instructions provided on the JDK download page.

Now you're ready to install Tomcat. Download the latest release from the Jakarta Project Web site [6]. As of this writing, the latest version was 5.0.28, and was available at http://www.apache.org/dist/jakarta/tomcat-5/v5.0.28/bin/. The file should be called jakarta-tomcat-5.0.28.exe, and is about 10MB.

Once you've downloaded the file, run it as you would any other install program. It will want to install into C:\Program Files\Apache Software Foundation\Tomcat 5.0 by default, but I suggest changing this to C:\Program Files\Apache Group\Tomcat 5.0 to keep it alongside Apache. The installation program will suggest an HTTP/1.1 Connector Port of 8080, which is fine unless you configured Apache to run on that port, in which case you should set Tomcat to use port 8000. You'll need to specify a password for the administrator user's account at this stage, and point the installer at the directory where you installed the JDK as well.

Once Tomcat is installed, you'll have yet another little icon in your Windows System Tray to monitor it. To start Tomcat, right-click on it and choose Start Service. If all goes well, a little green arrow should appear in the icon to indicate Tomcat is running. This will happen automatically when your system starts up from now on by default -- you can configure this and many other key settings by double-clicking the System Tray icon.

As I said before, Tomcat provides its own simple Web server, and we can use this to test that it is working properly. Tomcat's Web server is set up to use port 8080 by default, so open your Web browser and load http://localhost:8080/. If you changed the port to 8000 during the installation, load http://localhost:8000/ instead. You should see the Tomcat home page, with links to some examples that come preinstalled on the server.

Have a play with these examples if you're curious. In previous versions of Tomcat, the JSP examples would take considerable time to load the first time you used them, but would then work very quickly upon subsequent accesses. This happened because the first time a JSP page was accessed, Tomcat needed to compile it into a Java Servlet, which is a piece of pure Java code that can be run very quickly to process requests. That Servlet would then be held in memory to process subsequent requests for the same JSP at blazing speed. Tomcat 5, however, is significantly more clever at compiling things ahead of time, and usually doesn't suffer from this one-time delay.

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 [7], 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 [8]. 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 [9] 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 [10], should get you going with the former; as for the latter, an 8-part tutorial series, The JSP Files [11], 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 [12] 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.

[1] http://www.sitepoint.com/article/parts-1-8-tagged-bagged
[2] http://httpd.apache.org/
[3] http://httpd.apache.org/download.cgi
[4] http://www.sitepoint.com/article.php/846
[5] http://java.sun.com/j2se/1.5.0/download.jsp
[6] http://jakarta.apache.org/
[7] http://jakarta.apache.org/tomcat/connectors-doc/jk2/
[8] http://www.apache.org/dist/jakarta/tomcat-connectors/jk2/binaries/win32/
[9] http://www.sitepoint.com/article/364
[10] http://www.sitepoint.com/article/509
[11] http://www.sitepoint.com/article.php/770
[12] http://www.sitepoint.com/forums/