$Id: INSTALL.apache,v 1.9 1999/10/13 10:06:15 alph Exp $

This is short guide for installing gnujsp 1.0 on apache 1.3.x
using jserv 1.0, jsdk 2.0 (for jserv 1.0).

Note: Former versions of this document referenced servlet.jar from
jswdk 2.1. This file is not longer needed, instead servlet-2.0-plus.jar
from "FIXME: add source url here" which is included in the lib
diectory will be used now.

Apocryphal note from Wes:
This should work on JServ 0.9.11 as well, with the following lines added 
to srm.conf:
AddHandler jsp-handler .jsp
Action jsp-handler /servlet/gnujsp

You need:
	- apache 1.3.x
	- jserv 1.0
	- jsdk 2.0 for jserv 1.0
	- servlet-2.0-plus.jar (in the GNUJSP distribution)
	- jdk 1.1.7 or newer (I didn't tried 1.2 but heard about problems
	  and success, so you may try on your own.)
	- jar-File for gnujsp 1.0 (o.k. since you read this you
	  most probably have it already)

!!!!!!!!
!!!
!!! Note: Instead of servlet-2.0-plus.jar you may continue to use 
!!        servlet.jar from JSWDK 1.0 if you used it before! 
!!!       But the following does NOT work: 
!!!          - servlet.jar from jsdk2.1
!!!          - jsp.jar/servlet.jar from jswdk 1.0 EA
!!!
!!!!!!!!

If it dosn't work for you or if I miss something or my
(mis)use of the english language drives you crazy, send me
a note to alph@gjt.org or to the list gnujsp@gjt.org.

This configuration is running on SuSE/GNU Linux 6.2, Apache 1.3.6, JDK 1.1.7.
If you have extra notes regarding a Windows installatio,
write them down and send them to me. 

The servlets are mapped on "/alph" so if you prefer
another solution you have to replace "alph" with your choice.
You can put it in whatever zone you want as long
as the necessary parameters are in there!

I wanted to keep it short, but it grow ...
if it's too short feel free to ask!
I put all configuration files into the apache "conf" directory.
I assume you installed jserv 1.0 and the example servlets work
for you, if you need help in setting that running, try to ask but
for basic jserv installation you should check the jserv FAQ
and the jserv mailing list.

In each step I explain:	
	- what to do
	- why to do that
	- how to do

Step 1 - Install a new servlet zone
===================================

Each zone has it's own policy
from where to load servlets and how to keep them,
doing auto reloading of classes if they change, etc.

We call our new zone "alph".

Copy the example properties file from apache and name it
"alph.properties".

Now tell apache
	a) where to find class files (this means beans and
           classes needed to run our servlets) when RUNNING (in
           opposite to compiling) the jsp page

	   servlet-2.0-plus.jar 
			jsdk 2.0 servlet classes + base jsp stuff
			if you put it in the classpath after jsdk20.jar
			the servlet classes won't be used and don't
		        harm. 

	   gnujsp10cvs.jar or gnujsp10.jar
			jar file containing current GNUJSP version

	   jdbcbeans
			a directory where I develop some beans
                      	since they change, putting them here will auto
	              	reload them. Later they will we put in a jar file.

	b) I'm doing development, so let apache care for autoreloading if
	   things change. (Note: If you have a pointer to a bean
	   stored somewhere in the running virtual machine and you
	   change your bean class, don't expect the existing (!) bean
	   to change it's class magically. It's for new instances.)

	c) I prefer to use aliases instead of classes so I
           only need to change at one place e.g. if I prefer to
	   change one gnujsp against another version.
	   So we create an alias for gnujsp and give it some
	   init args it needs.
		- 'pagebase' to know where our web servers
                  document root is. Needed on jserv 1.0, didn't
	          tried newer versions.

		- 'scratchdir' is where gnujsp put's generated java/class
	          files
		  (Note: please don't store your own beans here,
                         a later version of gnujsp 1.0 may feel to
	                 cleanup that directory if feeling it needs to ...)

	        - 'checkclass=true' so jsp pages are not
	          always recompiled if restarting JspServlet

		- debug is for filling log files, keep it
	          out or note it in a comment until you need it

	        - compiler is the command used to compile
                  java server pages. This version uses the builtin
	          sun compiler from the jdk and sets the classpath
                  for COMPILATION (in opposite to running the jsp
		  page, see repository above.)
.
                  We need	
			* the original classpath of the jserv
                          virtual machine for basic stuff
                          (that means wrapper.classpath!)
                        * the repository (the java code of our jsp
                          pages and the class files reside here)
                        * gnujsp 1.0 for misc stuff
			* servlet-2.0-plus.jar for basic jsp classes
			* access to your beans dir (often missed by newbies!)
                  
                  "-d" tells the compiler where to store generated classes
	          "-deprecation" tells about using deprecated APIs and 
		  finally "%source" is replaced by the name of the java source
                  file generated from your jsp page.

           This is the list of args I'm using for development,
	   tahe a look at the complete list in the other docs.

           I may have added servlet-2.0-plus.jar or even
	   gnujsp10cvs.jar to the classpath of the
           wrapper instead of using it in repository and initArgs
	   but I try to keep the wrapper classpath small to avoid
	   conflicts with other servlet zones.

