Chapter 18. mod_jserv and Tomcat

mod_jserv uses GNU make, which is incompatible with all other known make s. So, you may need to get (from http://www.gnu.org/software/make/make.html) and build GNU make before starting. If you do, here's how we did it.

Since you probably already have a perfectly good make, you don't want the new one to get mixed up with it. Just for safety's sake, you might want to back up your real make before you start.

Create a directory for the sources as usual, unpack them, and make gmake (cunningly not called make) with the commands:

./configure --program-prefix=g
make
make install

You should end up with /usr/local/bin/gmake.

Having created gmake, move to the mod_jserv source directory. Before you start, you need to have compiled Apache so that JServ can pass its configure checks. If you have got this far in the book, you probably will already have compiled Apache once or twice, but if not — now is a good time to start. Go to Chapter 1.

You then need to decide whether you want to build it into the Apache executable (recommended) or prepare it as a DSO. We took the first route and configured mod_jserv with this:

MAKE=/usr/local/bin/gmake ./configure --prefix=/usr/local --with-apache-src=/usr/src/
apache/apache_1.3.19 --with-jdk-home=/usr/src/java/jdk1.1.8 --with-JSDK=/usr/src/
jsdk/JSDK2.0/lib

Your paths in general will be different. --prefix invokes the location where you want the JServ bits to be put. Rather perversely, they appear in the subdirectory .../etc below the directory you specify. You might also think that you were required to put /src on the end of the Apache path, but you're not. If the process fails for any reason, take care to delete the file config.cache before you try again. You might want to write the necessary commands as a script since it is unlikely to work at the first attempt:

rm config.cache
MAKE=/usr/local/bin/gmake ./configure --prefix=/usr/local/bin --with-apache-src=/usr/src/
apache/apache_1.3.19 --with-jdk-home=/usr/src/java/jdk1.1.8 --with-JSDK=/usr/src/
jsdk/JSDK2.0/lib > log

If you use mod_ssl, you should add --enable-EAPI. The script's voluminous comments will appear in the file log; error messages will go the screen. Any mistakes in this script can produce rather puzzling error messages. For instance, on our first attempt we misspelled --with-JSDK as --with-JDSK. The error message was:

checking JSDK ... configure: error: Does not exist:
    '/usr/local/JSDK2.0

which was true enough. Yet it required a tour through the Configure file to realize that the script had failed to match --with-JDSK, said nothing about it, and had then gone to its default location for JSDK.

When ./configure has done its numerous things, it prints some sage advice on what to do next, which would normally disappear off the top of the screen, but which you will find at the bottom of the log file:

+-STEP 1-------------------------------------------------------+
|Run 'make; make install' to make a .jar file, compile the C   |
|code and copy the appropriate files to the appropriate        |
|locations.                                                    |
+--------------------------------------------------------------+

+-STEP 2-------------------------------------------------------+
|Then cd /usr/src/apache/apache_1.3.19 and run 'make; make install'
+--------------------------------------------------------------+

+-STEP 3-------------------------------------------------------+
|Put this line somewhere in Apache's httpd.conf file:          |
|Include /usr/src/jserv/ApacheJServ-1.1.2/etc/jserv.conf
|                                                              |
|Then start Apache and try visiting the URL:                   |
|http://my586.my.domain:SERVER_PORT/servlets/Hello
|                                                              |
|If that works then you have successfully setup Apache JServ.  |
|                                                              |
|If that does not work then you should read the                |
|troubleshooting notes referenced below.                       |
+--------------------------------------------------------------+

+-Troubleshooting----------------------------------------------+
|Html documentation is available in the docs directory.        |
|                                                              |
|Common Errors:                                                |
|    Make sure that the log files can be written to by the     |
|    user your httpd is running as (ie: nobody). If there are  |
|    errors in your configuration, they will be logged there.  |
|                                                              |
|Frequently asked questions are answered in the FAQ-O-Matic:   |
|                                                              |
|           http://java.apache.org/faq/                        |
+--------------------------------------------------------------+

You should carry on with:

gmake

Then:

gmake install

Now go to /usr/src/apache/apache_1.3.19 (or whatever your path is to the Apache sources). Do not go down to the src subdirectory as we did originally. Then:

./configure --activate-module=src/modules/jserv/libjserv.a
make
make install

We saw some complaints from make. This time the comments are output to stderr. You can capture them with:

 make install &> log2. 

The comments end with:

+--------------------------------------------------------+
| You now have successfully built and installed the      |
| Apache 1.3 HTTP server. To verify that Apache actually |
| works correctly you now should first check the         |
| (initially created or preserved) configuration files   |
|                                                        |
|   /usr/local/etc/httpd/httpd.conf
|                                                        |
| and then you should be able to immediately fire up     |
| Apache the first time by running:                      |
|                                                        |
|   /usr/local/sbin/apachectl start
|                                                        |
| Thanks for using Apache.       The Apache Group        |
|                                http://www.apache.org/  |
+--------------------------------------------------------+

This is not very helpful because:

• The Config file is a variant of the enormous Apache "include everything" file which we think is confusing and retrograde.

• The Config file actually said nothing about JServ.

• The command /usr/local/sbin/apachectl start didn't work because Apache looked for the Config file in the wrong place.

But, in our view, building the executable is hard enough; one shouldn't expect the installation to work as well. The new httpd file is in .../src. Go there and check that everything worked by typing:

./httpd -l

A reference to mod_jserv.c among the "compiled-in modules" would be pleasing. Remember: if you forget ./, you'll likely run the httpd in /usr/local/bin, which probably won't know anything about JServ.) We then copied httpd to /usr/local/sbin/httpd_jserv.

