source: nutchez-0.1/tomcat/webapps/docs/jasper-howto.html @ 95

Last change on this file since 95 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 21.7 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Jasper 2 JSP Engine How To</title><meta value="Glenn L. Nielsen" name="author"><meta value="glenn@apache.org" name="email"><meta value="Peter Rossbach" name="author"><meta value="pero@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2      The Apache Tomcat Servlet/JSP Container
3    " align="right" src="./images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="./images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat 6.0</h1><h2>Jasper 2 JSP Engine How To</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/jasper-howto.html"><img alt="Printer Friendly Version" border="0" src="./images/printer.gif"><br>print-friendly<br>version
4                    </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
5<p>
6<a href="#Introduction">Introduction</a><br>
7<a href="#Configuration">Configuration</a><br>
8<a href="#Production Configuration">Production Configuration</a><br>
9<a href="#Web Application Compilation">Web Application Compilation</a><br>
10<a href="#Using Jikes">Using Jikes</a><br>
11</p>
12</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
13
14<p>Tomcat 6.0 uses the Jasper 2 JSP Engine to implement
15the <a href="http://java.sun.com/products/jsp/">JavaServer Pages 2.0</a>
16specification.</p>
17
18<p>Jasper 2 has been redesigned to significantly improve performance over
19the orignal Jasper.  In addition to general code improvements the following
20changes were made:
21<ul>
22<li><strong>JSP Custom Tag Pooling</strong> - The java objects instantiated
23for JSP Custom Tags can now be pooled and reused.  This significantly boosts
24the performance of JSP pages which use custom tags.</li>
25<li><strong>Background JSP compilation</strong> - If you make a change to
26a JSP page which had already been compiled Jasper 2 can recompile that
27page in the background.  The previously compiled JSP page will still be
28available to serve requests.  Once the new page has been compiled
29successfully it will replace the old page.  This helps improve availablity
30of your JSP pages on a production server.</li>
31<li><strong>Recompile JSP when included page changes</strong> - Jasper 2
32can now detect when a page included at compile time from a JSP has changed
33and then recompile the parent JSP.</li>
34<li><strong>JDT used to compile JSP pages</strong> - The
35Eclipse JDT Java compiler is now used to perform JSP java source code
36compilation. This compiler loads source dependencies from the container
37classloader. Ant and javac can still be used.</li>
38</ul>
39</p>
40
41<p>Jasper is implemented using the servlet class
42<code>org.apache.jasper.servlet.JspServlet</code>.</p>
43
44</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Configuration"><strong>Configuration</strong></a></font></td></tr><tr><td><blockquote>
45
46<p>By default Jasper is configured for use when doing web application
47development.  See the section <a href="#Production Configuration">
48Production Configuration</a> for information on configuring Jasper
49for use on a production Tomcat server.</p>
50
51<p>The servlet which implements Jasper is configured using init parameters
52in your global <code>$CATALINA_BASE/conf/web.xml</code>.
53
54<ul>
55<li><strong>checkInterval</strong> - If development is false and checkInterval
56is greater than zero, background compiles are enabled. checkInterval is the time
57in seconds between checks to see if a JSP page (and its dependent files) needs
58to be recompiled. Default <code>0</code> seconds.</li>
59
60<li><strong>classdebuginfo</strong> - Should the class file be compiled with
61debugging information?  <code>true</code> or <code>false</code>, default
62<code>true</code>.
63</li>
64
65<li><strong>classpath</strong> - Defines the class path to be used to compile
66the generated servlets. This parameter only has an effect if the ServletContext
67attribute org.apache.jasper.Constants.SERVLET_CLASSPATH is not set. This
68attribute is always set when Jasper is used within Tomcat. By default the
69classpath is created dynamically based on the current web application.</li>
70
71<li><strong>compiler</strong> - Which compiler Ant should use to compile JSP
72pages.  See the Ant documentation for more information. If the value is not set,
73then the default Eclipse JDT Java compiler will be used instead of using Ant.
74No default value.</li>
75
76<li><strong>compilerSourceVM</strong> - What JDK version are the source files
77compatible with? (Default JDK 1.4)</li>
78
79<li><strong>compilerTargetVM</strong> - What JDK version are the generated files
80compatible with? (Default JDK 1.4)</li>
81
82<li><strong>development</strong> - Is Jasper used in development mode? If true,
83the frequency at which JSPs are checked for modification may be specified via
84the modificationTestInterval parameter.<code>true</code> or <code>false</code>,
85default <code>true</code>.</li>
86
87<li><strong>displaySourceFragment</strong> - Should a source fragment be
88included in exception messages? <code>true</code> or <code>false</code>,
89default <code>true</code>.</li>
90
91<li><strong>dumpSmap</strong> - Should the SMAP info for JSR45 debugging be
92dumped to a file? <code>true</code> or <code>false</code>, default
93<code>false</code>. <code>false</code> if suppressSmap is true.</li>
94
95<li><strong>enablePooling</strong> - Determines whether tag handler pooling is
96enabled. <code>true</code> or <code>false</code>, default <code>true</code>.
97</li>
98
99<li><strong>engineOptionsClass</strong> - Allows specifying the Options class
100used to configure Jasper. If not present, the default EmbeddedServletOptions
101will be used.
102</li>
103
104<li><strong>errorOnUseBeanInvalidClassAttribute</strong> - Should Jasper issue
105an error when the value of the class attribute in an useBean action is not a
106valid bean class? <code>true</code> or <code>false</code>, default
107<code>true</code>.</li>
108
109<li><strong>fork</strong> - Have Ant fork JSP page compiles so they are
110performed in a seperate JVM from Tomcat? <code>true</code> or
111<code>false</code>, default <code>true</code>.</li>
112
113<li><strong>genStringAsCharArray</strong> - Should text strings be generated as char
114arrays, to improve performance in some cases? Default <code>false</code>.</li>
115
116<li><strong>ieClassId</strong> - The class-id value to be sent to Internet
117Explorer when using &lt;jsp:plugin&gt; tags.   Default
118<code>clsid:8AD9C840-044E-11D1-B3E9-00805F499D93</code>.</li>
119
120<li><strong>javaEncoding</strong> - Java file encoding to use for generating
121java source files. Default <code>UTF8</code>.</li>
122
123<li><strong>keepgenerated</strong> - Should we keep the generated Java source
124code for each page instead of deleting it? <code>true</code> or
125<code>false</code>, default <code>true</code>.</li>
126
127<li><strong>mappedfile</strong> - Should we generate static content with one
128print statement per input line, to ease debugging?
129<code>true</code> or <code>false</code>, default <code>true</code>.</li>
130
131<li><strong>modificationTestInterval</strong> - Causes a JSP (and its dependent
132files) to not be checked for modification during the specified time interval
133(in seconds) from the last time the JSP was checked for modification. A value of
1340 will cause the JSP to be checked on every access. Used in development mode
135only. Default is <code>4</code> seconds.</li>
136
137<li><strong>scratchdir</strong> - What scratch directory should we use when
138compiling JSP pages? Default is the work directory for the current web
139application.</li>
140
141<li><strong>suppressSmap</strong> - Should the generation of SMAP info for JSR45
142debugging be suppressed? <code>true</code> or <code>false</code>, default
143<code>false</code>.</li>
144 
145<li><strong>trimSpaces</strong> - Should white spaces in template text between
146actions or directives be trimmed ?, default <code>false</code>.</li>
147
148<li><strong>xpoweredBy</strong> - Determines whether X-Powered-By response
149header is added by generated servlet. <code>true</code> or <code>false</code>,
150default <code>false</code>.</li>
151</ul>
152</p>
153
154<p>The Java compiler from Eclipse JDT in included as the default compiler. It is
155an advanced Java compiler which will load all dependencies from the Tomcat class
156loader, which will help tremendously when compiling on large installations with
157tens of JARs. On fast servers, this will allow sub-second recompilation cycles
158for even large JSP  pages.</p>
159
160<p>Apache Ant, which was used in previous Tomcat releases, can be used instead
161of the new compiler by simply removing the <code>lib/jasper-jdt.jar</code> file,
162and placing the <code>ant.jar</code> file from the latest Ant distribution in
163the <code>lib</code> folder.  If you do this, you also need to use the "javac"
164argument to catalina.sh.</p>
165
166</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Production Configuration"><strong>Production Configuration</strong></a></font></td></tr><tr><td><blockquote>
167
168<p>The main JSP optimization which can be done is precompilation of JSPs.
169However, this might not be possible (for example, when using the
170jsp-property-group feature) or practical, in which case the configuration of the
171Jasper servlet becomes critical.</p>
172
173<p>When using Jasper 2 in a production Tomcat server you should consider making
174the following changes from the default configuration.
175<ul>
176<li><strong>development</strong> - To disable on access checks for JSP
177pages compilation set this to <code>false</code>.</li>
178<li><strong>genStringAsCharArray</strong> - To generate slightly more efficient
179char arrays, set this to <code>true</code>.</li>
180<li><strong>modificationTestInterval</strong> - If development has to be set to
181<code>true</code> for any reason (such as dynamic generation of JSPs), setting
182this to a high value will improve performance a lot.</li>
183<li><strong>trimSpaces</strong> - To remove useless bytes from the response,
184set this to <code>true</code>.</li>
185</ul>
186</p>
187
188</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Web Application Compilation"><strong>Web Application Compilation</strong></a></font></td></tr><tr><td><blockquote>
189
190<p>Using Ant is the preferred way to compile web applications using JSPC.
191Use the script given below (a similar script is included in the "deployer"
192download) to precompile a webapp:
193</p>
194
195<p>
196<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
197&lt;project name="Webapp Precompilation" default="all" basedir="."&gt; 
198
199   &lt;import file="${tomcat.home}/bin/catalina-tasks.xml"/&gt;
200 
201   &lt;target name="jspc"&gt; 
202
203    &lt;jasper
204             validateXml="false"
205             uriroot="${webapp.path}"
206             webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml"
207             outputDir="${webapp.path}/WEB-INF/src" /&gt; 
208
209  &lt;/target&gt; 
210
211  &lt;target name="compile"&gt;
212
213    &lt;mkdir dir="${webapp.path}/WEB-INF/classes"/&gt;
214    &lt;mkdir dir="${webapp.path}/WEB-INF/lib"/&gt;
215
216    &lt;javac destdir="${webapp.path}/WEB-INF/classes"
217           optimize="off"
218           debug="on" failonerror="false"
219           srcdir="${webapp.path}/WEB-INF/src"
220     excludes="**/*.smap"&gt;
221      &lt;classpath&gt;
222        &lt;pathelement location="${webapp.path}/WEB-INF/classes"/&gt;
223        &lt;fileset dir="${webapp.path}/WEB-INF/lib"&gt;
224          &lt;include name="*.jar"/&gt;
225        &lt;/fileset&gt;
226        &lt;pathelement location="${tomcat.home}/lib"/&gt;
227        &lt;fileset dir="${tomcat.home}/common/lib"&gt;
228          &lt;include name="*.jar"/&gt;
229        &lt;/fileset&gt;
230        &lt;fileset dir="${tomcat.home}/bin"&gt; 
231          &lt;include name="*.jar"/&gt; 
232        &lt;/fileset&gt; 
233      &lt;/classpath&gt;
234      &lt;include name="**" /&gt;
235      &lt;exclude name="tags/**" /&gt;
236    &lt;/javac&gt;
237
238  &lt;/target&gt;
239
240  &lt;target name="all" depends="jspc,compile"&gt;
241  &lt;/target&gt;
242
243  &lt;target name="cleanup"&gt;
244    &lt;delete&gt;
245        &lt;fileset dir="${webapp.path}/WEB-INF/src"/&gt;
246        &lt;fileset dir="${webapp.path}/WEB-INF/classes/org/apache/jsp"/&gt;
247    &lt;/delete&gt;
248  &lt;/target&gt;
249
250&lt;/project&gt;
251</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
252</p>
253
254<p>
255The following command line can be used to run the script
256(replacing the tokens with the Tomcat base path and the path to the webapp
257which should be precompiled):<br>
258<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
259$ANT_HOME/bin/ant -Dtomcat.home=&lt;$TOMCAT_HOME&gt; -Dwebapp.path=&lt;$WEBAPP_PATH&gt;
260</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
261</p>
262
263<p>
264Then, the declarations and mappings for the servlets which were generated
265during the precompilation must be added to the web application deployment
266descriptor. Insert the <code>${webapp.path}/WEB-INF/generated_web.xml</code>
267at the right place inside the <code>${webapp.path}/WEB-INF/web.xml</code> file.
268Restart the web application (using the manager) and test it to verify it is
269running fine with precompiled servlets. An appropriate token placed in the
270web application deployment descriptor may also be used to automatically
271insert the generated servlet declarations and mappings using Ant filtering
272capabilities. This is actually how all the webapps distributed with Tomcat
273are automatically compiled as part of the build process.
274</p>
275
276<p>
277At the jasper2 task you can use the option <code>addWebXmlMappings</code> for
278automatic merge the <code>${webapp.path}/WEB-INF/generated_web.xml</code>
279with the current web application deployment descriptor at
280<code>${webapp.path}/WEB-INF/web.xml</code>. When you want to use Java 5
281features inside your jsp's, add the following javac compiler task attributes:
282<code>source="1.5" target="1.5"</code>. For live
283applications you can also compile with <code>optimize="on"</code> and
284without debug info <code>debug="off"</code>.
285</p>
286
287<p>
288When you don't want to stop the jsp generation at first jsp syntax error, use   
289<code>failOnError="false"</code>and with
290<code>showSuccess="true"</code> all successfull <i>jsp to java</i>
291generation are printed out. Sometimes it is very helpfull, when you cleanup the
292generate java source files at <code>${webapp.path}/WEB-INF/src</code>
293and the compile jsp servlet classes at
294<code>${webapp.path}/WEB-INF/classes/org/apache/jsp</code>.
295</p>
296
297<p><strong>Hints:</strong>
298<ul>
299<li> When you switch to another Tomcat release, then regenerate and recompile
300your jsp's with the new Tomcat version.</li>
301<li>Use java system property at server runtime to disable tag pooling
302<code>org.apache.jasper.runtime.JspFactoryImpl.USE_POOL=false</code>.
303and limit the buffering with
304<code>org.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true</code>. Note
305that changing from the defaults may affect performance, but it will vary
306depending on the application.</li>
307</ul>
308</p>
309</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Using Jikes"><strong>Using Jikes</strong></a></font></td></tr><tr><td><blockquote>
310
311<p>If you wish to use
312<a href="http://oss.software.ibm.com/developerworks/opensource/jikes/">
313Jikes</a> to compile JSP pages:
314<ul>
315<li>From your <a href="ant.apache.org">Ant</a> installation, copy ant.jar
316and (if it's available: Ant 1.5 and later) ant-launcher.jar to
317<code>$CATALINA_HOME/lib</code>.</li>
318<li>Download and install jikes. jikes must support the -encoding option.
319Execute <code>jikes -help</code> to verify that it was built with support
320for <code>-encoding</code>.</li>
321<li>Set the init parameter <code>compiler</code> to <code>jikes</code>.</li>
322<li>Define the property <code>-Dbuild.compiler.emacs=true</code> when starting
323Tomcat by adding it to your <code>CATALINA_OPTS</code> environment variable.
324This changes how jikes outputs error messages so that it is compatible with
325Jasper.</li>
326<li>If you get an error reporting that jikes can't use UTF8 encoding, try
327setting the init parameter <code>javaEncoding</code> to
328<code>ISO-8859-1</code>.</li>
329</ul>
330</p>
331
332</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
333        Copyright &copy; 1999-2008, Apache Software Foundation
334        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.