Make the following changes (Note: I removed most of
the comments here for clarity.)

File: alph.properties

# List of Repositories
#######################

repositories=/usr/local/gnujsp-1.0cvs/lib/gnujsp10cvs.jar
repositories=/usr/local/gnujsp-1.0cvs/lib/servlet-2.0-plus.jar
repositories=/home/heyl/test/java/jdbcbeans
#repositories=/home/heyl/lib/java/Acme.jar
#repositories=/usr/local/webl-3.0/lib/WebL.jar

# Classloader parameters
#########################

autoreload.classes=true

# Enable servlet resourced autoreloading (properties and other 
# loaded resources)
autoreload.file=true

...

# Servlet Aliases
##################
# Note: if using webl or Acme stuff, add the jars here too
# if you added them to the repositories above (alph)
# In my real settings I added: usepackages=true,language=de,country=de
# but I guess you may prefer the default locale :-) (alph)

servlet.gnujsp.code=org.gjt.jsp.JspServlet
servlet.gnujsp.initArgs=checkclass=true,pagebase=/usr/local/www/doc,scratchdir=/var/local/apache/jsp,debug=true,compiler=builtin-javac -classpath %classpath%:%scratchdir%:/usr/local/gnujsp-1.0cvs/lib/servlet-2.0-plus.jar:/usr/local/gnujsp-1.0cvs/lib/gnujsp10cvs.jar:/home/heyl/test/java/jdbcbeans -d %scratchdir% -deprecation %source%


Step 2 - Tell jserv about alpl zone
===================================

Now lets tell jserv that we just invented an "alph" zone and want it to
be served under the same name.
(all servlets contained in the zone will be servede as "/alph/<servlet>",
e.g. "/alph/gnujsp"). I keep the CLASSPATH small to avoid
conflicts with different servlet zones. You may put other STATIC (!)
jar-Files here. You have to restart jserv if you change their content.
classes.zip may be only needed on linux, I didn't checked that.
Note that I didn't put servler-2.0-plus.jar here, see above for explanation.)   
Make sure the following is in 

File: jserv.properties

# Uncomment the following line is you encounter mysterious 
# ClassNotFoundExceptions that you can't explain.
# The "-v" Parameter may show the problem. The java runtime environment
# says "ClassNotFoundException: xx.class" if xx CAN (!) be found but
# xx uses class yy and yy.class can't be found. (alph)
# wrapper.bin.parameters=-v

....

# Note: for JDK 1.2 add tools.jar, too. (alph)

# CLASSPATH environment value passed to the JVM
wrapper.classpath=/usr/lib/jdk1.1.7/lib/classes.zip
wrapper.classpath=/usr/local/jserv/lib/Apache-JServ.jar
wrapper.classpath=/usr/local/jsdk-2.0/lib/jsdk.jar

...

# Servlet Zones parameters
###########################

# List of servlet zones JServ manages
zones=<some-other-zones>,alph

# Configuration file for each servlet zone
...
alph.properties=/usr/local/apache-1.3.6/conf/alph.properties

...
# Set the name of the trace/log file.  
#
# This is very useful for debugging (alph)
# Note: DON'T use the file as in ApJServLogFile in jserv.conf!
# You will get into trouble! (alph)
log.file=/usr/local/apache-1.3.6/logs/jserv.log

Step 3 - What to do on jsp files
================================

Now lets tell JServ what to do on .jsp files:

   Map them to the alias "gnujsp" in our zone "alph"
   Tell jserv that /alph means zone "alph"

(Note: the names "/alph" and "alph" just happen to be the same,
 they need not.)

Add the following line to 

File: jserv.conf

ApJServAction .jsp /alph/gnujsp     

ApJServMount /alph /alph


Step 4 - Welcome
================

Now you're ready to start! 
You need an example, how to "START" ?
O.K. here it is:

1. Create a directory "myexamples" in the document root directory
   of your web server.

2. Copy the content of the directory examples to that location.

3. Call http://localhost/myexamples/hello.jsp

4. Welcome to the world of GNUJSP!

Some examples need additional libraries, take a look
at the source code if compilation fails.
It will contain a note telling you about that.

No you can write a xy.jsp-Page somewhere in
your doc-Directory of your webserver, try somemore 
examples from the gnujsp distribution or if you
want to see your computer working for some time
copy the directory testsuite to <webroot>/testsuite
and enter into your browser "http://localhost/testsuite/main.jsp".

Have fun and tell us about bugs on gnujsp@gjt.org.

Carsten Heyl <alph@gjt.org>