How to install Apache JServ on win32 systems

Introduction

This section guides you through the installation process for win32 systems in the case you didn't use the self-installation typical mode or in case you did so but something went wrong and you choose the custom installation which doesn't automatically connect Apache JServ with the Apache Web Server.

Requirements

The following requirements exist for building Apache JServ:

Disk Space

The complete Apache JServ installation requires less than 2Mb of hard disk space. The compiled, not-compressed jar archive is more or less 100Kb.

Apache HTTP Server

Apache JServ works only with the Apache HTTP Server 1.3.1 or higher. (latest version is highly recommended).

Java Runtime Environment

A fully compliant Java 1.1 Runtime Environment is required for Apache JServ to execute. The official list of compatible ports is found on the JavaSoft web site.

Note: since Apache JServ uses only standard Java APIs (java.*), please, do not submit a bug report if your Java virtual machine fails to execute Apache JServ because of broken compliance. Send it to your Java virtual machine implementers.

Java Servlet Development Kit 2.0

The JavaSoft JSDK 2.0 is required by Apache JServ for proper servlet execution. This package is freely available from the JavaSoft web site (http://java.sun.com/products/servlet/index.html)

Note: this version of Apache JServ requires exactly the specified version of the JSDK in order to operate properly. Any other version (past, present or future) is not supported.

Java Compiler

Since the distribution include the precompiled Java binary archive, compilation of the Java source is optional.

Note: a Java compiler is needed to build servlets if you plan to write your own.

C Compiler

Even if win32 distribution comes with precompiled binaries, the mod_jserv module and the native wrapper need a C compiler in order to operate correctly. Currently only Microsoft Visual C++ (version 5.0 or higher) is supported.

Overview

The Apache JServ servlet engine is composed by two main parts, the servlet engine server application (written in 100% pure Java) and the web server module (mod_jserv, written in C). This module is communication layer that allows the web server to request servlets to the servlet engine.

Even if many different ways of installing Apache JServ exist, in this section we concentrate to the basic installation (called integrated or automatic mode) where the servlet engine process is spawned and controlled by the web server itself and, consequently, both the web server and the servlet engine share the same system resources.

This document assumes you have your Apache Web Server already installed and configured.

Installing the servlet engine

The servlet engine is a 100% pure Java server application with its own configuration files. jserv.properties is the main configuration file while zone.properties is an example servlet zone configuration file (see the servlet zone howto for more info on servlet zones). You need to edit a few directives in the jserv.properties file to let the JVM spawner (either the module or the wrapper) where to find things.

These are the properties you should edit:

wrapper.bin=@JAVA@ (the name of the JVM interpreter, absolute if not in PATH)

wrapper.classpath=@JSERV_CLASSES@ (the path to ApacheJServ.jar)
wrapper.classpath=@JSDK_CLASSES@ (the path to jsdk.jar)

root.properties=@ZONE_CONF@ (the path to ./conf/zone.properties)

log.file=@JSERV_LOG@ (the path to ./logs/jserv.log)

Installing the web server module

The Apache web server communicates with the servlet engine using the Apache JServ module named ApacheModuleJServ.dll (found in the \bin\c directory of the distribution). This file must be copied under the \modules directory of your existing Apache installation.

After you have copied the file in the module directory, you should append the configuration template file \conf\httpd.conf to your existing Apache configuration file (usually httpd.conf). This template helps you configure the module and the web server.

The first thing to do is to uncomment the loadmodule directive to let Apache know about the new module

# Tell Apache on win32 to load the Apache JServ communication module
LoadModule jserv_module modules/ApacheModuleJServ.dll

After this, you should specify the servlet engine configuration file (usually jserv.properties) and the module log file with the directives

ApJServProperties <full path to ./conf/jserv.properties>
ApJServLogFile <full path to ./logs/jserv.module.log>

The log file will be created if not existing or logs will be appended to an existing file.

Checking the installation

You are ready to test your Apache JServ installation: simply run the Apache Web Server and request the URL http://127.0.0.1/jserv/.

If the web server returns a File not found error code, this means that your module is not properly installed or that you disabled the jserv-status handler. Otherwise you see the dynamic Apache JServ configuration pages that show you the status of your servlet environment.

The page you are seeing is created by the ApacheModuleJServ.dll module. To see if the servlet engine is working, go to the servlet engine section and follow the link. If everything is successful, you see the dynamic page generated by Apache JServ showing his configurations, otherwise, if you get an internal server error, this means your servlet engine is not working.

Troubleshooting

If you get an internal server error while connecting to the servlet engine, you should check your log files for problems.

If the jserv.log file was not created this means that Apache JServ did not even start. Usually this is due to a dirty or broken classpath passed to the spawned virtual machine. Check out the jserv.module.log file and the Apache error.log file for clues on what the problem is. Just to make sure, you could try using absolute paths instead of relative ones because the different processes may see different working directories.

When the classpath is correct and Apache JServ starts, the jserv.log file is created. Look at that file for description of eventual other problems.

Installing servlets

After your servlet engine is up and running, you need to install your servlets. To do this you need to learn about servlet zones and their usage. Later on, more advanced users may want to learn how to secure their servlets and servlet engines.