409 lines
17 KiB
XML
409 lines
17 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
<!DOCTYPE document [
|
|
<!ENTITY project SYSTEM "project.xml">
|
|
]>
|
|
<document url="jasper-howto.html">
|
|
|
|
&project;
|
|
|
|
<properties>
|
|
<author email="glenn@apache.org">Glenn L. Nielsen</author>
|
|
<author email="pero@apache.org">Peter Rossbach</author>
|
|
<title>Jasper 2 JSP Engine How To</title>
|
|
</properties>
|
|
|
|
<body>
|
|
|
|
<section name="Table of Contents">
|
|
<toc/>
|
|
</section>
|
|
|
|
<section name="Introduction">
|
|
|
|
<p>Tomcat <version-major-minor/> uses the Jasper 2 JSP Engine to implement
|
|
the <a href="https://wiki.apache.org/tomcat/Specifications">JavaServer Pages 2.3</a>
|
|
specification.</p>
|
|
|
|
<p>Jasper 2 has been redesigned to significantly improve performance over
|
|
the original Jasper. In addition to general code improvements the following
|
|
changes were made:</p>
|
|
<ul>
|
|
<li><strong>JSP Custom Tag Pooling</strong> - 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.</li>
|
|
<li><strong>Background JSP compilation</strong> - 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 availability
|
|
of your JSP pages on a production server.</li>
|
|
<li><strong>Recompile JSP when included page changes</strong> - Jasper 2
|
|
can now detect when a page included at compile time from a JSP has changed
|
|
and then recompile the parent JSP.</li>
|
|
<li><strong>JDT used to compile JSP pages</strong> - 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.</li>
|
|
</ul>
|
|
|
|
|
|
<p>Jasper is implemented using the servlet class
|
|
<code>org.apache.jasper.servlet.JspServlet</code>.</p>
|
|
|
|
</section>
|
|
|
|
<section name="Configuration">
|
|
|
|
<p>By default Jasper is configured for use when doing web application
|
|
development. See the section <a href="#Production_Configuration">
|
|
Production Configuration</a> for information on configuring Jasper
|
|
for use on a production Tomcat server.</p>
|
|
|
|
<p>The servlet which implements Jasper is configured using init parameters
|
|
in your global <code>$CATALINA_BASE/conf/web.xml</code>.
|
|
</p>
|
|
<ul>
|
|
<li><strong>checkInterval</strong> - If development is false and checkInterval
|
|
is greater than zero, background compiles are enabled. checkInterval is the time
|
|
in seconds between checks to see if a JSP page (and its dependent files) needs
|
|
to be recompiled. Default <code>0</code> seconds.</li>
|
|
|
|
<li><strong>classdebuginfo</strong> - Should the class file be compiled with
|
|
debugging information? <code>true</code> or <code>false</code>, default
|
|
<code>true</code>.
|
|
</li>
|
|
|
|
<li><strong>classpath</strong> - 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 Tomcat. By default the
|
|
classpath is created dynamically based on the current web application.</li>
|
|
|
|
<li><strong>compiler</strong> - Which compiler Ant should use to compile JSP
|
|
pages. The valid values for this are the same as for the compiler attribute of
|
|
Ant's
|
|
<a href="https://ant.apache.org/manual/Tasks/javac.html#compilervalues">javac</a>
|
|
task. If the value is not set, then the default Eclipse JDT Java compiler will
|
|
be used instead of using Ant. There is no default value. If this attribute is
|
|
set then <code>setenv.[sh|bat]</code> should be used to add
|
|
<code>ant.jar</code>, <code>ant-launcher.jar</code> and <code>tools.jar</code>
|
|
to the <code>CLASSPATH</code> environment variable.</li>
|
|
|
|
<li><strong>compilerSourceVM</strong> - What JDK version are the source files
|
|
compatible with? (Default value: <code>1.7</code>)</li>
|
|
|
|
<li><strong>compilerTargetVM</strong> - What JDK version are the generated files
|
|
compatible with? (Default value: <code>1.7</code>)</li>
|
|
|
|
<li><strong>development</strong> - Is Jasper used in development mode? If true,
|
|
the frequency at which JSPs are checked for modification may be specified via
|
|
the modificationTestInterval parameter.<code>true</code> or <code>false</code>,
|
|
default <code>true</code>.</li>
|
|
|
|
<li><strong>displaySourceFragment</strong> - Should a source fragment be
|
|
included in exception messages? <code>true</code> or <code>false</code>,
|
|
default <code>true</code>.</li>
|
|
|
|
<li><strong>dumpSmap</strong> - Should the SMAP info for JSR45 debugging be
|
|
dumped to a file? <code>true</code> or <code>false</code>, default
|
|
<code>false</code>. <code>false</code> if suppressSmap is true.</li>
|
|
|
|
<li><strong>enablePooling</strong> - Determines whether tag handler pooling is
|
|
enabled. This is a compilation option. It will not alter the behaviour of JSPs
|
|
that have already been compiled. <code>true</code> or <code>false</code>,
|
|
default <code>true</code>.
|
|
</li>
|
|
|
|
<li><strong>engineOptionsClass</strong> - Allows specifying the Options class
|
|
used to configure Jasper. If not present, the default EmbeddedServletOptions
|
|
will be used. This option is ignored if running under a SecurityManager.
|
|
</li>
|
|
|
|
<li><strong>errorOnUseBeanInvalidClassAttribute</strong> - Should Jasper issue
|
|
an error when the value of the class attribute in an useBean action is not a
|
|
valid bean class? <code>true</code> or <code>false</code>, default
|
|
<code>true</code>.</li>
|
|
|
|
<li><strong>fork</strong> - Have Ant fork JSP page compiles so they are
|
|
performed in a separate JVM from Tomcat? <code>true</code> or
|
|
<code>false</code>, default <code>true</code>.</li>
|
|
|
|
<li><strong>genStringAsCharArray</strong> - Should text strings be generated as char
|
|
arrays, to improve performance in some cases? Default <code>false</code>.</li>
|
|
|
|
<li><strong>ieClassId</strong> - The class-id value to be sent to Internet
|
|
Explorer when using <jsp:plugin> tags. Default
|
|
<code>clsid:8AD9C840-044E-11D1-B3E9-00805F499D93</code>.</li>
|
|
|
|
<li><strong>javaEncoding</strong> - Java file encoding to use for generating
|
|
java source files. Default <code>UTF8</code>.</li>
|
|
|
|
<li><strong>keepgenerated</strong> - Should we keep the generated Java source
|
|
code for each page instead of deleting it? <code>true</code> or
|
|
<code>false</code>, default <code>true</code>.</li>
|
|
|
|
<li><strong>mappedfile</strong> - Should we generate static content with one
|
|
print statement per input line, to ease debugging?
|
|
<code>true</code> or <code>false</code>, default <code>true</code>.</li>
|
|
|
|
<li><strong>maxLoadedJsps</strong> - The 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. Default <code>-1</code></li>
|
|
|
|
<li><strong>jspIdleTimeout</strong> - The amount of time in seconds a JSP can be
|
|
idle before it is unloaded. A value of zero or less indicates never unload.
|
|
Default <code>-1</code></li>
|
|
|
|
<li><strong>modificationTestInterval</strong> - Causes a JSP (and its dependent
|
|
files) to not be checked for modification during the specified time interval
|
|
(in seconds) from the last time the JSP was checked for modification. A value of
|
|
0 will cause the JSP to be checked on every access. Used in development mode
|
|
only. Default is <code>4</code> seconds.</li>
|
|
|
|
<li><strong>recompileOnFail</strong> - If 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.</li>
|
|
|
|
<li><strong>scratchdir</strong> - What scratch directory should we use when
|
|
compiling JSP pages? Default is the work directory for the current web
|
|
application. This option is ignored if running under a SecurityManager.</li>
|
|
|
|
<li><strong>suppressSmap</strong> - Should the generation of SMAP info for JSR45
|
|
debugging be suppressed? <code>true</code> or <code>false</code>, default
|
|
<code>false</code>.</li>
|
|
|
|
<li><strong>trimSpaces</strong> - Should template text that consists entirely of
|
|
whitespace be removed? <code>true</code> or <code>false</code>, default
|
|
<code>false</code>.</li>
|
|
|
|
<li><strong>xpoweredBy</strong> - Determines whether X-Powered-By response
|
|
header is added by generated servlet. <code>true</code> or <code>false</code>,
|
|
default <code>false</code>.</li>
|
|
|
|
<li><strong>strictQuoteEscaping</strong> - When scriptlet expressions are used
|
|
for attribute values, should the rules in JSP.1.6 for the escaping of quote
|
|
characters be strictly applied? <code>true</code> or <code>false</code>, default
|
|
<code>true</code>.</li>
|
|
|
|
<li><strong>quoteAttributeEL</strong> - When EL is used in an attribute value
|
|
on a JSP page, should the rules for quoting of attributes described in JSP.1.6
|
|
be applied to the expression? <code>true</code> or <code>false</code>, default
|
|
<code>true</code>.</li>
|
|
</ul>
|
|
|
|
<p>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 Tomcat 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.</p>
|
|
|
|
<p>Apache Ant, which was used in previous Tomcat releases, can be used instead
|
|
of the new compiler by configuring the compiler attribute as explained above.
|
|
</p>
|
|
|
|
</section>
|
|
|
|
<section name="Known issues">
|
|
|
|
<p>As described in
|
|
<a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=39089">
|
|
bug 39089</a>, a known JVM issue,
|
|
<a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6294277">
|
|
bug 6294277</a>, may cause a
|
|
<code>java.lang.InternalError: name is too long to represent</code> exception
|
|
when compiling very large JSPs. If this is observed then it may be worked around
|
|
by using one of the following:
|
|
</p>
|
|
<ul>
|
|
<li>reduce the size of the JSP</li>
|
|
<li>disable SMAP generation and JSR-045 support by setting
|
|
<code>suppressSmap</code> to <code>true</code>.</li>
|
|
</ul>
|
|
|
|
</section>
|
|
|
|
<section name="Production Configuration">
|
|
|
|
<p>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.</p>
|
|
|
|
<p>When using Jasper 2 in a production Tomcat server you should consider making
|
|
the following changes from the default configuration.</p>
|
|
<ul>
|
|
<li><strong>development</strong> - To disable on access checks for JSP
|
|
pages compilation set this to <code>false</code>.</li>
|
|
<li><strong>genStringAsCharArray</strong> - To generate slightly more efficient
|
|
char arrays, set this to <code>true</code>.</li>
|
|
<li><strong>modificationTestInterval</strong> - If development has to be set to
|
|
<code>true</code> for any reason (such as dynamic generation of JSPs), setting
|
|
this to a high value will improve performance a lot.</li>
|
|
<li><strong>trimSpaces</strong> - To remove useless bytes from the response,
|
|
set this to <code>true</code>.</li>
|
|
</ul>
|
|
|
|
</section>
|
|
|
|
<section name="Web Application Compilation">
|
|
|
|
<p>Using Ant is the preferred way to compile web applications using JSPC. Note
|
|
that when pre-compiling JSPs, SMAP information will only be included in the
|
|
final classes if suppressSmap is false and compile is true.
|
|
Use the script given below (a similar script is included in the "deployer"
|
|
download) to precompile a webapp:
|
|
</p>
|
|
|
|
<source><![CDATA[<project name="Webapp Precompilation" default="all" basedir=".">
|
|
|
|
<import file="${tomcat.home}/bin/catalina-tasks.xml"/>
|
|
|
|
<target name="jspc">
|
|
|
|
<jasper
|
|
validateXml="false"
|
|
uriroot="${webapp.path}"
|
|
webXmlInclude="${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"
|
|
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}/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>]]></source>
|
|
|
|
<p>
|
|
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):
|
|
</p>
|
|
<source>$ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH></source>
|
|
|
|
|
|
<p>
|
|
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 <code>${webapp.path}/WEB-INF/generated_web.xml</code>
|
|
at the right place inside the <code>${webapp.path}/WEB-INF/web.xml</code> 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.
|
|
</p>
|
|
|
|
<p>
|
|
At the jasper task you can use the option <code>addWebXmlMappings</code> for
|
|
automatic merge the <code>${webapp.path}/WEB-INF/generated_web.xml</code>
|
|
with the current web application deployment descriptor at
|
|
<code>${webapp.path}/WEB-INF/web.xml</code>. When you want to use Java 6
|
|
features inside your JSP's, add the following javac compiler task attributes:
|
|
<code>source="1.6" target="1.6"</code>. For live
|
|
applications you can also disable debug info with <code>debug="off"</code>.
|
|
</p>
|
|
|
|
<p>
|
|
When you don't want to stop the JSP generation at first JSP syntax error, use
|
|
<code>failOnError="false"</code> and with
|
|
<code>showSuccess="true"</code> all successful <i>JSP to Java</i>
|
|
generation are printed out. Sometimes it is very helpful, when you cleanup the
|
|
generate java source files at <code>${webapp.path}/WEB-INF/src</code>
|
|
and the compile JSP servlet classes at
|
|
<code>${webapp.path}/WEB-INF/classes/org/apache/jsp</code>.
|
|
</p>
|
|
|
|
<p><strong>Hints:</strong></p>
|
|
<ul>
|
|
<li> When you switch to another Tomcat release, then regenerate and recompile
|
|
your JSP's with the new Tomcat version.</li>
|
|
<li>Use java system property at server runtime to disable PageContext pooling
|
|
<code>org.apache.jasper.runtime.JspFactoryImpl.USE_POOL=false</code>.
|
|
and limit the buffering with
|
|
<code>org.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true</code>. Note
|
|
that changing from the defaults may affect performance, but it will vary
|
|
depending on the application.</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section name="Optimisation">
|
|
<p>
|
|
There are a number of extension points provided within Jasper that enable the
|
|
user to optimise the behaviour for their environment.
|
|
</p>
|
|
|
|
<p>
|
|
The first of these extension points is the tag plug-in mechanism. This allows
|
|
alternative implementations of tag handlers to be provided for a web application
|
|
to use. Tag plug-ins are registered via a <code>tagPlugins.xml</code> file
|
|
located under <code>WEB-INF</code>. A sample plug-in for the JSTL is included
|
|
with Jasper.
|
|
</p>
|
|
|
|
<p>
|
|
The second extension point is the Expression Language interpreter. Alternative
|
|
interpreters may be configured through the <code>ServletContext</code>. See the
|
|
<code>ELInterpreterFactory</code> javadoc for details of how to configure an
|
|
alternative EL interpreter.
|
|
</p>
|
|
</section>
|
|
|
|
</body>
|
|
|
|
</document>
|