$Id: INSTALL.apache,v 1.23 2000/09/29 17:39:28 alph Exp $
This is short guide for installing gnujsp 1.0.1 on apache 1.3.x
using jserv 1.0/1.1b[123]/1.1.2, jsdk 2.0 (for jserv 1.0/1.1).
New since 1.0.1pre2:
A short installation guide for the impatient.
Note: Former versions of this document referenced servlet.jar from
jswdk 1.0. This file is no longer needed, instead servlet-2.0-plus.jar
from which is included
in the lib directory will be used now.
Note 2: If you use a CVS snapshot instead of a real release you
have to replace all occurences of gnujsp10.jar with gnujsp1.0cvs.jar.
Note 3: What is a "snapshot"? You want to try the latest development
version without dealing with CVS (a source code versioning
system the sources are in)? Every hour the CVS is checked for
changes if changes are found a new distribution is
born which we call a "snapshot". A link to them should
be available from the GNUJSP home page.
Note 4: Others had success running Blackdown JDK 1.2pre2,
2 differences must be noted:
1. The "-v" flag now must be written as "-verbose"
2. You have to add tools.jar to the CLASSPATH. The Sun compiler
is contained in that package.
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.1.2 (or 1.0 or 1.1b2/3)
- jsdk 2.0 for jserv
- servlet-2.0-plus.jar (in the GNUJSP distribution)
- jdk 1.1.7 or newer (I didn't tried 1.2 but it should work, sometimes the
JIT must be turned off)
- jar-File for gnujsp 1.0.1 (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 something is different on windows thanks to Alexander
Pisculla a windows example is added.
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.1.2 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.
Here are 2 installation guides:
1. A fast one without explanation. (GUIDE-1)
2. A detailed one. (GUIDE-2)
-------------------------------GUIDE-1--------------------------------------
1. Apache and Jserv should be configured so that the IsItRunningServlet
works. Konfiguration files are to be assumed in the directory
/usr/local/apache/conf/jserv
2. Add the following lines to jserv.conf:
ApJServVMTimeout 30
ApJServMount /alph /alphzone
ApJServAction .jsp /alph/gnujsp
3. jserv.properties:
Remove:
wrapper.classpath=/usr/local/jsdk-2.0/lib/jsdk.jar
Add:
# change to where you put the jar ...
wrapper.classpath=/usr/local/gnujsp/lib/servlet-2.0-plus.jar
Change the line
zones=root
to
zones=root,alphzone
Add:
alphzone.properties=/usr/local/apache/conf/jserv/alphzone.properties
4. Copy zone.properties.default to alphzone.properties
Remove:
repositories=/usr/local/apache-1.3.12/servlets
Add:
repositories=/usr/local/gnujsp/lib/gnujsp10.jar
# or
# repositories=/usr/local/gnujsp/lib/gnujsp10test.jar
repositories=/usr/local/gnujsp/lib/sax2.jar
repositories=/usr/local/gnujsp/lib/openxml-1.2-w3c.jar
repositories=/usr/local/gnujsp/lib/aelfred.jar
servlet.gnujsp.code=org.gjt.jsp.JspServlet
# give me debug output in the logs (time and space consuming)
# servlet.gnujsp.initArgs=debug=true
# I want detailed path output in the logs (lot of stuff)
# servlet.gnujsp.initArgs=pathdebug=true
# where to put created java source and class files (www server needs write access!)
servlet.gnujsp.initArgs=scratchdir=/var/local/apache/jsp
# created java classes use packages instead of long file names
servlet.gnujsp.initArgs=usepackages=true
# remove comment if you want german messages :-)
# servlet.gnujsp.initArgs=language=de,country=de
# checkclass: is set to true: check for changes to jsp pages and recompile
# checkdependancies: keep track of included files and check for changes
servlet.gnujsp.initArgs=checkdependancies=true,checkclass=true
# Do not remove java source files after compilation. (helpful for debugging)
# servlet.gnujsp.initArgs=keepJava=true
# which sax parser to use for xml files (experimental!)
# servlet.gnujsp.initArgs=xmlparser=com.microstar.xml.SAXDriver
# builtin-java: use the java compiler classes from JDK
servlet.gnujsp.initArgs=compiler=builtin-javac -classpath %classpath%:%scratchdir%:/usr/local/gnujsp/lib/gnujsp10.jar -d %scratchdir% -deprecation %source%
# Windows users:
# 1. Use "" for pathes with spaces
# 2. Use ";" as path separator
# Example: -classpath "%classpath%;%scratchdir;c:\path with spaces"
# needed by test cases in the testsuite
# servlet.gnujsptestservlet.code=org.gjt.jsp.test.GNUJSPTestServlet
5. Copy hello.jsp from the examples to your document root (where your HTML pages
reside ...) and call it via
http://localhost/hello.jsp
6. If that does not work try the jserv config checker in the doc/apache directory
./check-gnujsp-conf --jservconf /usr/local/apache/conf/jserv/jserv.conf
or
perl check-gnujsp-conf --jservconf /usr/local/apache/conf/jserv/jserv.conf
activate debug/pathdebug for gnujsp and look into the apache/jserv logs.
7. If all that fails write to gnujsp@gjt.org.
8. Enjoy gnujsp ...
-------------------------------GUIDE-2--------------------------------------
Now follows a detailed explanation of what to do and why when
configuring jserv 1.1.2 for gnujsp.
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".
(Note: No special reason for that except
thats my computer name and you won't have it already :-)
You may add the lines to your existing zone instead.)
Copy the example properties file (zone.properties.default or example.properties or
root.properties) from apache and name it
"alphzone.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.
gnujsp10.jar (or gnujsp10cvs.jar for snapshots)
jar file containing current GNUJSP version
(Note: use gnujsp10test.jar if you want to try the
complete testsuite)
jdbcbeans
a directory where I develop some beans
since they change, putting them here will auto
reload them. Later they will be 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.
- '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 the dir containing your own beans
(often missed by newbies if developing own beans!)
"-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,
take a look at the complete list in the other docs.
I may have added servlet-2.0-plus.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.
Note: If you add gnujsp10.jar to the wrapper classpath
your jsp pages CANNOT load any beans, classes, whatever
from the repository! *footnote1*)
Note 2: the pagebase parameter is no longer needed and may
instead cause problems, so please remove it from your config!
Make the following changes (Note: I removed most of
the comments here for clarity.)
File: alphzone.properties
# List of Repositories
#######################
repositories=/usr/local/gnujsp-1.0/lib/gnujsp10.jar
# or
# repositories=/usr/local/gnujsp/lib/gnujsp10test.jar
repositories=/usr/local/gnujsp-1.0/lib/servlet-2.0-plus.jar
# sax base classes
repositories=/usr/local/gnujsp/lib/sax2.jar
# org.w3c classes
repositories=/usr/local/gnujsp/lib/openxml-1.2-w3c.jar
# a sax compatible parser
repositories=/usr/local/gnujsp/lib/aelfred.jar
# this a directory where *I* keep some of my beans,
# put your directory here or don't use it ...
repositories=/home/heyl/test/java/jdbcbeans
#repositories=/home/heyl/lib/java/Acme.jar
#repositories=/usr/local/webl-3.0/lib/WebL.jar
# Windows example:
#repositories=c:/lib/gnujsp10cvs.jar,c:/lib/servlet-2.0-plus.jar
#repositories=c:/lib/mybeans
#
# 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)
# From a tip from Ray Thomas:
# Be sure the scratchdir is writable by the same uid as the jserv process.
# Using automatically start this is the same uid as the webserver
# process. If for example, your jserv/webserver runs as "nobody," then
# change the owner and group of scratchdir to "nobody" as well. Also make
# sure at least the owner ("nobody") has write permissions for the directory.
# ex.
# chown nobody /var/local/apache/jsp
# chgrp nobody /var/local/apache/jsp
# chmod u+w /var/local/apache/jsp
servlet.gnujsp.code=org.gjt.jsp.JspServlet
servlet.gnujsp.initArgs=debug=true
servlet.gnujsp.initArgs=checkclass=true
servlet.gnujsp.initArgs=scratchdir=/var/local/apache/jsp
# which sax parser to use for xml files (experimental!)
# servlet.gnujsp.initArgs=xmlparser=com.microstar.xml.SAXDriver
servlet.gnujsp.initArgs=compiler=builtin-javac -classpath %classpath%:%scratchdir%:/usr/local/gnujsp-1.0/lib/servlet-2.0-plus.jar:/usr/local/gnujsp-1.0/lib/gnujsp10.jar:/home/heyl/test/java/jdbcbeans -d %scratchdir% -deprecation %source%
# Windows example
# servlet.gnujsp.initArgs=debug=true
# servlet.gnujsp.initArgs=scratchdir=c:/utility/apache/temp
# servlet.gnujsp.initArgs=compiler=builtin-javac -classpath %classpath%;%scratchdir%;c:/lib/gnujsp10cvs.jar;c:/lib/servlet.jar -d %scratchdir% -deprecation %source%
# Windows users with space pathes use: -classpath "%classpath%:%scratchdir:c:\path with spaces"
Step 2 - Tell jserv about alph zone
===================================
Now lets tell jserv that we just invented an "alphzone" zone and want it to
be served under the same name.
(all servlets contained in the zone will be served as "/alph/",
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 to JDK 2 users: You may have to add tools.jar to wrapper.classpath.
Note that I didn't put servlet-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
# For JDK 2:
# wrapper.bin.parameters=-verbose
....
# 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
# Possibly for JDK 2:
#wrapper.classpath=/usr/lib/.../lib/tools.jar
wrapper.classpath=/usr/local/jserv/lib/Apache-JServ.jar
wrapper.classpath=/usr/local/jsdk-2.0/lib/jsdk.jar
# Windows example:
# wrapper.classpath=c:/utility/jdk1.1.7b/lib/classes.zip
# wrapper.classpath=c:/lib/ApacheJServ.jar
# wrapper.classpath=c:/lib/jsdk.jar
#
...
# Servlet Zones parameters
###########################
# List of servlet zones JServ manages
zones=,alphzone
# Configuration file for each servlet zone
...
alphzone.properties=/usr/local/apache-1.3.6/conf/alphzone.properties
# Win:
# alphzone.properties=c:/utility/apache/conf/alphzone.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.12/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 "alphzone"
Tell jserv that /alph means zone "alphzone"
Add the following line to
File: jserv.conf
ApJServAction .jsp /alph/gnujsp
ApJServMount /alph /alphzone
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.
Now you can write a xy.jsp-Page somewhere in
your doc-Directory of your webserver, try some more
examples from the gnujsp distribution or if you
want to see your computer working for some time
copy the directory testsuite to /testsuite
and enter into your browser "http://localhost/testsuite/main.jsp".
Have fun and tell us about bugs on gnujsp@gjt.org.
Carsten Heyl
*footnote1*)
Simon ("Simon Waterhouse (UK)" )
send a detailed description what happens when you put
gnujsp10.jar in the wrapper classpath:
"However if you *do* put org.gjt.jsp.JspServlet on the wrapper.classpath my
experience is that you:
a. break Jserv's nice autoreloading feature
b. won't be able to load classes from the zone's repositories
Why ?
Jserv's classloader (org.apache.java.lang.AdpativeClassLoader) defers to the
system class loader as a good
loader should. Putting org.gjt.jsp.JspServlet on the wrapper classpath means
that the JspServlet gets loaded by the system class loader
(sun.misc.Launcher in my case) and autoreloading then doesn't work for this
servlet because AdpativeClassLoader is out of the loop.
Also JspClassLoader (line 45) defers to JspServlet's ClassLoader - if this
is NOT AdpativeClassLoader then loading of classes from the servlet zone
repository fails (as only good ole AdpativeClassLoader knows where these
repositories are...)"