GNU JSP Installation Guide
$Id: install.html,v 1.13 2000/09/07 15:39:07 alph Exp $
Before you start installing GNUJSP make sure you have the following:
- JDK or JRE 1.1 or higher.
- A java compiler (one is included with the full JDK, but you can specify others).
A web server that supports the servlet API, either directly or
through a servlet engine.
- An implementation of the javax.servlet.jsp packages. GNUJSP comes
with a drop-in replacement for the servlet and JSP interfaces,
copyrighted by the Free Software Foundation (in the lib directory of
the distribution), or you can use the implementation included with
Sun's JSWDK 1.0 download; see http://java.sun.com/products/servlet/. See the specific installation details for more information.
Upgrading from 0.9.x
If you are upgrading from an older version of GNU JSP, please note
that 90 percent of the code has changed, and that GNU JSP no longer
supports the JSP 0.91 syntax. If you are queasy about making this
change, you can map files with the .jsp10 extension to
org.gjt.jsp.JspServlet and leave your 0.9 mappings intact. This
way you can test out the new spec without compromising your legacy jsp
files. However, it is recommended that you do not mix and match files
for both 0.9 and 1.0 specs if you use session-related features.
Support for the JSP Specification
GNU JSP supports most features of the JSP 1.0 specification, with the
taglib directive. Taglib is an optional, unspecified feature of JSP 1.0; GNUJSP plans to implement full tag extension support as illustrated by the JSP 1.1 specification, currently in public release.
The testsuite which comes with GNU JSP demonstrates and tests most
features of the JSP syntax.
JSP 0.91 and JSP 0.92 are not supported. If you need a version of GNUJSP that supports JSP 0.91, please check the archive section for version 0.9.10 and refer to the documentation that comes with 0.9.10.
GNU JSP supports the precompilation protocol specified
in the JSP 1.1 specification. If a request is received for a JSP page
with the parameter
jsp_precompile set to any non-null value,
GNU JSP will ensure that the page is compiled, but will not process the
Support for JSDK 2.1 Features
A great deal of work has been spent on providing wrapper classes to allow
servlet engines that implement only JSDK 2.0 (Apache JServ is probably the most popular of these) to use the JSP features that
require JSDK 2.1. If you have a JSDK 2.1 compliant server, these wrappers
aren't used. Every effort has been made to make GNU JSP function just as
well under JSDK 2.0 as JSDK 2.1, but there are a few caveats. If you run under JSDK 2.0, you should be aware that although GNU JSP
makes things like
jsp:include possible, it doesn't remove the corresponding
limitation from your servlets that aren't processed by GNU JSP.
Because GNUJSP can be used with such a large number of webservers and
servlet engines, it is impossible to provide a detailed installation
guide for each. You should consult the documentation that comes with
your webserver or servlet engine for details.
Detailed instructions are currently provided for the following engines:
If your web server and servlet engine aren't specifically mentioned, here
are some general guidelines.
- Apache JServ: see
- Jigsaw 2.0.x: see
- vqServer 1.9.17: see
lib/gnujsp10.jar file to the CLASSPATH used by the web server.
Create a directory to store the generated java and class files. Make sure
the webserver and/or the servlet engine have write permissions to this
Configure the GNUJSP servlet. The servlet alias should be "gnujsp" and the
class name should be "org.gjt.jsp.JspServlet" (note that this has changed from version 0.9.x). The init parameter
"scratchdir" is required, and should contain the name of the directory
created in the previous step.
For a lot of servlet engines this means adding the following
lines to a file called "servlets.properties":
servlet.gnujsp.initArgs=scratchdir=[directory created in step two]
See Initialization Parameters for all options.
Associate the extension ".jsp" with the GNUJSP servlet.
To test your setup, copy the JSP files in the examples directory and try
accessing them via the webserver.
Most troubleshooting can be done by investigating the log files generated
by your servlet engine or webserver. Because configuration details vary,
we cannot provide detailed troubleshooting instructions, but you are welcome
to post your problems on the GNU JSP mailing list (see Reporting Bugs).
Developing on GNU JSP
GNUJSP automatically detects changes to a JSP file (and the JSP files it
includes), and recompiles the JSP file if necessary. When a change (or
a new file) is detected, the JSP file is translated to a java file, and
javac is run. If javac reports any errors, GNUJSP does its best to translate
the java line numbers to JSP line numbers and reports the errors in the
When you use beans from JSP pages, you can put them in one of two places:
Some experimentation may be necessary to get this to work.
in the servlet repository; if GNUJSP has been installed in the servlet
repository, it calls the servlet class loader to load the beans from the
servlet repository. If the servlet engine automatically reloads servlets
when the bean changes, GNUJSP will also be reloaded and therefore reload
the bean as well.
in the system classpath; this always works, but the bean will
not be automatically reloaded when it is changed.
Deploying on GNU JSP
In a deployment or production environment, you'll generally want to
scrutinize the init parameters. Typically you will enable
checkclass and turn off
debug. You can
probably also gain a little performance by turning off
checkdependencies if you're certain you don't need it.
The full list of available init parameters is:
This required init parameter specifies the JSP repository; the directory
where GNUJSP writes the generated java and class files.
(0.9 used 'repository', but this conflicted with Apache JServ's
notion of a repository. 'scratchdir' is used by Sun's reference
If set to "true", the source files produced by GNUJSP are retained in the
specified scratch directory. Otherwise they are removed once the class is
This init parameter specifies the command line used to compile the
generated java files into class files. A number of special values can
The default value of the compiler init parameter is:
When the command is "builtin-javac" the builtin java compiler
of the JDK is used (this requires tools.jar on JDK 1.2).
The string %classpath% is replaced with the system classpath.
The string %scratchdir% is replaced with the full pathname of
the JSP repository as defined by the scratchdir init parameter.
The string %source% is replaced with the name of the java file to
The string %encoding% is replaced with the specified character
encoding of the JSP page being compiled.
The string %% is replaced with a single percentage sign.
All other occurences of %% are replaced by the value
of the init parameter , e.g. %beanspath% is replaced
by the value of the init parameter beanspath.
builtin-javac -classpath %classpath%:%scratchdir% -d %scratchdir% -deprecation %source%
where the colon between %classpath% and %scratchdir% is replaced
with the platform dependent path separator (: on Unix, ; on Windows).
If you want to use spaces in the classpath argument put the argument in quotes:
-classpath "%classpath%;%scratchdir%;c:\I like quotes".
On Windows systems, the Runtime.exec(String) method seems to reparse
the parameters, so make sure there are no spaces in the classpath or
scratchdir when you are not using the builtin java compiler.
You can use IBM's open source jikes compiler with GNUJSP; remember to add
[JDK_HOME]/jre/lib/rt.jar to the servlet engine's
Using external compilers with the Blackdown JDK 1.2 prereleases for
GNU/Linux requires the use of the
-green option for the JVM.
Default: false. If this property is false, GNU JSP will recompile all JSP
pages each time it starts up. This can be useful for development when
pages depend on beans that are simultaneously being developed. It can
be a bottleneck, however, in a production environment, so you may wish to
enable this option when deploying. Note that this operates independently of
checkdependencies; it merely means that if a .class file
already exists for a JSP page, it should be loaded instead of regenerated
on the first request.
Set this init parameter to "false" to prevent GNUJSP from
checking the file dates of the source JSP file (and the files
included by it) when running the generated class file.
- country and language
Default: the default country and language of the Java virtual machine.
Specify these properties to select a particular locale to internationalize
GNU JSP's error messages, if available.
Set this init parameter to "true" to make GNUJSP generate
some debug output (in the servlet log).
Set this init parameter to "true" to make GNUJSP generate
extra debug output (in the servlet log). This is useful
for debugging path problems when jsp files are not found
or include files are not found.
In many web servers, JSP pages can be called either as
"/secure/file.jsp" or as "/servlet/gnujsp/secure/file.jsp". This
is a security hole when authentication is required to access the
directory "/secure", but not for "/servlet". If the optional
denyuri init parameter is set, GNUJSP will not accept requests
that start with the same string as denyuri (in this example, you
would set denyuri to "/servlet/gnujsp"). This is a hack to
solve a problem that should really be solved by the servlet
engine. This parameter replaces the checkuri parameter in GNU
Default: not set.
When determining the JSP file to compile, GNUJSP calls
ServletContext.getRealPath(request.getServletPath()). If that fails to
return a valid filename, GNUJSP tries getRequestURI() instead. If that
also fails, GNUJSP finally tries request.getPathTranslated(). The
optional pagebase init parameter can be set to prefix the result of
getPathTranslated() with a constant string. This can be useful
when the servlet engine runs on a different server than the webserver.
Set to true means that GNUJSP should generate
subdirectories and packages for java source and class
files. This is a must on MacOS platforms due to the maximum
filename length of 30 characters.
Set to true means that GNUJSP should generate
a prefix to each file which includes the hostname and port
of the request. Enable this if you are directing multiple
virtual hosts to the same instance of GNUJSP.
Set to anything means that you are using Apache with JServ.
It is needed for a JServ-specific workaround.
If you are not using Apache with JServ, do not set this property.
When using Apache try first without using this property.
Set to true means that GNUJSP should try to load
URLs via HTTP GET if locating them as jsp pages or as servlets fails.
This is used in JSDK 2.0 environments (e.g. jserv). In Versions before
1.0.1pre2 the default was true.
Set to true means that GNUJSP should locate files
by using the apache property "org.apache.jserv.DOCUMENT_ROOT" as page base.
Use this only if you know what you are doing. It will break
virtual servers and most probably standard ~user behaviour.
Please tell the list email@example.com if you have to set it!
Using GNU JSP with Java 2
In general, GNU JSP behaves exactly the same under a Java 2 virtual
machine (JDK 1.2, for example) as it does when running under JDK 1.1.
However, if you want to use the built-in compiler (javac), you'll want
to add "
[JDK_HOME]/lib/tools.jar" to the classpath setting.
If you think you've found a bug or have a question, comment, or
contribution, check the mailing list at http://www.gjt.org/servlets/MailingLists/ListInfo.html/gnujsp.