Links

- Docs Home
- FAQ

User Guide

- 1) Introduction
- 2) Setup
- 3) First webapp
- 4) Deployer
- 5) Manager
- 6) Realms and AAA
- 7) Security Manager
- 8) JNDI Resources
- 9) JDBC DataSources
- 10) Classloading
- 11) JSPs
- 12) SSL
- 13) SSI
- 14) CGI
- 15) Proxy Support
- 16) MBean Descriptor
- 17) Default Servlet
- 18) Clustering
- 19) Load Balancer

Reference

- Release Notes
- Tomcat Configuration
- JK Documentation
- Servlet API Javadocs
- JSP API Javadocs

Tomcat Development

- Building
- Changelog
- Status
- Developers
- Functional Specs.
- Tomcat Javadocs
- Jasper Javadocs
- Architecture

# The Apache Jakarta Tomcat 5 Servlet/JSP Container

## Jasper 2 JSP Engine How To

print-friendly
version

Table of Contents

> Introduction
> Configuration
> Production Configuration
> Web Application Compilation
> Using Jikes

Introduction

> Tomcat 5.0 uses the Jasper 2 JSP Engine to implement the JavaServer Pages 2.0 specification.

> Jasper 2 has been redesigned to significantly improve performance over the orignal Jasper. In addition to general code improvements the following changes were made:

> - JSP Custom Tag Pooling - The java objects instantiated for JSP Custom Tags can now be pooled and reused. This significantly boosts the performance of JSP pages which use custom tags.
> - Background JSP compilation - If you make a change to a JSP page which had already been compiled Jasper 2 can recompile that page in the background. The previously compiled JSP page will still be available to serve requests. Once the new page has been compiled successfully it will replace the old page. This helps improve availablity of your JSP pages on a production server.
> - Recompile JSP when included page changes - Jasper 2 can now detect when a page included at compile time from a JSP has changed and then recompile the parent JSP.
> - Ant used to compile JSP pages - The Ant Build Tool is now used to perform JSP java source code compilation.

> Jasper is implemented using the servlet class `org.apache.jasper.servlet.JspServlet`.

Configuration

> By default Jasper is configured for use when doing web application development. See the section Production Configuration for information on configuring Jasper for use on a production Tomcat server.

> The servlet which implements Jasper is configured using init parameters in your global `$CATALINA_BASE/conf/web.xml`.

> - checkInterval - If development is false and reloading is true, background compiles are enabled. checkInterval is the time in seconds between checks to see if a JSP page needs to be recompiled. Default `300` seconds.
> - compiler - Which compiler Ant should use to compile JSP pages. See the Ant documenation for more information. Default `javac`.
> - classdebuginfo - Should the class file be compiled with debugging information? `true` or `false`, default `true`.
> - classpath - What class path should I use while compiling generated servlets? By default the classpath is created dynamically based on the current web application.
> - compilerSourceVM - What JDK version is the source compatible with. By default this is 1.3.
> - compilerTargetVM - What JDK version should the generated files be compatible with. By default this is also 1.3.
> - development - Is Jasper used in development mode (will check for JSP modification on every access)? `true` or `false`, default `true`.
> - enablePooling - Determines whether tag handler pooling is enabled. `true` or `false`, default `true`.
> - ieClassId - The class-id value to be sent to Internet Explorer when using <jsp:plugin> tags. Default `clsid:8AD9C840-044E-11D1-B3E9-00805F499D93`.
> - fork - Have Ant fork JSP page compiles so they are performed in a seperate JVM from Tomcat? `true` or `false`, default `true`.
> - javaEncoding - Java file encoding to use for generating java source files. Default `UTF8`.
> - keepgenerated - Should we keep the generated Java source code for each page instead of deleting it? `true` or `false`, default `true`.
> - mappedfile - Should we generate static content with one print statement per input line, to ease debugging? `true` or `false`, default `true`.
> - reloading - Should Jasper check for modified JSPs? `true` or `false`, default `true`.
> - scratchdir - What scratch directory should we use when compiling JSP pages? Default is the work directory for the current web application.
> - trimSpaces - Should white spaces in template text between actions or directives be trimmed ?, default `false`.

Production Configuration

> When using Jasper 2 in a production Tomcat server you should consider making the following changes from the default configuration.

