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

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

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