webapps/docs/jasper-howto.xml - tomcat80 - Git at Google

 <?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="http://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&apos;s
 <a href="http://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 &lt;jsp:plugin&gt; 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 white spaces in template text between
 actions or directives be trimmed ?, 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> which can be changed with the
 <code>org.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING</code> system
 property.</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}"
              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}/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=&lt;$TOMCAT_HOME&gt; -Dwebapp.path=&lt;$WEBAPP_PATH&gt;</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=&quot;1.6&quot; target=&quot;1.6&quot;</code>. For live
 applications you can also compile with <code>optimize=&quot;on&quot;</code> and
 without debug info <code>debug=&quot;off&quot;</code>.
 </p>

 <p>
 When you don't want to stop the jsp generation at first jsp syntax error, use
 <code>failOnError=&quot;false&quot;</code>and with
 <code>showSuccess=&quot;true&quot;</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>
	<?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="http://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="http://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 white spaces in template text between
	actions or directives be trimmed ?, 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> which can be changed with the
	<code>org.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING</code> system
	property.</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}"
	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}/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 compile with <code>optimize="on"</code> and
	without debug info <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>