JServ 0.9.12 How Do I...

This document attempts to explain how to perform various tasks with JServ 0.9.12. It is intended as a reference.

Installation
Administration
Configuration
Development
1. work with Sessions

Installation

compile mod_jserv.c.into Apache
test my JServ installation: See the INSTALL file for detailed instructions on both of these issues.

decide between Manual and Automatic mode

We suggest using Manual mode in these cases:

You are familiar with JServ, and want to start and stop the JVM independant of Apache.
Want to run the JVM as a user other than the one Apache runs as (perhaps to prevent rogue CGIs from killing the VM).
Want to use the load balancing features of JServ.

Otherwise we suggest Automatic mode, since it prevents the need for a separate startup script.

using JSDK 2.0: If you wish to use Apache JServ 0.9.12-rc1 with JSDK 2.0, you will need to recompile the JServ classes, using the jsdk.jar file which comes with JSDK 2.0. Apache JServ 0.9.12-rc1 is does not implement the JSDK 2.1 specification, but it does implement the 2.0 specification.
Sun's licensing terms prevent us from distributing JServ w/ JSDK 2.0.

Administration

start/stop JServ in Manual mode

First, customize the jserv.init script in JServ's manual/ directory to suite your needs. Usually this simply involves setting the JSERV_HOME, JAVA_HOME, and CLASSPATH environment variables.

This script can be invoked with start or stop as an argument.

Note that this script assumes that $JSERV_HOME/logs exists, as it will use this directory to log STDERR/STDOUT from the VM, and to write out JServ's PID file. Make sure it exists, and is writable by the user that you run JServ as.

We suggest that you copy this file into the directory where startup scripts go (/etc/rc.d/init.d for Linux), and create the necessary sym links so that the file is executed when your machine boots.

start/stop JServ in Automatic mode: There is no need for a separate jserv.init script when running JServ in Automatic mode, since these functions are performed by Apache itself. We assume that you already have an analogous init script to start and stop Apache, and these will in turn start and stop JServ.
To restart JServ, simply send a kill -HUP to Apache's PID. However, if you wish to restart JServ's Java process without affecting any httpd processes, you can do a kill [jvm pid]. Apache will observe this, and automatically spawn a new JVM. The downside to this method is that JServ will not call destroy() on its servlets before exiting, and any requests in progress will be immediately killed.

rotate JServ's logs

If you are running JServ in Manual mode, the jserv.init file will send STDERR/STDOUT from the VM to $JSERV_HOME/logs/jserv.log

If you are running JServ in Automatica mode, you can specify where you want STDERR/STDOUT redirected with the ServletErrorLog directive.

To rotate logs in Automatic mode:

Move the old log to your archive directory: mv $JSERV_HOME/logs/jserv.log /www/logs/old.jserv.log
kill -HUP [apache PID] - This will restart JServ, and refresh the filehandle to ServletErrorLog

To rotate logs in Manual mode:

Move the old log to your archive directory: mv $JSERV_HOME/logs/jserv.log /www/logs/old.jserv.log
```
jserv.init stop
jserv.init start
	    
```
This is necessary because the jserv.log file is owned by the parent shell script, and won't refresh from a kill -HUP.

Configuration

know what to put in Apache's srm.conf file: See the INSTALL file's 'Automatic Mode' section for an example set of directives to get you started.
Once you have a working installation, see the INSTALL file's 'Available Apache Directives' section for a list of all valid Apache directives, and a description of how to use them.

bind a servlet to a file extension

If you wish to use JServSSI to embed <servlet> tags, or GSP or GnuJSP as a page compiler, then you'll need to bind a servlet to a file extension. Here's an example.

#
# Add this to Apache's srm.conf
#
# Example for GNU Server Pages
# binds all  .gsp pages to the GspServlet
ServletAlias /gspservlet  /path/to/gsp.jar
AddHandler   gsp-handler  .gsp
Action       gsp-handler  /gspservlet/gsp

# 
# add this to the servlet properties file for this virtual host
#
# Make sure that 'gsp' is a valid servlet in your servlet.properties file
servlet.gsp.code=com.bitmechanic.gsp.GspServlet
servlet.gsp.initArgs=propfile=/path/to/gsp.properties

Once you've got this setup, any URLs ending in the bound file extension will be picked up by JServ and passed off to the appropriate servlet. Note that this works with DirectoryIndex as well, so you can say:

DirectoryIndex index.html index.cgi index.gsp

So requests to /foo/ will match /foo/index.gsp if it exists.

configure servlets to reload when modified

JServ will automatically reload a Servlet when it changes if you do the following two things:

Add the directory the servlet resides in to the jserv.<hostname>.repository property in your General Properties file
Remove the directory from the system CLASSPATH by removing any ServletClassPath directives pointing at this directory (Automatic mode), or removing it from the CLASSPATH environment variable in the script that starts JServ (Manual mode)

