Slapping Together A JSP Development Environment

Get a JSP development environment up and running on your Windows/Linux box in thirty minutes flat.

Older

You know you're getting old when it takes you a day to configure software...especially when bright-eyed kids half your age accomplish the same thing in two hours flat.

This was the thought that crossed my mind when I recently decided to set up my machine for JSP (Java Server Pages) development. I got myself set up, made sure there was plenty of space available on my hard drive, and went to work downloading the software off the Web. And I spent the next ten hours wading through acres and acres of incomprehensible detail while trying to get Apache, mod_jserv and Tomcat to talk nice to each other.

The task was made more difficult by the fact that each program used different words to refer to the same thing in their separate documentation, and failed to address some of the gotchas common to such a situation. In fact, once I logged on to Deja.com [http://www.deja.com/] and visited a few of the discussion forums, I found that quite a few of the problems I was experiencing had been addressed by users who obviously have larger brains than mine, and it was only after a few hours in the forums that I was finally able to get my JSP development environment up and running.

What's my point? Very simple: if I wasn't so pig-headed, I would have given up on JSP after the first two hours. This would be a shame, since it's actually a pretty powerful language (and looks particularly good on a resume). And so, I decided to put together this article for all those of you who may be struggling with the same problems, in the hope that it will save you some time and answer some of the questions you may have.

No, no, you don't need to thank me. Money's better.

Essential Software

The first and most basic thing you need to decide is whether you're going to be doing JSP development on Windows or Linux (this tutorial covers both). Myself, I have it working on both my Windows 95 system and my Linux box. If you have the machines to spare, or simply have lots of time on your hands (loser!), you can do the same; if not, pick one and then get yourself copies of all the programs listed below.

Java Development Kit: The J in JSP stands for Java, and you can't do anything without a copy of the latest Java Development Kit from Sun Microsystems. As of this writing, the latest kit is available from http://java.sun.com/ for both Windows and Linux platforms. This tutorial uses the Java2 SDK 1.3.

Tomcat: Sun's recommended server for JSP development, Tomcat takes care of parsing JSP pages and also provides a servlet engine for Java servlets. You can download a copy of Tomcat from The Jakarta Project's Web site at http://jakarta.apache.org/ . This tutorial uses Tomcat 3.2.

Apache: The world's favourite Web server, Apache handles all requests for static HTML content and non-JSP pages. Get yourself a copy for your platform from http://www.apache.org/ . This tutorial uses Apache 1.3.14.

JServ: JServ is an Apache loadable module that serves as the all-important connection between the Tomcat and Apache servers. You can download a copy from http://java.apache.org/jserv/ . This tutorial uses JServ 1.1.1.

Once you've got all that down, it's time to get down to business. We'll do a Windows installation first.

One Tomcat, Standing Alone

The first thing you need to do is set up the JDK. Double-click the installable file you just downloaded, and let the program install itself into a convenient location on your hard drive. I'll assume you've installed it to C:\JDK\

Next, go ahead and install Apache - the default installation location of C:\PROGRAM FILES\APACHE GROUP\APACHE\ is fine - and modify the configuration file "httpd.conf" in case you need to customize its operation. You should test that the server is running by starting it up and pointing your browser to http://localhost/ - if you see an Apache test page, that means your server is up and running. You'll also see an MS-DOS window which displays a status message like this:

C:\> APACHE
Apache/1.3.14 (Win32) running...

Third step: install the Tomcat Web server. Now, Tomcat comes as a single compressed file, which contains both Linux and Windows versions. You don't need to run an installation program; just unzip it to a convenient location and you're done. I used C:\TOMCAT\ as the location for my Tomcat installation.

At this point, it's time to see if the Tomcat server is working (Tomcat works independently of Apache as well). Pop open an MS-DOS window, and set up a few of the environment variables Tomcat needs to function correctly.

C:\> SET JAVA_HOME=C:\JDK

C:\> SET TOMCAT_HOME=C:\TOMCAT

C:\> SET PATH=%PATH%;C:\JDK\BIN

Obviously, you need to replace the locations above with the actual file paths on your system.

Once that's done, change to the Tomcat BIN\ directory and start Tomcat.

C:\TOMCAT\BIN> TOMCAT START

If all went well, you should see something like this:

Including all jars in C:\TOMCAT\LIB in your CLASSPATH.

Using CLASSPATH:
C:\TOMCAT\CLASSES;C:\TOMCAT\LIB\ANT.JAR;C:\TOMCAT\LIB\JAXP.JAR;C:\TOMCAT\LIB
\SERVLET.JAR;C:\TOMCAT\LIB\PARSER.JAR;C:\TOMCAT\LIB\WEBSER~1.JAR;C:\TOMCAT\L
IB\JASPER.JAR;C:\JDK\LIB\TOOLS.JAR

Starting Tomcat in new window

You should also see a new MS-DOS window with something like this displayed in it:

2001-01-30 02:47:19 - ContextManager: Adding context Ctx( /examples )
2001-01-30 02:47:19 - ContextManager: Adding context Ctx( /admin )
Starting tomcat. Check logs/tomcat.log for error messages
2001-01-30 02:47:20 - ContextManager: Adding context Ctx(  )
2001-01-30 02:47:20 - ContextManager: Adding context Ctx( /test )
2001-01-30 02:47:22 - PoolTcpConnector: Starting HttpConnectionHandler on 8080
2001-01-30 02:47:22 - PoolTcpConnector: Starting Ajp12ConnectionHandler on
8007

This indicates that the Tomcat server is running on port 8080.

If, on the other hand, you got this:

Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space
Out of environment space

then there's one more thing you need to do. Close the MS-DOS prompt, move to Windows Explorer, and create a new "MS-DOS Prompt" shortcut (you can copy the one in the Start-> Programs menu if you like). Right-click the shortcut, find the Memory tab, and change the "Initial Environment" memory size from "Auto" to the maximum (usually 4096 KB). Save the changes to your shortcut, use it to open up a new MS-DOS window, set the environment variables as described above, and try running Tomcat again. This time, things should work as advertised.

Quick aside: since the variables you set are destroyed each time you exit an MS-DOS session under Windows, I'd recommend that you add them to your C:\AUTOEXEC.BAT startup file so that they are permanently installed in memory. Or you could write a simple batch file which creates and sets the variables in MS-DOS before running Tomcat each time.

In order to test your Tomcat installation, point your browser to http://localhost:8080/ and try browsing through the various JSP examples available on the default page at http://localhost:8080/examples/jsp/

Alternatively, you could create a simple JSP file called "hello.jsp" in the directory C:\TOMCAT\WEBAPPS\EXAMPLES\JSP\, containing the following JSP code:

<html>
<body>
<%
out.println("Waiter, can I have a cup of Java, please?");
%>
</body>
</html>

And now, when you point your browser to http://localhost:8080/examples/jsp/hello.jsp, you should be presented with a page which looks like this:

<html>
<body>
Waiter, can I have a cup of Java, please?

</body>
</html>

If it works, take a deep breath - you're halfway there! Next, you need to get Apache talking with Tomcat, so that you don't need to add the :8080 suffix each time you want to execute a JSP document.

Connecting The Dots

In order to get Apache and Tomcat working together, you need to load the JServ Apache module. Under Windows, this module is currently named "ApacheModuleJServ.dll", and you need to place it in the C:\PROGRAM FILES\APACHE GROUP\APACHE\MODULES\ directory. Next, open up your "httpd.conf" file, and add the following line to the "DSO Support" section:

LoadModule jserv_module modules/ApacheModuleJServ.dll

This loads the JServ module into memory.

And then add the following line to the end of "httpd.conf":

Include "c:/tomcat/conf/tomcat-apache.conf"

Each time Tomcat starts, it automatically creates a configuration file for Apache, customized to your system - this file is named "tomcat-apache.conf", and is stored in the Tomcat CONF\ directory. This file contains JServ settings specific to Tomcat, together with directives designed to help Apache deal with JSP files, and is essential to getting Tomcat and Apache working together.

If Apache is running, you'll need to stop and restart it for the new settings to take effect. And if all has gone well, the next time you start Apache, you'll see something like this:

Apache/1.3.14 (Win32) tomcat/1.0 running...

This indicates that the JServ module has been loaded, and is available for use with Tomcat.

There is another Windows-specific problem you might encounter at this stage. If your Tomcat server has been installed to a directory with a so-called "long" file path, and this long path contains spaces or strange characters (say, C:\PROGRAM FILES\TOMCAT\WEBAPPS\EXAMPLES), Apache may barf with a complaint about aliases. In this case, note the line number with the error, open up the "tomcat-apache.conf" file, and enclose the long file paths in double quotes to fix the problem.

Finally, the acid test. Start up Tomcat

C:\TOMCAT\BIN> TOMCAT START

Including all jars in C:\TOMCAT\LIB in your CLASSPATH.

Using CLASSPATH:
C:\TOMCAT\CLASSES;C:\TOMCAT\LIB\ANT.JAR;C:\TOMCAT\LIB\JAXP.JAR;C:\TOMCAT\LIB
\SERVLET.JAR;C:\TOMCAT\LIB\PARSER.JAR;C:\TOMCAT\LIB\WEBSER~1.JAR;C:\TOMCAT\L
IB\JASPER.JAR;C:\JDK\LIB\TOOLS.JAR

Starting Tomcat in new window

2001-01-30 02:47:19 - ContextManager: Adding context Ctx( /examples )
2001-01-30 02:47:19 - ContextManager: Adding context Ctx( /admin )
Starting tomcat. Check logs/tomcat.log for error messages
2001-01-30 02:47:20 - ContextManager: Adding context Ctx(  )
2001-01-30 02:47:20 - ContextManager: Adding context Ctx( /test )
2001-01-30 02:47:22 - PoolTcpConnector: Starting HttpConnectionHandler on 8080
2001-01-30 02:47:22 - PoolTcpConnector: Starting Ajp12ConnectionHandler on
8007

Then start up Apache.

Apache/1.3.14 (Win32) tomcat/1.0 running...

And point your browser to http://localhost/examples/jsp/hello.jsp. If Tomcat, Apache and JServ are all configured properly, your JSP page should be parsed by the Tomcat engine and returned correctly to the browser. You can now use Apache to serve JSP documents without the necessity of specifying the port number in the URL.

In case you need to stop the Tomcat server, you can use

C:\TOMCAT\BIN> TOMCAT STOP

Including all jars in C:\TOMCAT\LIB in your CLASSPATH.

Using CLASSPATH:
C:\TOMCAT\CLASSES;C:\TOMCAT\LIB\ANT.JAR;C:\TOMCAT\LIB\JAXP.JAR;C:\TOMCAT\LIB
\SERVLET.JAR;C:\TOMCAT\LIB\PARSER.JAR;C:\TOMCAT\LIB\WEBSER~1.JAR;C:\TOMCAT\L
IB\JASPER.JAR;C:\JDK\LIB\TOOLS.JAR

Stop Tomcat

Same Story, Different OS

If you're using Linux, the procedure is almost identical. First, install the Linux version of the JDK to a directory of your choice (I used /usr/local/jdk/) and then follow that up by installing the Tomcat server (/usr/local/tomcat/). You shouldn't usually need to install Apache, since that comes standard on most Linux distros - however, you should check and ensure that the version you have supports loadable modules. You can verify this by typing

$ /usr/local/apache/bin/httpd -l

(assuming that Apache has been installed to /usr/local/apache/) and viewing the resulting output - if you see the line

mod_so.c

in the list of compiled-in modules, you're good to go. If not, you'll need to recompile your Apache server with support for loadable modules.

You first need to test whether the Tomcat server is working in stand-alone mode. First set the environment variables JAVA_HOME and TOMCAT_HOME to the appropriate locations, like this:

$ JAVA_HOME=/usr/local/jdk; export JAVA_HOME
$ TOMCAT_HOME=/usr/local/tomcat; export TOMCAT_HOME

Add the Java interpreter to your PATH.

$ PATH=$PATH:/usr/local/jdk/bin; export PATH

And then run Tomcat using the shell script in the /usr/local/tomcat/bin directory

$ /usr/local/tomcat/bin/tomcat.sh start

Tomcat should start up, displaying messages similar to the ones above.

In order to test your Tomcat installation, point your browser to http://localhost:8080/ and try browsing through the various JSP examples available on the default page at http://localhost:8080/examples/jsp/

Alternatively, you could create a simple JSP file called "hello.jsp" in the directory /usr/local/tomcat/webapps/examples/jsp/, containing the following JSP code:

<html>
<body>
<%
out.println("Waiter, can I have a cup of Java, please?");
%>
</body>
</html>

And now, when you point your browser to http://localhost:8080/examples/jsp/hello.jsp, you should be presented with a page which looks like this:

<html>
<body>
Waiter, can I have a cup of Java, please?

</body>
</html>

Next, you have to set up Apache to communicate with Tomcat via mod_jserv. Install the mod_jserv.so module that you downloaded (you can either get the source and compile it, or use one of the pre-built RPMs) and then edit Apache's "httpd.conf" file to insert the following lines into it:

LoadModule jserv_module modules/mod_jserv.so

If you're using an RPM, this may be done for you automatically.

And then add the following line to the end of "httpd.conf":

Include /usr/local/tomcat/conf/tomcat-apache.conf

Shut down Apache, start Tomcat, and then restart Apache. If all has gone well, you should now be able to browse to http://localhost/examples/jsp/hello.jsp and view the JSP document correctly.

Putting It In Context

The default Tomcat installation comes with a folder named "webapps", which contains sample files. You can place your JSP documents here, or you can define new locations from which to serve JSP files. In Tomcat-lingo, these locations are known as "contexts", and they're defined in the "server.xml" file in the Tomcat CONF directory.

Let's suppose that you wanted to serve files from the location http://localhost/jsp/, The first thing to do is to define a context in the Tomcat "server.xml" configuration file.

 <Context path="/jsp" docBase="webapps/jsp/" debug="0" reloadable="true">
  </Context>

This maps the location /jsp to the "webapps/jsp" folder.

Next, create a directory named "jsp" in the "webapps" folder, place the "hello.jsp" script there, and restart Tomcat and Apache. You should see the new context when Tomcat starts up.

Context log: path="/examples" Adding context path="/examples"
docBase="webapps/examples"
Context log: path="/test" Adding context path="/test"  docBase="webapps/test"
Context log: path="/jsp" Adding context path="/jsp"  docBase="webapps/jsp/"

Now, when you point your browser to the URL http://localhost/jsp/hello.jsp, you should see the file being rendered correctly.

You can add as many contexts as you like, using the format above - however, these will always be one level below the server's document root. If you'd like to run JSP files from the document root itself, you should place them in the "webapps/ROOT" folder. For example, if the file "hello.jsp" was located in "webapps/ROOT", I would be able to access it via the URL http://localhost/hello.jsp.

If you're really picky, you can define an alternate location for the root folder by creating a new context - as the following example demonstrates:

 <Context path="/" docBase="webapps/my/new/server/root" debug="0"
reloadable="true" >
 </Context>

For more information on contexts, and how to tweak them for maximum performance, take a look at the Tomcat User Guide at http://jakarta.apache.org/tomcat/jakarta-tomcat/src/doc/uguide/tomcat_ug.html, and the Tomcat-Apache HOWTO at http://jakarta.apache.org/tomcat/jakarta-tomcat/src/doc/tomcat-apache-howto.html

Making The Grade

If you plan to use JSP to communicate with a database using a JDBC connection, there are a couple of additional things you need to do.

First, get yourself a copy of the mm.mySQL module from http://www.worldserver.com/mm.mysql/ or http://mmmysql.sourceforge.net/ - this is required to communicate with the database. Extract the file "mysql.jar" from the archive, and place it in your JDK's LIB/ folder.

Next, add the location of this file to the CLASSPATH variable. On Windows, use

C:\> SET CLASSPATH=%CLASSPATH%;C:\JDK\LIB\MYSQL.JAR

and on Linux, use

$ CLASSPATH=$CLASSPATH:/usr/local/jdk/lib/mysql.jar; export CLASSPATH

Pop open your favourite text editor and create the following JSP file:

 <html>
 <head>
 </head>
 <%@ page language="java" import="java.sql.*" %>
 <body>
 <%
  Class.forName("org.gjt.mm.mysql.Driver");

  //assume database "test", user "root", password ""
 // change this as per your requirements
  Connection myConn =
DriverManager.getConnection("jdbc:mysql://localhost/test?user=root&password=
");

  Statement stmt = myConn.createStatement();

  // assume you have a "grades" table with
  // grades is various subjects and student names
  // change this as per your requirements
  String query = "select * from grades where literature >  90";

  ResultSet myResultSet = stmt.executeQuery(query);

  if (myResultSet != null) {
    while (myResultSet.next()) {
      // specify the field name
      String name = myResultSet.getString("name");

%>
 <%= name %>
 <br>
 <%
    }
  }

  stmt.close();

  myConn.close();
%>
 </body>
 </html>

This is a simple JSP file to connect to a database, run a query and return the results. Remember to modify the database name, user details and query in the example above before proceeding.

Finally, start up Tomcat, Apache and mySQL. Point your browser to the file you just created - say, http://localhost/examples/jsp/query.jsp and JSP should display the results of your query.

And that's it. You now know how to set up a JSP development environment with minimum fuss and effort. Now get out there and show those kids how the pros do it!

Note: All examples in this article have been tested on Windows 95 and Red Hat Linux 7.0, with JDK 1.3, Apache 1.3.14, Tomcat 3.2, JServ 1.1.1 and mm.mysql 1.0. Examples are illustrative only, and are not meant for a production environment. YMMV!

This article was first published on31 Jan 2001.