Jasper 2 JSP Engine How To

Introduction
Configuration
Production Configuration
Web Application Compilation
Using Jikes

Introduction

JBoss Web 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.
JDT used to compile JSP pages - The Eclipse JDT Java compiler is now used to perform JSP java source code compilation. This compiler loads source dependencies from the container classloader. Ant and javac can still be used.

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

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 JBoss Web 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 documentation for more information. If the value is not set, then the default Eclipse JDT Java compiler will be used instead of using Ant. No default value.
classdebuginfo - Should the class file be compiled with debugging information? true or false, default true.
classpath - Defines the class path to be used to compile the generated servlets. This parameter only has an effect if the ServletContext attribute org.apache.jasper.Constants.SERVLET_CLASSPATH is not set. This attribute is always set when Jasper is used within JBoss Web. By default the classpath is created dynamically based on the current web application.
compilerSourceVM - What JDK version are the source files compatible with? (Default JDK 1.4)
compilerTargetVM - What JDK version are the generated files compatible with? (Default JDK 1.4)
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.
engineOptionsClass - Allows specifying the Options class used to configure Jasper. If not present, the default EmbeddedServletOptions will be used.
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 JBoss Web ? true or false, default true.
javaEncoding - Java file encoding to use for generating java source files. Default UTF8.
genStringAsCharArray - Should text strings be generated as char arrays, to improve performance in some cases? Default false.
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.
modificationTestInterval - Checks for modification for a given JSP file (and all its dependent files) will be performed only once every specified amount of seconds. Setting this to 0 will cause the JSP to be checked on every access. Default is 4 seconds.
reloading - Should Jasper check for modified JSPs? true or false, default false.
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.

The Java compiler from Eclipse JDT in included as the default compiler. It is an advanced Java compiler which will load all dependencies from the Jboss Web class loader, which will help tremendously when compiling on large installations with tens of JARs. On fast servers, this will allow sub-second recompilation cycles for even large JSP pages.

Apache Ant can be used instead instead of the new compiler by simply removing the lib/jasper-jdt.jar file, and placing the ant.jar file from the latest Ant distribution in the lib folder. If you do this, you also need to use the "javac" argument to catalina.sh.

Production Configuration

The main JSP optimization which can be done is precompilation of JSPs. However, this might not be possible (for example, when using the jsp-property-group feature) or practical, in which case the configuration of the Jasper servlet becomes critical.

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

development - To disable on access checks for JSP pages compilation set this to false.
genStringAsCharArray - To generate slightly more efficient char arrays, set this to true.
modificationTestInterval - If development has to be set to true for any reason (such as dynamic generation of JSPs), setting this to a high value will improve performance a lot.
trimSpaces - To remove useless bytes from the response, set this to true.

Web Application Compilation

Using Ant is the preferred way to compile web applications using JSPC. Use the script given below (a similar script is included in the "deployer" download) to precompile a webapp:

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

   <import file="${tomcat.home}/bin/catalina-tasks.xml"/>
  
   <target name="jspc"> 

    <jasper 
             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}/lib"/>
        <fileset dir="${tomcat.home}/common/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>

  <target name="cleanup">
  	<delete>
        <fileset dir="${webapp.path}/WEB-INF/src"/>
        <fileset dir="${webapp.path}/WEB-INF/classes/org/apache/jsp"/>
  	</delete>
  </target>

</project>

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

$ANT_HOME/bin/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.

At the jasper2 task you can use the option addWebXmlMappings for automatic merge the ${webapp.path}/WEB-INF/generated_web.xml with the current web application deployment descriptor at ${webapp.path}/WEB-INF/web.xml. When you want to use Java 5 feature inside your jsp's, add the following javac compiler task attributes: source="1.5" target="1.5". For live application you can also compile with optimize="on" and without debug info debug="off".

When you don't want to stop the jsp generation at first jsp syntax error, use failOnError="false"and with showSuccess="true" all successfull jsp to java generation are printed out. Sometimes it is very helpfull, when you cleanup the generate java source files at ${webapp.path}/WEB-INF/src and the compile jsp servlet classes at ${webapp.path}/WEB-INF/classes/org/apache/jsp.

Hints:

When you switch to another JBoss Web or Tomcat release, then regenerate and recompile your jsp's with this version again!
Use java system property at server runtime to disable tag pooling org.apache.jasper.runtime.JspFactoryImpl.USE_POOL=false. and limit the buffering with org.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true. Note that changing from the defaults may affect performance, but depending on the application.

Using Jikes

If you wish to use Jikes to compile JSP pages:

From your Ant installation, copy ant.jar and (if it's available: Ant 1.5 and later) ant-launcher.jar to $CATALINA_BASE/lib.
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 JBoss Web 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.

Jasper 2 JSP Engine How To

Table of Contents

Introduction

Configuration

Production Configuration

Web Application Compilation

Using Jikes