Here is an example Automatic mode configuration:

Let's say you want JServ to automatically reload modified Servlets in:
/home/pixel/web1/classes 

##############################################
#
# in srm.conf:
#
#
# we keep this line in so JServ still knows to load servlets for this alias
ServletAlias /servlets /home/pixel/web1/classes
ServletAlias /jserv    /home/pixel/web1/classes/jserv-0.9.12.jar
ServletPort 8007
ServletClassPath /usr/local/java/lib/classes.zip
ServletClassPath /home/pixel/bitmechanic/jserv/servclasses.zip
ServletClassPath /home/pixel/web1/classes/jserv-0.9.12.jar
#
# we comment this line out so that it's not in the system classpath
#ServletClassPath /home/pixel/web1/classes
ServletBinary /usr/local/java/bin/java
ServletProperties conf/servlet.properties
ServletGeneralProperties conf/jserv.properties
ServletErrorLog logs/jserv_errors.log
#
############################################################

############################################################
#
# in conf/jserv.properties we add:
#
jserv._default_.repository=/home/pixel/web1/classes

setup servlets on different virtual hosts

Create a General Properties file that contains a colon separated list of the hostnames that will be using JServ.

#
# In General Properties file (typically named jserv.properties)
#
# virtual hosts using JServ
jserv.hosts=www.bitmechanic.com:sumo.bitmechanic.com:ninja.bitmechanic.com

Add jserv.<hostname>.properties and jserv.<hostname>.repository entries for each hostname to the same General Properties file.

#
# in the same jserv.properties file as above
#
jserv.www.bitmechanic.com.properties=/www/conf/bitmechanic.properties
jserv.www.bitmechanic.com.repository=/www/reloadable/www.bitmechanic.com

jserv.ninja.bitmechanic.com.properties=/www/conf/ninja.properties
jserv.ninja.bitmechanic.com.repository=/www/reloadable/ninja.bitmechanic.com

jserv.sumo.bitmechanic.com.properties=/www/conf/sumo.properties
jserv.sumo.bitmechanic.com.repository=/www/reloadable/sumo.bitmechanic.com

Create a separate Servlet Properties file for each of the hosts. These are the filenames specified in each jserv.<hostname>.properties directive above.
This enables you to have different servlet configurations, session lifetimes, and classpaths for each virtual host.
See the INSTALL file for a complete list of valid properties for both the General and Servlet Property files.
Configure JServ to load the General Properties file.
In Automatic mode, add a ServletGeneralProperties directive to your srm.conf file:
```
ServletGeneralProperties conf/jserv.properties
```
In Manual mode, set the JSERV_PROPERTY_FILE environment variable in the shell script that starts JServ:
```
JSERV_PROPERTY_FILE=/local/jserv/conf/jserv.properties
export JSERV_PROPERTY_FILE
```

create an alias for a servlet

In the INSTALL file, we suggest that you test JServ by requesting: /jserv/org.apache.jserv.JServServlet

But sometimes you don't want to reference a Servlet by its full package name. You want to create an alias. To add an alias, edit the Servlet Properties file for this host and add:

#
# format:
servlet.aliasname.code=full class name
servlet.aliasname.initArgs=arg1=value1,arg2=value2

#
# example for JServServlet.  if you had
#    ServletAlias /jserv /path/to/jserv-0.9.12.jar
#
# then you could request this servlet by accessing:
#
# http://yourhost.com/jserv/jservtest
#
servlet.jservtest.code=org.apache.jserv.JServServlet
servlet.jservtest.initArgs=

Development

work with Sessions

javax.servlet.http.HttpSession can be thought of as a Hashtable unique to each user that you can store arbitrary objects in between requests. Since this data is stored in RAM, reading and writing to it is very quick. However, don't go overboard or you'll run out of RAM in the VM. In addition, it is up to the servlet author to make sure that data stored in sessions gets persisted to disk somewhere, since this data will be lost if the JVM is restarted.

To use a Session, you simply call:

//
// In the service() method of a servlet
//
// this will create a new session if one doesn't exist for this user
HttpSession session = request.getSession(true);

When a session is created, JServ will send a cookie to the browser. If the user accepts the cookie, JServ will automatically return the correct session for that user on subsequent requests.

If you don't want to rely on cookies, you must rewrite all URLs on the page to include the user's session ID. the HttpServletResponse.encodeURL() method should be used in these cases.

As of 0.9.12, JServ supports configurable cookie lifetimes. Set the jserv.cookie.lifetime property in your Servlet Properties file. See the INSTALL document for more details on syntax. If this is set then the JServ session cookie will persist after the user exits their browser. By default the cookie is transient, so the user will be assigned a new session ID each time they start their browser.

Set jserv.session.lifetime to have JServ expire sessions that have gone unaccessed for a period of time. See the INSTALL document for details on syntax. If this property is not present, the servlets must manage session expiration manually.