JServ 1.1.2

JServ is an 'open source' servlet runner

Installation Instructions

1. First you need to download Apache JServ. It's available from http://java.apache.org/. The version used in this tutorial is 1.1.2.

2. Make sure you have a Java Runtime Environment. i.e. that you can run Java programs on your machine! JREs for many platforms are freely available from: http://java.sun.com/cgi-bin/java-ports.cgi

3. Make sure you have a copy of Sun's Java Servlet Development Kit v2.0, freely available from: http://java.sun.com/products/servlet/archive.html.

   The version of JServ used in this tutorial needed exactly the 2.0 version.

4. The only files you need from Apache JServ distribution are:

   ApacheJServ-1.1.2/src/java/ApacheJServ.jar
   ApacheJServ-1.1.2/conf/jserv.properties.in
   ApacheJServ-1.1.2/conf/zone.properties.in
   

   We are going to install JServ in /usr/local/jserv in this example:

   $ mkdir /usr/local/jserv
   $ cd ApacheJServ-1.1.2
   $ cp src/java/ApacheJServ.jar /usr/local/jserv
   $ mkdir /usr/local/jserv/conf
   $ cp conf/jserv.properties.in /usr/local/jserv/conf/jserv.properties
   $ cp conf/zone.properties.in /usr/local/jserv/conf/zone.properties
   

5. Now we need to edit the config files we have put in /usr/local/jserv/conf.

   First, edit jserv.properties. This file contains various global settings for the JServ servlet runner. You may need to alter the settings in here to suit your environment.

   In this example, the only alterations we made were:

   wrapper.bin=@JAVA@
     => wrapper.bin=/usr/local/jdk1.2.2/bin/java
   
   wrapper.classpath=@JSERV_CLASSES@
     => wrapper.classpath=/usr/local/jserv/ApacheJServ.jar
   
   wrapper.classpath=@JSDK_CLASSES@
     => wrapper.classpath=/usr/local/JSDK2.0/lib/jsdk.jar
   
   root.properties=@JSERV_CONF@/zone.properties
     => root.properties=/usr/local/jserv/conf/zone.properties
   
   log.file=@JSERV_LOG@/jserv.log
     => log.file=/tmp/jserv.log
   

   Now edit zone.properties. This zone file defines settings for all the servlets in a particular zone, such as where the servlets should be found on disk. JServ can be setup to run with multiple zones, generally you have one per virtual server. In this example, we only have one zone defined in the jserv.properties file called "root", and we have set the "root.properties" value to point to the zone.properties file we are now editing. For more information on zones, check out the JServ documentation on the JServ website.

   In our example, all we are going to do to the zone.properties file is alter the repositories line to define where our servlets will live on disk. (/usr/local/jserv/servlets in our case).

   So we set

   repositories=/usr/local/jserv/servlets
   

   and we create the directory /usr/local/jserv/servlets.

6. We are now ready to start up the JServ servlet runner. The servlet runner is started independently of Zeus Server. JServ need not be run on the same machine as the web server, as Zeus can communicate with JServ over the network. In our example, we have the Java Runtime Environment installed in /usr/java, so the Java interpreter is accessed as /usr/java/bin/java. We have also copied the jsdk.jar file from Sun's Java Servlet Development kit that was downloaded in step 2, to /usr/local/jserv/jsdk.jar.

   $ cd /usr/local/jserv
   $ export CLASSPATH=jsdk.jar:ApacheJServ.jar
   $ /usr/java/bin/java org.apache.jserv.JServ conf/jserv.properties
   

   JServ should now startup, and print out a version number:

   ApacheJServ/1.1.2
   

   To run the program in the background, you should append a & to the command above.

7. Now JServ is setup and running, we can configure Zeus Web Server to communicate with it.

   In the Zeus Admin Server, choose a virtual server. Go to the Java Servlets configuration page, listed under API Support in the menu bar. Make sure Java Servlet support is enabled by clicking the radio button at the top of the page.

   The out-of-the-box JServ configuration works with the following settings:

   Directory: /jserv
   Machine name: localhost
   
   Port: 8007
   Servlet context: root
   Protocol: ajpv12
   

   Fill these in and click on "Apply changes". After you commit your changes, a URL beginning with a prefix of /jserv will cause the web server to forward the request onto the JServ runner.

8. Now we are ready to access servlets from our web server.

   

   First, try to access the internal status servlet in JServ. For example, if your website runs on http://www.mysite.com/, access the URL http://www.mysite.com/jserv/org.apache.jserv.JServ.

   This should bring up a web page showing the current status of the servlet engine and servlet zones defined. This servlet can be disabled in the jserv.properties file

   

   To run your own servlets, follow these steps. For an example we will use SnoopServlet.

   From the JSDK distribution you downloaded in step 3, copy the SnoopServlet.class file from the examples/ directory into /usr/local/jserv/servlets.

   Now access /jserv/SnoopServlet, from the URL http://www.mysite.com/jserv/SnoopServlet.

   

   This should run Sun's example servlet and display various information about the servlet environment in your browser.

   Several other example servlets are shipped with the JSDK, including SimpleServlet and SessionServlet:

   

You are now ready to write your own servlets! It is highly recommended that you read through the JServ documentation as there are many powerful and configurable features you may wish to use.

Content Manager [Administrator] 14 December 2005