> - development - To enable background compilation of JSP pages set this to `false`.
> - fork - The internal JVM javac compiler used by Ant has a known memory leak. And Ant requires that java compiles be synchronized, i.e. only one JSP page can be compiled at a time. Set fork to `true` or do not define it (it is the default value) so that Ant compiles JSP pages in a seperate JVM. This removes the synchronization of JSP page compiles and prevents all the javac classes from being instantiated and subsequently garbage collected by the JVM Tomcat is running in. This also works around known issues with javac, including memory leaking, as well as JAR file locking on Windows.

Web Application Compilation

> Using Ant is the preferred way to compile web applications using JSPC. Use the script given below to precompile a webapp:

>     <project name="Webapp Precompilation" default="all" basedir=".">

>       <target name="jspc">

>         <taskdef classname="org.apache.jasper.JspC" name="jasper2" >
>           <classpath id="jspc.classpath">
>             <pathelement location="${java.home}/../lib/tools.jar"/>
>             <fileset dir="${tomcat.home}/bin">
>               <include name="*.jar"/>
>             </fileset>
>             <fileset dir="${tomcat.home}/server/lib">
>               <include name="*.jar"/>
>             </fileset>
>             <fileset dir="${tomcat.home}/common/lib">
>               <include name="*.jar"/>
>             </fileset>
>           </classpath>
>         </taskdef>

>         <jasper2
>                  validateXml="false"
>                  uriroot="${webapp.path}"
>                  webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml"
>                  outputDir="${webapp.path}/WEB-INF/src" />

>       </target>

>       <target name="compile">

>         <mkdir dir="${webapp.path}/WEB-INF/classes"/>
>         <mkdir dir="${webapp.path}/WEB-INF/lib"/>

>         <javac destdir="${webapp.path}/WEB-INF/classes"
>                optimize="off"
>                debug="on" failonerror="false"
>                srcdir="${webapp.path}/WEB-INF/src"
>     	   excludes="**/*.smap">
>           <classpath>
>             <pathelement location="${webapp.path}/WEB-INF/classes"/>
>             <fileset dir="${webapp.path}/WEB-INF/lib">
>               <include name="*.jar"/>
>             </fileset>
>             <pathelement location="${tomcat.home}/common/classes"/>
>             <fileset dir="${tomcat.home}/common/lib">
>               <include name="*.jar"/>
>             </fileset>
>             <pathelement location="${tomcat.home}/shared/classes"/>
>             <fileset dir="${tomcat.home}/shared/lib">
>               <include name="*.jar"/>
>             </fileset>
>             <fileset dir="${tomcat.home}/bin">
>               <include name="*.jar"/>
>             </fileset>
>           </classpath>
>           <include name="**" />
>           <exclude name="tags/**" />
>         </javac>

>       </target>

>       <target name="all" depends="jspc,compile">
>       </target>

>     </project>

> The following command line can be used to run the script (replacing the tokens with the Tomcat base path and the path to the webapp which should be precompiled):

>     $ANT_HOME/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH>

> Then, the declarations and mappings for the servlets which were generated during the precompilation must be added to the web application deployment descriptor. Insert the `${webapp.path}/WEB-INF/generated_web.xml` at the right place inside the `${webapp.path}/WEB-INF/web.xml` file. Restart the web application (using the manager) and test it to verify it is running fine with precompiled servlets. An appropriate token placed in the web application deployment descriptor may also be used to automatically insert the generated servlet declarations and mappings using Ant filtering capabilities. This is actually how all the webapps distributed with Tomcat are automatically compiled as part of the build process.

Using Jikes

> If you wish to use Jikes to compile JSP pages:

> - Download and install jikes. jikes must support the -encoding option. Execute `jikes -help` to verify that it was built with support for `-encoding`.
> - Set the init parameter `compiler` to `jikes`.
> - Define the property `-Dbuild.compiler.emacs=true` when starting Tomcat by adding it to your `CATALINA_OPTS` environment variable. This changes how jikes outputs error messages so that it is compatible with Jasper.
> - If you get an error reporting that jikes can't use UTF8 encoding, try setting the init parameter `javaEncoding` to `ISO-8859-1`.

Copyright © 1999-2003, Apache Software Foundation