GNU JSP Installation Guide

$Id: install.html,v 1.13 2000/09/07 15:39:07 alph Exp $

Prerequisites

Before you start installing GNUJSP make sure you have the following:

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 following exceptions:

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 request.

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:forward and jsp:include possible, it doesn't remove the corresponding limitation from your servlets that aren't processed by GNU JSP.

Configuration

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.

  1. Add the lib/gnujsp10.jar file to the CLASSPATH used by the web server.
  2. 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 directory.

  3. 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.code=org.gjt.jsp.JspServlet
    servlet.gnujsp.initArgs=scratchdir=[directory created in step two]

    See Initialization Parameters for all options.

  4. Associate the extension ".jsp" with the GNUJSP servlet.
  5. To test your setup, copy the JSP files in the examples directory and try accessing them via the webserver.

Troubleshooting

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 browser window.

When you use beans from JSP pages, you can put them in one of two places:

  1. 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.
  2. in the system classpath; this always works, but the bean will not be automatically reloaded when it is changed.
Some experimentation may be necessary to get this to work.

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.

Initialization Parameters

The full list of available init parameters is:

scratchdir
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 implementation.)
keepJava
Default: false. 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 successfully compiled.
compiler
This init parameter specifies the command line used to compile the generated java files into class files. A number of special values can be used:
  • 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 compile
  • 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.
The default value of the compiler init parameter is:
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 classpath.

Using external compilers with the Blackdown JDK 1.2 prereleases for GNU/Linux requires the use of the -green option for the JVM.

checkclass
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.
checkdependencies
Default: true. 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.
debug
Default: false. Set this init parameter to "true" to make GNUJSP generate some debug output (in the servlet log).
pathdebug
Default: false. 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.
denyuri
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 JSP 0.9.
pagebase
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.
usepackages
Default: false.
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.
usehostname
Default: false.
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.
jserv
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.
usehttpfallback
Default: false.
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.
usedocroot
Default: false.
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 gnujsp@gjt.org 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.

Reporting Bugs

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.