|
|
Tomcat example source code file (jasper-howto.xml)
This example Tomcat source code file (jasper-howto.xml) is included in the DevDaily.com
"Java Source Code
Warehouse" project. The intent of this project is to help you "Learn Java by Example" TM.
The Tomcat jasper-howto.xml source code
<?xml version="1.0"?>
<!--
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 email="pero@apache.org">Peter Rossbach
<title>Jasper 2 JSP Engine How To
</properties>
<body>
<section name="Table of Contents">
<p>
<a href="#Introduction">Introduction
<a href="#Configuration">Configuration
<a href="#Production Configuration">Production Configuration
<a href="#Web Application Compilation">Web Application Compilation
<a href="#Using Jikes">Using Jikes
</p>
</section>
<section name="Introduction">
<p>Tomcat 6.0 uses the Jasper 2 JSP Engine to implement
the <a href="http://java.sun.com/products/jsp/">JavaServer Pages 2.0
specification.</p>
<p>Jasper 2 has been redesigned to significantly improve performance over
the orignal Jasper. In addition to general code improvements the following
changes were made:
<ul>
<li>JSP Custom Tag Pooling - 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>Background JSP compilation - 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 availablity
of your JSP pages on a production server.</li>
<li>Recompile JSP when included page changes - 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>JDT used to compile JSP pages - 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>
<p>Jasper is implemented using the servlet class
<code>org.apache.jasper.servlet.JspServlet.
</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.
<ul>
<li>checkInterval - 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 seconds.
<li>classdebuginfo - Should the class file be compiled with
debugging information? <code>true or false, default
<code>true.
</li>
<li>classpath - 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>compiler - Which compiler Ant should use to compile JSP
pages. See the Ant documentation for more information. If the value is not set,
then the default Eclipse JDT Java compiler will be used instead of using Ant.
No default value.</li>
<li>compilerSourceVM - What JDK version are the source files
compatible with? (Default JDK 1.4)</li>
<li>compilerTargetVM - What JDK version are the generated files
compatible with? (Default JDK 1.4)</li>
<li>development - 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 or false,
default <code>true.
<li>displaySourceFragment - Should a source fragment be
included in exception messages? <code>true or false,
default <code>true.
<li>dumpSmap - Should the SMAP info for JSR45 debugging be
dumped to a file? <code>true or false, default
<code>false. false if suppressSmap is true.
<li>enablePooling - Determines whether tag handler pooling is
enabled. <code>true or false, default true.
</li>
<li>engineOptionsClass - Allows specifying the Options class
used to configure Jasper. If not present, the default EmbeddedServletOptions
will be used.
</li>
<li>errorOnUseBeanInvalidClassAttribute - Should Jasper issue
an error when the value of the class attribute in an useBean action is not a
valid bean class? <code>true or false, default
<code>true.
<li>fork - Have Ant fork JSP page compiles so they are
performed in a seperate JVM from Tomcat? <code>true or
<code>false, default true.
<li>genStringAsCharArray - Should text strings be generated as char
arrays, to improve performance in some cases? Default <code>false.
<li>ieClassId - The class-id value to be sent to Internet
Explorer when using <jsp:plugin> tags. Default
<code>clsid:8AD9C840-044E-11D1-B3E9-00805F499D93.
<li>javaEncoding - Java file encoding to use for generating
java source files. Default <code>UTF8.
<li>keepgenerated - Should we keep the generated Java source
code for each page instead of deleting it? <code>true or
<code>false, default true.
<li>mappedfile - Should we generate static content with one
print statement per input line, to ease debugging?
<code>true or false, default true.
<li>modificationTestInterval - 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 seconds.
<li>scratchdir - What scratch directory should we use when
compiling JSP pages? Default is the work directory for the current web
application.</li>
<li>suppressSmap - Should the generation of SMAP info for JSR45
debugging be suppressed? <code>true or false, default
<code>false.
<li>trimSpaces - Should white spaces in template text between
actions or directives be trimmed ?, default <code>false.
<li>xpoweredBy - Determines whether X-Powered-By response
header is added by generated servlet. <code>true or false,
default <code>false.
</ul>
</p>
<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 simply removing the <code>lib/jasper-jdt.jar file,
and placing the <code>ant.jar file from the latest Ant distribution in
the <code>lib folder. If you do this, you also need to use the "javac"
argument to catalina.sh.</p>
</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.
<ul>
<li>development - To disable on access checks for JSP
pages compilation set this to <code>false.
<li>genStringAsCharArray - To generate slightly more efficient
char arrays, set this to <code>true.
<li>modificationTestInterval - If development has to be set to
<code>true for any reason (such as dynamic generation of JSPs), setting
this to a high value will improve performance a lot.</li>
<li>trimSpaces - To remove useless bytes from the response,
set this to <code>true.
</ul>
</p>
</section>
<section name="Web Application Compilation">
<p>Using Ant is the preferred way to compile web applications using JSPC.
Use the script given below (a similar script is included in the "deployer"
download) to precompile a webapp:
</p>
<p>
<source>
<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}/common/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>
<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):<br/>
<source>
$ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH>
</source>
</p>
<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
at the right place inside the <code>${webapp.path}/WEB-INF/web.xml 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 jasper2 task you can use the option <code>addWebXmlMappings for
automatic merge the <code>${webapp.path}/WEB-INF/generated_web.xml
with the current web application deployment descriptor at
<code>${webapp.path}/WEB-INF/web.xml. When you want to use Java 5
features inside your jsp's, add the following javac compiler task attributes:
<code>source="1.5" target="1.5". For live
applications you can also compile with <code>optimize="on" and
without debug info <code>debug="off".
</p>
<p>
When you don't want to stop the jsp generation at first jsp syntax error, use
<code>failOnError="false"and with
<code>showSuccess="true" all successfull jsp to java
generation are printed out. Sometimes it is very helpfull, when you cleanup the
generate java source files at <code>${webapp.path}/WEB-INF/src
and the compile jsp servlet classes at
<code>${webapp.path}/WEB-INF/classes/org/apache/jsp.
</p>
<p>Hints:
<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 tag pooling
<code>org.apache.jasper.runtime.JspFactoryImpl.USE_POOL=false.
and limit the buffering with
<code>org.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true. Note
that changing from the defaults may affect performance, but it will vary
depending on the application.</li>
</ul>
</p>
</section>
<section name="Using Jikes">
<p>If you wish to use
<a href="http://oss.software.ibm.com/developerworks/opensource/jikes/">
Jikes</a> to compile JSP pages:
<ul>
<li>From your Ant installation, copy ant.jar
and (if it's available: Ant 1.5 and later) ant-launcher.jar to
<code>$CATALINA_BASE/lib.
<li>Download and install jikes. jikes must support the -encoding option.
Execute <code>jikes -help to verify that it was built with support
for <code>-encoding.
<li>Set the init parameter compiler to jikes.
<li>Define the property -Dbuild.compiler.emacs=true when starting
Tomcat by adding it to your <code>CATALINA_OPTS environment variable.
This changes how jikes outputs error messages so that it is compatible with
Jasper.</li>
<li>If you get an error reporting that jikes can't use UTF8 encoding, try
setting the init parameter <code>javaEncoding to
<code>ISO-8859-1.
</ul>
</p>
</section>
</body>
</document>
Other Tomcat examples (source code examples)
Here is a short list of links related to this Tomcat jasper-howto.xml source code file:
|
The search page
Other Tomcat source code examples at this package level
Click here to learn more about this project