If it is there, you can proceed to test that it all works by setting up site.jserv (a straight copy of site.simple) with this line in the Config file — making sure that the path suits:

Include /usr/local/bin/etc/jserv.conf

Finally, start Apache (as /usr/local/sbin/httpd_jserv), and visit http://www.butterthlies.com/servlets/Hello. You should see something like this:

Example Apache JServ Servlet
Congratulations, ApacheJServ 1.1.2 is working! 

Sadly, the Earth didn't quite move for both of us. Ben's first attempt failed. The problem was that his supplied jserv.conf was not quite set up correctly. The solution was to copy it into our own configuration file and edit it appropriately. The problem we saw was this:

Syntax error on line 43 of /usr/local/jserv/etc/jserv.conf:
ApJServLogFile: file '/home/ben/www3/NONE/logs/mod_jserv.log' can't be opened

We corrected this to be a sensible path, and then Apache started. But attempting to access the sample servlet caused an internal error in Apache. The error log said:

java.io.IOException: Directory not writable: //NONE/logs
    at org.apache.java.io.LogWriter.<init>(LogWriter.java:287)
    at org.apache.java.io.LogWriter.<init>(LogWriter.java:203)
    at org.apache.jserv.JServLog.<init>(JServLog.java:92)
    at org.apache.jserv.JServ.start(JServ.java:233)
    at org.apache.jserv.JServ.main(JServ.java:158)

We had to read the source to figure this one out, but it turned out that /usr/local/jserv/etc/jserv.properties had the line:

log.file=NONE/logs/jserv.log

presumably for the same reason that jserv.conf was wrong. To fix this we took our own copy of the properties file (which is used by the Java part of JServ) and changed the path. To use the new properties file, we had to change its location in our httpd.conf:

ApJServProperties /usr/local/jserv/etc/jserv.properties

This still didn't cure our problems. This time the error appeared in the jserv.log file we've just reconfigured earlier:

[28/04/2001 11:17:48:420 GMT] Error creating classloader for servlet zone root :
java.lang.IllegalArgumentException: Repository //NONE/servlets doesn't exist!

This error relates to a servlet zone, called root — this is defined in jserv.properties by two directives:

zones=root
root.properties=/usr/local/jserv/etc/zone.properties

So now the offending file is zone.properties, which we copied, changed its location in jserv.properties, and corrected:

repositories=NONE/servlets

We changed this to point at the example directory in the source of JServ, which has a precompiled example servlet in it, in our case:

repositories=/home/ben/software/unpacked/ApacheJServ-1.1.2/example

and finally, surfing to the Hello server (http://your.server/servlets/Hello) gave us a well-deserved "congratulations" page.

JServ has its own Apache directives, which are documented in the jserv.conf file.

ApJServManual [on/off]
Default: "Off"

ApJServProperties [filename]
Default: "./conf/jserv.properties"

ApJServLogFile [filename] 
Default: "./logs/mod_jserv.log"

ApJServLogLevel [debug|info|notice|warn|error|crit|alert|emerg]
Default: info    (unless compiled w/ JSERV_DEBUG, in which case it's debug)

ApJServDefaultProtocol [name]
Default: "ajpv12"

ApJServDefaultHost [hostname]
Default: "localhost"

ApJServDefaultPort [number]
Default: protocol-dependant (for ajpv12 protocol this is "8007")

ApJServVMTimeout [seconds] 
Default: 10 seconds

ApJServProtocolParameter [name] [parameter] [value]
Default: NONE

ApJServSecretKey [filename]
Default: "./conf/jserv.secret.key"

ApJServMount [name] [jserv-url]
Default: NONE

ApJServMountCopy [on/off]
Default: "On"

ApJServAction [extension] [servlet-uri]
Defaults: NONE

Enable the Apache JServ status handler with the URL of http://servername/jserv/ (note the trailing slash!). Change the deny directive to restrict access to this status page:

Now that we have JServ running, let's add a little servlet to it, just to show how its done. Of course, there's already a simple servlet in the JServ package, the Hello servlet mentioned earlier; the source is in the example directory, so take a look. We wanted to do something just a little more interesting, so here's another servlet called Simple, which shows the parameters passed to it. As always, Java requires plenty of code to make this happen, but there you are: