Jetty Logo
Version: 9.2.2-SNAPSHOT
Contact the core Jetty developers at www.webtide.com

private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery

Chapter 8. Configuring JSP Support

Table of Contents

Configuring JSP

Configuring JSP

This document provides information about configuring Java Server Pages for Jetty.

Which JSP Implementation

From jetty-9.2 onwards, we are using Jasper from Apache as the default JSP container implementation. In previous versions we used Jasper from Glassfish, and if you wish to, you can continue to do so.

The jetty-distribution by default enables the jsp module, and by default, this module is set to Apache Jasper. To change to use Glassfish Jasper instead, edit the $JETTY_HOME/start.d/jsp.mod file and change the line indicated:

Note that the availability of some JSP features may depend on which JSP container implementation you are using. Note also that it may not be possible to precompile your jsps with one container and deploy to the other.

JSPs and Embedding

If you have an embedded setup for your webapp and wish to use jsps, you will need to ensure that a JSP engine is correctly initialized.

For both Apache and Glassfish JSP engines, a Servlet Specification 3.1 style ServletContainerInitializer is used to accomplish this. You will need to ensure that this ServletContainerInitializer is run by jetty. Perhaps the easiest way to do this is to enable annotations processing so that jetty automatically discovers and runs it. The Embedded Examples section includes a worked code example of how to do this.

Alternatively, you can manually wire in the appropriate ServletContainerInitializer as shown in the embedded-jetty-jsp example on github, in which case you will not need the jetty-annotations jar on your classpath, nor include the AnnotationConfiguration in the list of configuration classes.

Precompiling JSPs

You can either follow the instructions on precompilation provided by the JSP container of your choice (either Glassfish or Apache), or if you are using maven for your builds, you can use the jetty-jspc-maven plugin to do it for you.

If you have precompiled your jsps, and have customized the output package prefix (which is org.apache.jsp by default), you should configure your webapp context to tell Jetty about this custom package name. You can do this using a servlet context init-param called org.eclipse.jetty.servlet.jspPackagePrefix.

For example, suppose you have precompiled your jsps with the custom package prefix of com.acme, then you would add the following lines to your web.xml file:

Note

both jetty maven plugins - jetty-jspc-maven-plugin and the jetty-maven-plugin - will only use Apache Jasper

Runtime Compiling JSPs

Depending on which JSP container you elect to use, the configuration and compilation characteristics will be different.

Apache JSP Container

By default, the Apache JSP container will look for the Eclipse Java Compiler (jdt). The jetty distribution ships a copy of this in $JETTY_HOME/lib/apache-jsp. If you wish to use a different compiler, you will need to configure the compilerClassName init-param on the JspServlet with the name of the class.

Table 8.1. Understanding Apache JspServlet Parameters

init paramDescriptionDefaultwebdefault.xml
classpathClasspath used for jsp compilation. Only used if org.apache.catalina.jsp_classpath context attribute is not set, which it is in Jetty.-
classdebuginfoInclude debugging info in class file.TRUE
checkIntervalInterval in seconds between background recompile checks. Only relevant if development=false.0
developmentdevelopment=true, recompilation checks occur on each request. See also modificationTestInterval.TRUE
displaySourceFragmentShould a source fragment be included in exception messagesTRUE
errorOnUseBeanInvalidClassAttributeShould Jasper issue an error when the value of the class attribute in an useBean action is not a valid bean classTRUE
forkShould Ant fork its Java compiles of JSP pages?TRUEFALSE
keepgeneratedDo you want to keep the generated Java files around?TRUE
trimSpacesShould white spaces between directives or actions be trimmed?FALSE
enablePoolingDetermines whether tag handler pooling is enabled.TRUE
engineOptionsClassAllows specifying the Options class used to configure Jasper. If not present, the default EmbeddedServletOptions will be used. 
mappedFileSupport for mapped Files. Generates a servlet that has a print statement per line of the JSP file TRUE
suppressSmapGeneration of SMAP info for JSR45 debugging.FALSE
dumpSmapDump SMAP JSR45 info to a file.FALSE
genStrAsCharArrayOption for generating Strings.FALSE
ieClassIdThe class-id value to be sent to Internet Explorer when using <jsp:plugin> tags.clsid:8AD9C840-044E-11D1-B3E9-00805F499D93
maxLoadedJspsThe maximum number of JSPs that will be loaded for a web application. If more than this number of JSPs are loaded, the least recently used JSPs will be unloaded so that the number of JSPs loaded at any one time does not exceed this limit. A value of zero or less indicates no limit.-1
jspIdleTimeoutThe amount of time in seconds a JSP can be idle before it is unloaded. A value of zero or less indicates never unload.-1
scratchDirDirectory where servlets are generated. See
compilerClassNameIf not set, defaults to the Eclipse jdt compiler. 
compilerUsed if the Eclipse jdt compiler cannot be found on the classpath. It is the classname of a compiler that Ant should invoke.
compilerTargetVMTarget vm to compile for.1.7
compilerSourceVMSets source compliance level for the jdt compiler.1.7
javaEncodingPass through the encoding to use for the compilation.UTF8
modificationTestIntervalIf development=true, interval between recompilation checks, triggered by a request.4
xpoweredByGenerate an X-Powered-By response header.FALSEFALSE
recompileOnFailIf a JSP compilation fails should the modificationTestInterval be ignored and the next access trigger a re-compilation attempt? Used in development mode only and is disabled by default as compilation may be expensive and could lead to excessive resource usage.-


Glassfish JSP Container

To compile .jsp files into Java classes, you need a Java compiler. You can acquire a Java compiler from the JVM if you are using a full JDK, or from a third party Jar.

By default, the Glassfish JSP container tries to use the compiler that is part of the JDK. NOTE: when using the JDK compiler, the system does not save your class files to disk unless you use the saveBytecode init-param as described below.

If you do not have a full JDK, you can configure the Eclipse Java Compiler that Jetty ships in the distro in $JETTY_HOME/lib/jsp/.You need to define a SystemProperty that prevents the Glassfish JSP engine from defaulting to the in-JVM compiler.

This is best done when using the standalone distro by uncommenting the System property org.apache.jasper.compiler.disablejsr199 in the jsp module:

Or for embedded usages, simply define this as a normal System property.

Configuration

The JSP engine has many configuration parameters. Some parameters affect only precompilation, and some affect runtime recompilation checking. Parameters also differ among the various versions of the JSP engine. This page lists the configuration parameters, their meanings, and their default settings. Set all parameters on the org.apache.jasper.JspServlet instance defined in the webdefault.xml file.

Note

Be careful: for all of these parameters, if the value you set doesn't take effect, try using all lower case instead of camel case, or capitalizing only some of the words in the name, as JSP is inconsistent in its parameter naming strategy.

Table 8.2. Understanding Glassfish JSP Parameters

init paramDescriptionDefaultwebdefault.xml
developmentdevelopment=true, recompilation checks occur on each request. See also modificationTestInterval.TRUE
forkShould Ant fork its Java compiles of JSP pages?TRUEFALSE
keepgeneratedDo you want to keep the generated Java files around?FALSE
saveBytecodeIf class files are generated as byte arrays, should they be saved to disk at the end of compilations?FALSE
trimSpacesShould white spaces between directives or actions be trimmed?FALSE
enablePoolingDetermines whether tag handler pooling is enabled.TRUE
mappedFileSupport for mapped Files. Generates a servlet that has a print statement per line of the JSP file./TRUE
sendErrorToClientIf false, stack traces, etc., are sent to std error instead of the client's browser.FALSE
classdebuginfoInclude debugging info in class file.TRUE
checkIntervalInterval in seconds between background recompile checks. Only relevant if development=false.0
suppressSmapGeneration of SMAP info for JSR45 debugging.FALSE
dumpSmapDump SMAP JSR45 info to a file.FALSE
genStrAsCharArrayOption for generating Strings.FALSE
genStrAsByteArrayOption for generating Strings.TRUE
defaultBufferNone FALSE
errorOnUseBeanInvalidClassAttribute FALSE
scratchDirDirectory where servlets are generated. Jetty sets this value according to the [/display/JETTY/Temporary+Directories work dir] settings for the webapp.
compilerDetermined at runtime. For Jetty this is the Eclipse jdt compiler.
compilerTargetVMTarget vm to compile for.1.5
compilerSourceVMSets source compliance level for the jdt compiler.1.5
javaEncodingPass through the encoding to use for the compilation.UTF8
modificationTestIntervalIf development=true, interval between recompilation checks, triggered by a request.0
xpoweredByGenerate an X-Powered-By response header.FALSEFALSE
usePrecompiled/use-precompiled FALSE
validating/enableTldValidationWhether or not to validate tag files against the schema.FALSE
reload-intervalIf reload-interval=0, then no runtime checking of JSP, otherwise sets the checking interval for both development=true and development=false.
initial-capacity/initialCapacityThe initial capacity of the hash maps mapping the name of the JSP to class and JSP file.

Much confusion generally ensues about the development, checkInterval and modificationTestInterval parameters and JSP runtime recompilation. Here is a factoring out of the various options:

  • Check the JSP files for possible recompilation on every request:

  • Only check approximately every N seconds, where a request triggers the time-lapse calculation. This example checks every 60 seconds:

  • Do no checking whatsoever, but still compile the JSP on the very first hit. (Be aware that this ''reload-interval'' parameter is shorthand for a ''development=false'' and ''checkInterval=0'' combination.):

  • Don't do any request-time checking, but instead start a background thread to do checks every N seconds. This example checks every 60 seconds:

Modifying Configuration

Regardless of which JSP container you are using, there are several options for modifying the JspServlet configuration.

Overriding webdefault.xml

You can make a copy of the $JETTY_HOME/etc/webdefault.xml that ships with Jetty, apply your changes, and use it instead of the shipped version. The example below shows how to do this when using the Jetty Maven plugin.

If you are using the Jetty distro, and you want to change the JSP settings for just one or a few of your webapps, copy the $JETTY_HOME/etc/webdefault.xml file somewhere, modify it, and then use a context xml file to set this file as the defaultsDescriptor for your webapp. Here's a snippet:

If you want to change the JSP settings for all webapps, edit the $JETTY_HOME/etc/webdefaults.xml file directly instead.

Configuring the JSP Servlet in web.xml

Another option is to add an entry for the JSPServlet to the WEB-INF/web.xml file of your webapp and change or add init-params. You may also add (but not remove) servlet-mappings. You can use the entry in $JETTY_HOME/etc/webdefault.xml as a starting point.

Using JSTL Taglibs

The JavaServer Pages Standlard Tag Library (JSTL) is part of the Jetty distribution and is automatically put on the classpath when you select your flavour of JSP. It is also automatically on the classpath for the jetty maven plugin, which uses the Apache JSP engine as of jetty-9.2.

Embedding

If you are using jetty in an embedded scenario, and you need to use JSTL, then you must ensure that the JSTL jars are included on the container's classpath - that is the classpath that is the parent of the webapp's classpath. This is a restriction that arises from the Java EE specification.

The jars that you will include will depend on the flavour of JSP that you are using.

With Glassfish JSP

You will need to put the jstl jars that are present in $jetty.home/lib/jsp onto the container's classpath. The Glassfish JSP engine will find the jstl tag definitions inside these jars during startup.

With Apache JSP

You will need to put the jars that are present in the $jetty.home/lib/apache-jstl directory onto the container's classpath. The Apache JSP engine will find the jstl tag definitions inside these jars during startup.

As an efficiency enhancement, you can have jetty examine the jstl jars to find the tags, and pre-feed them into the Apache JSP engine. This is more efficient, because jetty will only scan the jars you tell it to, whereas the Apache JSP engine will scan every jar, which can be time-consuming in applications with a lot of jars on the container classpath.

To take advantage of this efficiency enhancement, set up the org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern to include a pattern that will match the names of the jstl jars. The Embedded Examples section includes a worked code example of how to do this, here's a snippet from it:

Using JSF Taglibs

The following sections provide information about using JSF taglibs with Jetty Standalone and the Jetty Maven Plugin.

Using JSF Taglibs with Jetty Distribution

If you want to use JSF with your webapp, you need to copy the JSF implementation Jar (whichever Jar contains the META-INF/*.tld files from your chosen JSF implementation) into Jetty's shared container lib directory. You can either put them into the lib directory matching your JSP container of choice (either $JETTY_HOME/lib/jsp for Glassfish JSP, or $JETTY_HOME/lib/apache-jsp for Apache JSP), or put them into $JETTY_HOME/lib/ext.

Using JSF Taglibs with Jetty Maven Plugin

You should make your JSF jars dependencies of the plugin and not the webapp itself. For example:

See an error or something missing? Contribute to this documentation at Github!(Generated: 2014-09-02T01:00:31-07:00)