You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by re...@apache.org on 2006/07/08 00:40:09 UTC
svn commit: r420006 [13/17] - in /tomcat/tc6.0.x/trunk: res/ res/deployer/
webapps/docs/ webapps/docs/META-INF/ webapps/docs/WEB-INF/
webapps/docs/api/ webapps/docs/appdev/ webapps/docs/appdev/sample/
webapps/docs/appdev/sample/docs/ webapps/docs/appde...
Added: tomcat/tc6.0.x/trunk/webapps/docs/jasper-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/jasper-howto.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/jasper-howto.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/jasper-howto.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,345 @@
+<?xml version="1.0"?>
+<!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">
+<p>
+<a href="#Introduction">Introduction</a><br />
+<a href="#Configuration">Configuration</a><br />
+<a href="#Production Configuration">Production Configuration</a><br />
+<a href="#Web Application Compilation">Web Application Compilation</a><br />
+<a href="#Using Jikes">Using Jikes</a><br />
+</p>
+</section>
+
+<section name="Introduction">
+
+<p>Tomcat 5.5 uses the Jasper 2 JSP Engine to implement
+the <a href="http://java.sun.com/products/jsp/">JavaServer Pages 2.0</a>
+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><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 availablity
+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>
+
+<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>.
+
+<ul>
+<li><strong>checkInterval</strong> - If development is false and reloading is
+true, background compiles are enabled. checkInterval is the time in seconds
+between checks to see if a JSP page needs to be recompiled. Default
+<code>300</code> seconds.</li>
+
+<li><strong>compiler</strong> - 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><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> - What class path should I use while compiling
+generated servlets? By default the classpath is created dynamically based on
+the current web application.</li>
+
+<li><strong>compilerSourceVM</strong> - What JDK version are the source files compatible with? (Default JDK 1.4)</li>
+
+<li><strong>compilerTargetVM</strong> - What JDK version are the generated files compatible with? (Default JDK 1.4)</li>
+
+<li><strong>development</strong> - Is Jasper used in development mode (will
+check for JSP modification on every access)? <code>true</code> or
+<code>false</code>, default <code>true</code>.</li>
+
+<li><strong>enablePooling</strong> - Determines whether tag handler pooling is
+enabled. <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.
+</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>fork</strong> - Have Ant fork JSP page compiles so they are
+performed in a seperate JVM from Tomcat? <code>true</code> or
+<code>false</code>, default <code>true</code>.</li>
+
+<li><strong>javaEncoding</strong> - Java file encoding to use for generating
+java source files. Default <code>UTF8</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>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>modificationTestInterval</strong> - Checks for modification for a given
+JSP file (and all its dependent files) will be performed only once every specified amount
+of seconds. Setting this to 0 will cause the JSP to be checked on every access.
+Default is <code>4</code> seconds.</li>
+
+<li><strong>reloading</strong> - Should Jasper check for modified JSPs?
+<code>true</code> or <code>false</code>, default <code>false</code>.</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.</li>
+
+<li><strong>trimSpaces</strong> - Should white spaces in template text between
+actions or directives be trimmed ?, default <code>false</code>.</li>
+</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. This new compiler will be updated to support the Java 5 syntax as soon as
+possible.</p>
+
+<p>Apache Ant, which was used in previous Tomcat releases, can be used instead instead of
+the new compiler by simply removing the <code>common/lib/jasper-compiler-jdt.jar</code> file,
+and placing the <code>ant.jar</code> file from the latest Ant distribution in the
+<code>common/lib</code> 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><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>
+</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=".">
+
+ <target name="jspc">
+
+ <taskdef classname="org.apache.jasper.JspC" name="jasper2" >
+ <classpath id="jspc.classpath">
+ <pathelement location="${java.home}/../lib/tools.jar"/>
+ <fileset dir="${tomcat.home}/bin">
+ <include name="*.jar"/>
+ </fileset>
+ <fileset dir="${tomcat.home}/server/lib">
+ <include name="*.jar"/>
+ </fileset>
+ <fileset dir="${tomcat.home}/common/lib">
+ <include name="*.jar"/>
+ </fileset>
+ </classpath>
+ </taskdef>
+
+ <jasper2
+ 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}/common/classes"/>
+ <fileset dir="${tomcat.home}/common/lib">
+ <include name="*.jar"/>
+ </fileset>
+ <pathelement location="${tomcat.home}/shared/classes"/>
+ <fileset dir="${tomcat.home}/shared/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</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 jasper2 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 5 feature inside your jsp's, add the following javac compiler task
+attributes: <code>source="1.5" target="1.5"</code>. For live application
+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 successfull <i>jsp to java</i> generation are printed out. Sometimes it is
+very helpfull, 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>
+<ul>
+<li> When you switch to another tomcat release, then regenerate and recompile
+your jsp's with this version again!</li>
+<li>Use java system property at server runtime to disable tag 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 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 <a href="ant.apache.org">Ant</a> installation, copy ant.jar
+and (if it's available: Ant 1.5 and later) ant-launcher.jar to
+<code>$CATALINA_BASE/common/lib</code>.</li>
+<li>Download and install jikes. jikes must support the -encoding option.
+Execute <code>jikes -help</code> to verify that it was built with support
+for <code>-encoding</code>.</li>
+<li>Set the init parameter <code>compiler</code> to <code>jikes</code>.</li>
+<li>Define the property <code>-Dbuild.compiler.emacs=true</code> when starting
+Tomcat by adding it to your <code>CATALINA_OPTS</code> 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</code> to
+<code>ISO-8859-1</code>.</li>
+</ul>
+</p>
+
+</section>
+</body>
+
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/jasper-howto.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/jndi-datasource-examples-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/jndi-datasource-examples-howto.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/jndi-datasource-examples-howto.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/jndi-datasource-examples-howto.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,655 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="jndi-datasource-examples-howto.html">
+
+ &project;
+
+ <properties>
+ <author email="leslie.hughes@rubus.com">Les Hughes</author>
+ <author email="david-tomcat@haraburda.com">David Haraburda</author>
+ <author>Glenn Nielsen</author>
+ <author email="yoavs@apache.org">Yoav Shapira</author>
+ <title>JNDI Datasource HOW-TO</title>
+ </properties>
+
+<body>
+
+<section name="Table of Contents">
+<p>
+<a href="#Introduction">Introduction</a><br />
+<a href="#Database Connection Pool (DBCP) Configurations">
+Database Connection Pool (DBCP) Configurations</a><br />
+<a href="#Non DBCP Solutions">Non DBCP Solutions</a><br />
+<a href="#Oracle 8i with OCI client">Oracle 8i with OCI client</a><br />
+<a href="#Common Problems">Common Problems</a><br />
+</p>
+</section>
+
+<section name="Introduction">
+
+<p>JNDI Datasource configuration is covered extensively in the
+JNDI-Resources-HOWTO. However, feedback from <code>tomcat-user</code> has
+shown that specifics for individual configurations can be rather tricky.</p>
+
+<p>Here then are some example configurations that have been posted to
+tomcat-user for popular databases and some general tips for db useage.</p>
+
+<p>You should be aware that since these notes are derived from configuration
+and/or feedback posted to <code>tomcat-user</code> YMMV :-). Please let us
+know if you have any other tested configurations that you feel may be of use
+to the wider audience, or if you feel we can improve this section in anyway.</p>
+
+<p>
+<b>Please note that JNDI resource configuration has changed somewhat between
+Tomcat 5.0.x and Tomcat 5.5.x.</b> You will most likely need to modify your JNDI
+resource configurations to match the syntax in the example below in order
+to make them work in Tomcat 5.5.x.
+</p>
+
+<p>
+Also, please note that JNDI DataSource configuration in general, and this
+tutorial in particular, assumes that you have read and understood the
+<a href="config/context.html">Context</a> and
+<a href="config/host.html">Host</a> configuration references, including
+the section about Automatic Application Deployment in the latter reference.
+</p>
+</section>
+
+<section name="Database Connection Pool (DBCP) Configurations">
+
+<p>DBCP provides support for JDBC 2.0. On systems using a 1.4 JVM DBCP
+will support JDBC 3.0. Please let us know if you have used DBCP and its
+JDBC 3.0 features with a 1.4 JVM.
+</p>
+
+<p>See the <a href="http://jakarta.apache.org/commons/dbcp/configuration.html">
+DBCP documentation</a> for a complete list of configuration parameters.
+</p>
+
+<subsection name="Installation">
+<p>DBCP uses the Jakarta-Commons Database Connection Pool. It relies on
+number of Jakarta-Commons components:
+<ul>
+<li>Jakarta-Commons DBCP</li>
+<li>Jakarta-Commons Collections</li>
+<li>Jakarta-Commons Pool</li>
+</ul>
+These libraries are located in a single JAR at
+<code>$CATALINA_HOME/common/lib/naming-factory-dbcp.jar</code>. However,
+only the classes needed for connection pooling have been included, and the
+packages have been renamed to avoid interfering with applications.
+</p>
+
+</subsection>
+
+<subsection name="Preventing dB connection pool leaks">
+
+<p>
+A database connection pool creates and manages a pool of connections
+to a database. Recycling and reusing already existing connections
+to a dB is more efficient than opening a new connection.
+</p>
+
+<p>
+There is one problem with connection pooling. A web application has
+to explicetely close ResultSet's, Statement's, and Connection's.
+Failure of a web application to close these resources can result in
+them never being available again for reuse, a db connection pool "leak".
+This can eventually result in your web application db connections failing
+if there are no more available connections.</p>
+
+<p>
+There is a solution to this problem. The Jakarta-Commons DBCP can be
+configured to track and recover these abandoned dB connections. Not
+only can it recover them, but also generate a stack trace for the code
+which opened these resources and never closed them.</p>
+
+<p>
+To configure a DBCP DataSource so that abandoned dB connections are
+removed and recycled add the following attribute to the
+<code>Resource</code> configuration for your DBCP DataSource:
+<source>
+ removeAbandoned="true"
+</source>
+When available db connections run low DBCP will recover and recyle
+any abandoned dB connections it finds. The default is <code>false</code>.
+</p>
+
+<p>
+Use the <code>removeAbandonedTimeout</code> attribute to set the number
+of seconds a dB connection has been idle before it is considered abandoned.
+<source>
+ removeAbandonedTimeout="60"
+</source>
+The default timeout for removing abandoned connections is 300 seconds.
+</p>
+
+<p>
+The <code>logAbandoned</code> attribute can be set to <code>true</code>
+if you want DBCP to log a stack trace of the code which abandoned the
+dB connection resources.
+<source>
+ logAbandoned="true"
+</source>
+The default is <code>false</code>.
+</p>
+
+</subsection>
+
+<subsection name="MySQL DBCP Example">
+
+<h3>0. Introduction</h3>
+<p>Versions of <a href="http://www.mysql.com/products/mysql/index.html">MySQL</a> and JDBC drivers that have been reported to work:
+<ul>
+<li>MySQL 3.23.47, MySQL 3.23.47 using InnoDB,, MySQL 3.23.58, MySQL 4.0.1alpha</li>
+<li><a href="http://www.mysql.com/products/connector-j">Connector/J</a> 3.0.11-stable (the official JDBC Driver)</li>
+<li><a href="http://mmmysql.sourceforge.net">mm.mysql</a> 2.0.14 (an old 3rd party JDBC Driver)</li>
+</ul>
+</p>
+
+<p>Before you proceed, don't forget to copy the JDBC Driver's jar into <code>$CATALINA_HOME/common/lib</code>.</p>
+
+<h3>1. MySQL configuration</h3>
+<p>
+Ensure that you follow these instructions as variations can cause problems.
+</p>
+
+<p>Create a new test user, a new database and a single test table.
+Your MySQL user <strong>must</strong> have a password assigned. The driver
+will fail if you try to connect with an empty password.
+<source>
+mysql> GRANT ALL PRIVILEGES ON *.* TO javauser@localhost
+ -> IDENTIFIED BY 'javadude' WITH GRANT OPTION;
+mysql> create database javatest;
+mysql> use javatest;
+mysql> create table testdata (
+ -> id int not null auto_increment primary key,
+ -> foo varchar(25),
+ -> bar int);
+</source>
+<blockquote>
+<strong>Note:</strong> the above user should be removed once testing is
+complete!
+</blockquote>
+</p>
+
+<p>Next insert some test data into the testdata table.
+<source>
+mysql> insert into testdata values(null, 'hello', 12345);
+Query OK, 1 row affected (0.00 sec)
+
+mysql> select * from testdata;
++----+-------+-------+
+| ID | FOO | BAR |
++----+-------+-------+
+| 1 | hello | 12345 |
++----+-------+-------+
+1 row in set (0.00 sec)
+
+mysql>
+</source>
+</p>
+
+<h3>2. server.xml configuration</h3>
+<p>Configure the JNDI DataSource in Tomcat by adding a declaration for your
+resource to <code>$CATALINA_HOME/conf/server.xml</code>.</p>
+<p>Add this in between the <code></Context></code> tag of the examples
+context and the <code></Host></code> tag closing the localhost definition.
+If there is no such tag, you can add one as illustrated in the
+<a href="config/context.html">Context</a> and
+<a href="config/host.html">Host</a> configuration references, and repeated below
+for your convenience.
+
+<source>
+<Context path="/DBTest" docBase="DBTest"
+ debug="5" reloadable="true" crossContext="true">
+
+ <!-- maxActive: Maximum number of dB connections in pool. Make sure you
+ configure your mysqld max_connections large enough to handle
+ all of your db connections. Set to 0 for no limit.
+ -->
+
+ <!-- maxIdle: Maximum number of idle dB connections to retain in pool.
+ Set to -1 for no limit. See also the DBCP documentation on this
+ and the minEvictableIdleTimeMillis configuration parameter.
+ -->
+
+ <!-- maxWait: Maximum time to wait for a dB connection to become available
+ in ms, in this example 10 seconds. An Exception is thrown if
+ this timeout is exceeded. Set to -1 to wait indefinitely.
+ -->
+
+ <!-- username and password: MySQL dB username and password for dB connections -->
+
+ <!-- driverClassName: Class name for the old mm.mysql JDBC driver is
+ org.gjt.mm.mysql.Driver - we recommend using Connector/J though.
+ Class name for the official MySQL Connector/J driver is com.mysql.jdbc.Driver.
+ -->
+
+ <!-- url: The JDBC connection url for connecting to your MySQL dB.
+ The autoReconnect=true argument to the url makes sure that the
+ mm.mysql JDBC Driver will automatically reconnect if mysqld closed the
+ connection. mysqld by default closes idle connections after 8 hours.
+ -->
+
+ <Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource"
+ maxActive="100" maxIdle="30" maxWait="10000"
+ username="javauser" password="javadude" driverClassName="com.mysql.jdbc.Driver"
+ url="jdbc:mysql://localhost:3306/javatest?autoReconnect=true"/>
+
+</Context>
+</source>
+</p>
+
+<h3>3. web.xml configuration</h3>
+
+<p>Now create a <code>WEB-INF/web.xml</code> for this test application.
+<source>
+<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
+http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
+ version="2.4">
+ <description>MySQL Test App</description>
+ <resource-ref>
+ <description>DB Connection</description>
+ <res-ref-name>jdbc/TestDB</res-ref-name>
+ <res-type>javax.sql.DataSource</res-type>
+ <res-auth>Container</res-auth>
+ </resource-ref>
+</web-app>
+</source>
+</p>
+
+<h3>4. Test code</h3>
+<p>Now create a simple <code>test.jsp</code> page for use later.
+<source>
+<%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %>
+<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
+
+<sql:query var="rs" dataSource="jdbc/TestDB">
+select id, foo, bar from testdata
+</sql:query>
+
+<html>
+ <head>
+ <title>DB Test</title>
+ </head>
+ <body>
+
+ <h2>Results</h2>
+
+<c:forEach var="row" items="${rs.rows}">
+ Foo ${row.foo}<br/>
+ Bar ${row.bar}<br/>
+</c:forEach>
+
+ </body>
+</html>
+</source>
+</p>
+
+<p>That JSP page makes use of <a href="http://java.sun.com/products/jsp/jstl">JSTL</a>'s SQL and Core taglibs. You can get it from Sun's <a href="http://java.sun.com/webservices/downloads/webservicespack.html">Java Web Services Developer Pack</a> or <a href="http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html">Jakarta Taglib Standard 1.1</a> project - just make sure you get a 1.1.x release. Once you have JSTL, copy <code>jstl.jar</code> and <code>standard.jar</code> to your web app's <code>WEB-INF/lib</code> directory.
+
+</p>
+
+<p>Finally deploy your web app into <code>$CATALINA_HOME/webapps</code> either
+as a warfile called <code>DBTest.war</code> or into a sub-directory called
+<code>DBTest</code></p>
+<p>Once deployed, point a browser at
+<code>http://localhost:8080/DBTest/test.jsp</code> to view the fruits of
+your hard work.</p>
+
+</subsection>
+
+<subsection name="Oracle 8i, 9i & 10g">
+<h3>0. Introduction</h3>
+
+<p>Oracle requires minimal changes from the MySQL configuration except for the
+usual gotchas :-)</p>
+<p>Drivers for older Oracle versions may be distributed as *.zip files rather
+than *.jar files. Tomcat will only use <code>*.jar</code> files installed in
+<code>$CATALINA_HOME/common/lib</code>. Therefore <code>classes111.zip</code>
+or <code>classes12.zip</code> will need to be renamed with a <code>.jar</code>
+extension. Since jarfiles are zipfiles, there is no need to unzip and jar these
+files - a simple rename will suffice.</p>
+
+<p>Some early versions of Tomcat 4.0 when used with JDK 1.4 will not load
+classes12.zip unless you unzip the file, remove the <code>javax.sql.*</code>
+class heirarchy and rejar.</p>
+
+<p>For Oracle 9i onwards you should use <code>oracle.jdbc.OracleDriver</code>
+rather than <code>oracle.jdbc.driver.OracleDriver</code> as Oracle have stated
+that <code>oracle.jdbc.driver.OracleDriver</code> is deprecated and support
+for this driver class will be discontinued in the next major release.
+</p>
+
+<h3>1. server.xml configuration</h3>
+<p>In a similar manner to the mysql config above, you will need to define your
+Datasource in your server.xml file. Here we define a Datasource called myoracle
+using the thin driver to connect as user scott, password tiger to the sid
+called mysid. (Note: with the thin driver this sid is not the same as the
+tnsname). The schema used will be the default schema for the user scott.</p>
+
+<p>Use of the OCI driver should simply involve a changing thin to oci in the URL string.
+<source>
+<Resource name="jdbc/myoracle" auth="Container"
+ type="javax.sql.DataSource" driverClassName="oracle.jdbc.OracleDriver"
+ url="jdbc:oracle:thin:@127.0.0.1:1521:mysid"
+ username="scott" password="tiger" maxActive="20" maxIdle="10"
+ maxWait="-1"/>
+</source>
+</p>
+
+<h3>2. web.xml configuration</h3>
+<p>You should ensure that you respect the elemeent ordering defined by the DTD when you
+create you applications web.xml file.</p>
+<source>
+<resource-ref>
+ <description>Oracle Datasource example</description>
+ <res-ref-name>jdbc/myoracle</res-ref-name>
+ <res-type>javax.sql.DataSource</res-type>
+ <res-auth>Container</res-auth>
+</resource-ref>
+</source>
+<h3>3. Code example</h3>
+<p>You can use the same example application as above (asuming you create the required DB
+instance, tables etc.) replacing the Datasource code with something like</p>
+<source>
+Context initContext = new InitialContext();
+Context envContext = (Context)initContext.lookup("java:/comp/env");
+DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle");
+Connection conn = ds.getConnection();
+//etc.
+</source>
+</subsection>
+
+
+<subsection name="PostgreSQL">
+<h3>0. Introduction</h3>
+<p>PostgreSQL is configured in a similar manner to Oracle.</p>
+
+<h3>1. Required files </h3>
+<p>
+Copy the Postgres JDBC jar to $CATALINA_HOME/common/lib. As with Oracle, the
+jars need to be in this directory in order for DBCP's Classloader to find
+them. This has to be done regardless of which configuration step you take next.
+</p>
+
+<h3>2. Resource configuration</h3>
+
+<p>
+You have two choices here: define a datasource that is shared across all Tomcat
+applications, or define a datasource specifically for one application.
+</p>
+
+<h4>2a. Shared resource configuration</h4>
+<p>
+Use this option if you wish to define a datasource that is shared across
+multiple Tomcat applications, or if you just prefer defining your datasource
+in this file.
+</p>
+<p><i>This author has not had success here, although others have reported so.
+Clarification would be appreciated here.</i></p>
+
+<source>
+<Resource name="jdbc/postgres" auth="Container"
+ type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
+ url="jdbc:postgresql://127.0.0.1:5432/mydb"
+ username="myuser" password="mypasswd" maxActive="20" maxIdle="10" maxWait="-1"/>
+</source>
+<h4>2b. Application-specific resource configuration</h4>
+
+<p>
+Use this option if you wish to define a datasource specific to your application,
+not visible to other Tomcat applications. This method is less invasive to your
+Tomcat installation.
+</p>
+
+<p>
+Create a resource definition file for your application defining the
+datasource. This file must have the same name as your application, so if
+your application deploys as <code>someApp.war</code>, this filename must
+be <code>someApp.xml</code>. This file should look something like the following.
+</p>
+
+<source>
+<Context path="/someApp" docBase="someApp"
+ crossContext="true" reloadable="true" debug="1">
+
+<Resource name="jdbc/postgres" auth="Container"
+ type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
+ url="jdbc:postgresql://127.0.0.1:5432/mydb"
+ username="myuser" password="mypasswd" maxActive="20" maxIdle="10"
+maxWait="-1"/>
+</Context>
+</source>
+
+<h3>3. web.xml configuration</h3>
+<source>
+<resource-ref>
+ <description>postgreSQL Datasource example</description>
+ <res-ref-name>jdbc/postgres</res-ref-name>
+ <res-type>javax.sql.DataSource</res-type>
+ <res-auth>Container</res-auth>
+</resource-ref>
+</source>
+
+<h4>4. Accessing the datasource</h4>
+<p>
+When accessing the datasource programmatically, remember to prepend
+<code>java:/comp/env</code> to your JNDI lookup, as in the following snippet of
+code. Note also that "jdbc/postgres" can be replaced with any value you prefer, provided
+you change it in the above resource definition file as well.
+</p>
+
+<source>
+InitialContext cxt = new InitialContext();
+if ( cxt == null ) {
+ throw new Exception("Uh oh -- no context!");
+}
+
+DataSource ds = (DataSource) cxt.lookup( "java:/comp/env/jdbc/postgres" );
+
+if ( ds == null ) {
+ throw new Exception("Data source not found!");
+}
+</source>
+
+</subsection>
+</section>
+
+<section name="Non-DBCP Solutions">
+<p>
+These solutions either utilise a single connection to the database (not recommended for anything other
+than testing!) or some other pooling technology.
+</p>
+</section>
+
+<section name="Oracle 8i with OCI client">
+<subsection name="Introduction">
+<p>Whilst not strictly addressing the creation of a JNDI DataSource using the OCI client, these notes can be combined with the
+Oracle and DBCP solution above.</p>
+<p>
+In order to use OCI driver, you should have an Oracle client installed. You should have installed
+Oracle8i(8.1.7) client from cd, and download the suitable JDBC/OCI
+driver(Oracle8i 8.1.7.1 JDBC/OCI Driver) from <a href="http://otn.oracle.com/">otn.oracle.com</a>.
+</p>
+<p>
+After renaming <code>classes12.zip</code> file to <code>classes12.jar</code>
+for Tomcat, copy it into <code>$CATALINA_HOME/common/lib</code>.
+You may also have to remove the <code>javax.sql.*</code> classes
+from this file depending upon the version of Tomcat and JDK you are using.
+</p>
+</subsection>
+
+<subsection name="Putting it all together">
+<p>
+Ensure that you have the <code>ocijdbc8.dll</code> or <code>.so</code> in your <code>$PATH</code> or <code>LD_LIBRARY_PATH</code>
+ (possibly in <code>$ORAHOME\bin</code>) and also confirm that the native library can be loaded by a simple test program
+using <code>System.loadLibrary("ocijdbc8");</code>
+</p>
+<p>
+You should next create a simple test servlet or jsp that has these
+<strong>critical lines</strong>:
+</p>
+<source>
+DriverManager.registerDriver(new
+oracle.jdbc.driver.OracleDriver());
+conn =
+DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password");
+</source>
+<p>
+where database is of the form <code>host:port:SID</code> Now if you try to access the URL of your
+test servlet/jsp and what you get is a
+<code>ServletException</code> with a root cause of <code>java.lang.UnsatisfiedLinkError:get_env_handle</code>.
+</p>
+<p>
+First, the <code>UnsatisfiedLinkError</code> indicates that you have
+<ul>
+<li>a mismatch between your JDBC classes file and
+your Oracle client version. The giveaway here is the message stating that a needed library file cannot be
+found. For example, you may be using a classes12.zip file from Oracle Version 8.1.6 with a Version 8.1.5
+Oracle client. The classeXXXs.zip file and Oracle client software versions must match.
+</li>
+<li>A <code>$PATH</code>, <code>LD_LIBRARY_PATH</code> problem.</li>
+<li>It has been reported that ignoring the driver you have downloded from otn and using
+the classes12.zip file from the directory <code>$ORAHOME\jdbc\lib</code> will also work.
+</li>
+</ul>
+</p>
+<p>
+Next you may experience the error <code>ORA-06401 NETCMN: invalid driver designator</code>
+</p>
+<p>
+The Oracle documentation says : "Cause: The login (connect) string contains an invalid
+driver designator. Action: Correct the string and re-submit."
+
+Change the database connect string (of the form <code>host:port:SID</code>) with this one:
+<code>(description=(address=(host=myhost)(protocol=tcp)(port=1521))(connect_data=(sid=orcl)))</code>
+</p>
+<p>
+<i>Ed. Hmm, I don't think this is really needed if you sort out your TNSNames - but I'm not an Oracle DBA :-)</i>
+</p>
+</subsection>
+</section>
+
+<section name="Common Problems">
+<p>Here are some common problems encountered with a web application which
+uses a database and tips for how to solve them.</p>
+
+<subsection name="Intermittent dB Connection Failures">
+<p>
+Tomcat runs within a JVM. The JVM periodically performs garbage collection
+(GC) to remove java objects which are no longer being used. When the JVM
+performs GC execution of code within Tomcat freezes. If the maximum time
+configured for establishment of a dB connection is less than the amount
+of time garbage collection took you can get a db conneciton failure.
+</p>
+
+<p>To collect data on how long garbage collection is taking add the
+<code>-verbose:gc</code> argument to your <code>CATALINA_OPTS</code>
+environment variable when starting Tomcat. When verbose gc is enabled
+your <code>$CATALINA_BASE/logs/catalina.out</code> log file will include
+data for every garbage collection including how long it took.</p>
+
+<p>When your JVM is tuned correctly 99% of the time a GC will take less
+than one second. The remainder will only take a few seconds. Rarely,
+if ever should a GC take more than 10 seconds.</p>
+
+<p>Make sure that the db connection timeout is set to 10-15 seconds.
+For the DBCP you set this using the parameter <code>maxWait</code>.</p>
+
+</subsection>
+
+<subsection name="Random Connection Closed Exceptions">
+<p>
+These can occur when one request gets a db connection from the connection
+pool and closes it twice. When using a connection pool, closing the
+connection just returns it to the pool for reuse by another request,
+it doesn't close the connection. And Tomcat uses multiple threads to
+handle concurrent requests. Here is an example of the sequence
+of events which could cause this error in Tomcat:
+<pre>
+ Request 1 running in Thread 1 gets a db connection.
+
+ Request 1 closes the db connection.
+
+ The JVM switches the running thread to Thread 2
+
+ Request 2 running in Thread 2 gets a db connection
+ (the same db connection just closed by Request 1).
+
+ The JVM switches the running thread back to Thread 1
+
+ Request 1 closes the db connection a second time in a finally block.
+
+ The JVM switches the running thread back to Thread 2
+
+ Request 2 Thread 2 tries to use the db connection but fails
+ because Request 1 closed it.
+</pre>
+Here is an example of properly written code to use a db connection
+obtained from a connection pool:
+<pre>
+ Connection conn = null;
+ Statement stmt = null; // Or PreparedStatement if needed
+ ResultSet rs = null;
+ try {
+ conn = ... get connection from connection pool ...
+ stmt = conn.createStatement("select ...");
+ rs = stmt.executeQuery();
+ ... iterate through the result set ...
+ rs.close();
+ rs = null;
+ stmt.close();
+ stmt = null;
+ conn.close(); // Return to connection pool
+ conn = null; // Make sure we don't close it twice
+ } catch (SQLException e) {
+ ... deal with errors ...
+ } finally {
+ // Always make sure result sets and statements are closed,
+ // and the connection is returned to the pool
+ if (rs != null) {
+ try { rs.close(); } catch (SQLException e) { ; }
+ rs = null;
+ }
+ if (stmt != null) {
+ try { stmt.close(); } catch (SQLException e) { ; }
+ stmt = null;
+ }
+ if (conn != null) {
+ try { conn.close(); } catch (SQLException e) { ; }
+ conn = null;
+ }
+ }
+</pre>
+</p>
+
+</subsection>
+
+<subsection name="Context versus GlobalNamingResources">
+<p>
+ Please note that although the above instructions place the JNDI declarations in a Context
+ element, it is possible and sometimes desirable to place these declarations in the
+ <a href="config/globalresources.html">GlobalNamingResources</a> section of the server
+ configuration file. A resource placed in the GlobalNamingResources section will be shared
+ among the Contexts of the server.
+</p>
+</subsection>
+
+<subsection name="JNDI Resource Naming and Realm Interaction">
+<p>
+ In order to get Realms to work, the realm must refer to the datasource as
+ defined in the <GlobalNamingResources> or <Context> section, not a datasource as renamed
+ using <ResourceLink>.
+</p>
+</subsection>
+
+</section>
+
+</body>
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/jndi-datasource-examples-howto.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,765 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="jndi-resources-howto.html">
+
+ &project;
+
+ <properties>
+ <author email="craigmcc@apache.org">Craig R. McClanahan</author>
+ <author email="yoavs@apache.org">Yoav Shapira</author>
+ <title>JNDI Resources HOW-TO</title>
+ </properties>
+
+<body>
+
+
+<section name="Introduction">
+
+<p>Tomcat 5 provides a JNDI <strong>InitialContext</strong> implementation
+instance for each web application running under it, in a manner that is
+compatible with those provided by a
+<a href="http://java.sun.com/j2ee">Java2 Enterprise Edition</a> application
+server.
+
+The J2EE standard provides a standard set of elements in
+the <code>/WEB-INF/web.xml</code> file to reference resources; resources
+referenced in these elements must be defined in an application-server-specific configuration.
+</p>
+
+<p>For Tomcat 5, these entries in per-web-application
+<code>InitialContext</code> are configured in the
+<code><strong><Context></strong></code> elements that can be specified
+in either <code>$CATALINA_HOME/conf/server.xml</code> or, preferably,
+the per-web-application context XML file (either <code>META-INF/context.xml</code>).
+</p>
+
+<p>Tomcat 5 maintains a separate namespace of global resources for the
+entire server. These are configured in the
+<a href="config/globalresources.html">
+<code><strong><GlobalNameingResources></strong></code></a> element of
+<code>$CATALINA_HOME/conf/server.xml</code>. You may expose these resources to
+web applications by using
+<code><strong><ResourceLink></strong></code> elements.
+</p>
+
+<p>The resources defined in these elements
+may be referenced by the following elements in the web application deployment
+descriptor (<code>/WEB-INF/web.xml</code>) of your web application:</p>
+<ul>
+<li><code><strong><env-entry></strong></code> - Environment entry, a
+ single-value parameter that can be used to configure how the application
+ will operate.</li>
+<li><code><strong><resource-ref></strong></code> - Resource reference,
+ which is typically to an object factory for resources such as a JDBC
+ <code>DataSource</code>, a JavaMail <code>Session</code>, or custom
+ object factories configured into Tomcat 5.</li>
+<li><code><strong><resource-env-ref></strong></code> - Resource
+ environment reference, a new variation of <code>resource-ref</code>
+ added in Servlet 2.4 that is simpler to configure for resources
+ that do not require authentication information.</li>
+</ul>
+
+<p>The <code>InitialContext</code> is configured as a web application is
+initially deployed, and is made available to web application components (for
+read-only access). All configured entries and resources are placed in
+the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
+access to a resource - in this case, to a JDBC <code>DataSource</code> -
+would look something like this:</p>
+
+<source>
+// Obtain our environment naming context
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+
+// Look up our data source
+DataSource ds = (DataSource)
+ envCtx.lookup("jdbc/EmployeeDB");
+
+// Allocate and use a connection from the pool
+Connection conn = ds.getConnection();
+... use this connection to access the database ...
+conn.close();
+</source>
+
+<p>See the following Specifications for more information about programming APIs
+for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE)
+servers, which Tomcat emulates for the services that it provides:</p>
+<ul>
+<li><a href="http://java.sun.com/products/jndi/#download">Java Naming and
+ Directory Interface</a> (included in JDK 1.4, available separately for
+ prior JDK versions)</li>
+<li><a href="http://java.sun.com/j2ee/download.html">J2EE Platform
+ Specification</a> (in particular, see Chapter 5 on <em>Naming</em>)</li>
+</ul>
+
+</section>
+
+
+<section name="Configuring JNDI Resources">
+
+<p>Each available JNDI Resource is configured based on inclusion of the
+following elements in the <code><strong><Context></strong></code> or
+<code><strong><DefaultContext></strong></code> elements:</p>
+
+<ul>
+<li><a href="config/context.html#Environment Entries"><Environment></a> -
+ Configure names and values for scalar environment entries that will be
+ exposed to the web application through the JNDI
+ <code>InitialContext</code> (equivalent to the inclusion of an
+ <code><env-entry></code> element in the web application
+ deployment descriptor).</li>
+<li><a href="config/context.html#Resource Definitions"><Resource></a> -
+ Configure the name and data type of a resource made available to the
+ application (equivalent to the inclusion of a
+ <code><resource-ref></code> element in the web application
+ deployment descriptor).</li>
+<li><a href="config/context.html#Resource Links"><ResourceLink></a> -
+ Add a link to a resource defined in the global JNDI context. Use resource
+ links to give a web application access to a resource defined in
+ the<a href="config/globalresources.html"><GlobalNamingResources></a>
+ child element of the <a href="config/server.html"><Server></a>
+ element.</li>
+<li><a href="config/context.html#Transaction"><Transaction></a> -
+ Add a resource factory for instantiating the UserTransaction object
+ instance that is available at <code>java:comp/UserTransaction</code>.</li>
+
+</ul>
+
+<p>Any number of these elements may be nested inside a
+<a href="config/context.html"><Context></a> element (to be associated
+only with that particular web application).</p>
+
+<p>In addition, the names and values of all <code><env-entry></code>
+elements included in the web application deployment descriptor
+(<code>/WEB-INF/web.xml</code>) are configured into the initial context as
+well, overriding corresponding values from <code>conf/server.xml</code>
+<strong>only</strong> if allowed by the corresponding
+<code><Environment></code> element (by setting the
+<code>override</code> attribute to "true").</p>
+
+<p>Global resources can be defined in the server-wide JNDI context, by adding
+the resource elements described above to the
+<a href="config/globalresources.html"><GlobalNamingResources></a>
+child element of the <a href="config/server.html"><Server></a>
+element and using a
+<a href="config/context.html#Resource Links"><ResourceLink></a> to
+include it in the per-web-application context.</p>
+
+</section>
+
+
+<section name="Tomcat Standard Resource Factories">
+
+ <p>Tomcat 5 includes a series of standard resource factories that can
+ provide services to your web applications, but give you configuration
+ flexibility (in <code>$CATALINA_HOME/conf/server.xml</code>) without
+ modifying the web application or the deployment descriptor. Each
+ subsection below details the configuration and usage of the standard
+ resource factories.</p>
+
+ <p>See <a href="#Adding Custom Resource Factories">Adding Custom
+ Resource Factories</a> for information about how to create, install,
+ configure, and use your own custom resource factory classes with
+ Tomcat 5.</p>
+
+ <p><em>NOTE</em> - Of the standard resource factories, only the
+ "JDBC Data Source" and "User Transaction" factories are mandated to
+ be available on other platforms, and then they are required only if
+ the platform implements the Java2 Enterprise Edition (J2EE) specs.
+ All other standard resource factories, plus custom resource factories
+ that you write yourself, are specific to Tomcat and cannot be assumed
+ to be available on other containers.</p>
+
+ <subsection name="Generic JavaBean Resources">
+
+ <h3>0. Introduction</h3>
+
+ <p>This resource factory can be used to create objects of <em>any</em>
+ Java class that conforms to standard JavaBeans naming conventions (i.e.
+ it has a zero-arguments constructor, and has property setters that
+ conform to the setFoo() naming pattern. The resource factory will
+ create a new instance of the appropriate bean class every time a
+ <code>lookup()</code> for this entry is made.</p>
+
+ <p>The steps required to use this facility are described below.</p>
+
+ <h3>1. Create Your JavaBean Class</h3>
+
+ <p>Create the JavaBean class which will be instantiated each time
+ that the resource factory is looked up. For this example, assume
+ you create a class <code>com.mycompany.MyBean</code>, which looks
+ like this:</p>
+
+<source>
+package com.mycompany;
+
+public class MyBean {
+
+ private String foo = "Default Foo";
+
+ public String getFoo() {
+ return (this.foo);
+ }
+
+ public void setFoo(String foo) {
+ this.foo = foo;
+ }
+
+ private int bar = 0;
+
+ public int getBar() {
+ return (this.bar);
+ }
+
+ public void setBar(int bar) {
+ this.bar = bar;
+ }
+
+
+}
+</source>
+
+ <h3>2. Declare Your Resource Requirements</h3>
+
+ <p>Next, modify your web application deployment descriptor
+ (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
+ you will request new instances of this bean. The simplest approach is
+ to use a <code><resource-env-ref></code> element, like this:</p>
+
+<source>
+<resource-env-ref>
+ <description>
+ Object factory for MyBean instances.
+ </description>
+ <resource-env-ref-name>
+ bean/MyBeanFactory
+ </resource-env-ref-name>
+ <resource-env-ref-type>
+ com.mycompany.MyBean
+ </resource-env-ref-type>
+</resource-env-ref>
+</source>
+
+ <p><strong>WARNING</strong> - Be sure you respect the element ordering
+ that is required by the DTD for web application deployment descriptors!
+ See the
+ <a href="http://java.sun.com/products/servlet/download.html">Servlet
+ Specification</a> for details.</p>
+
+ <h3>3. Code Your Application's Use Of This Resource</h3>
+
+ <p>A typical use of this resource environment reference might look
+ like this:</p>
+
+<source>
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
+
+writer.println("foo = " + bean.getFoo() + ", bar = " +
+ bean.getBar());
+</source>
+
+ <h3>4. Configure Tomcat's Resource Factory</h3>
+
+ <p>To configure Tomcat's resource factory, add an elements like this to the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
+ <code>Context</code> element for this web application.</p>
+<source>
+<Context ...>
+ ...
+ <Resource name="bean/MyBeanFactory" auth="Container"
+ type="com.mycompany.MyBean"
+ factory="org.apache.naming.factory.BeanFactory"
+ bar="23"/>
+ ...
+</Context>
+</source>
+
+ <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
+ must match the value specified in the web application deployment
+ descriptor. We are also initializing the value of the <code>bar</code>
+ property, which will cause <code>setBar(23)</code> to be called before
+ the new bean is returned. Because we are not initializing the
+ <code>foo</code> property (although we could have), the bean will
+ contain whatever default value is set up by its constructor.</p>
+
+ </subsection>
+
+
+ <subsection name="JavaMail Sessions">
+
+ <h3>0. Introduction</h3>
+
+ <p>In many web applications, sending electronic mail messages is a
+ required part of the system's functionality. The
+ <a href="http://java.sun.com/products/javamail">Java Mail</a> API
+ makes this process relatively straightforward, but requires many
+ configuration details that the client application must be aware of
+ (including the name of the SMTP host to be used for message sending).</p>
+
+ <p>Tomcat 5 includes a standard resource factory that will create
+ <code>javax.mail.Session</code> session instances for you, already
+ connected to the SMTP server that is configured in <code>server.xml</code>.
+ In this way, the application is totally insulated from changes in the
+ email server configuration environment - it simply asks for, and receives,
+ a preconfigured session whenever needed.</p>
+
+ <p>The steps required for this are outlined below.</p>
+
+ <h3>1. Declare Your Resource Requirements</h3>
+
+ <p>The first thing you should do is modify the web application deployment
+ descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
+ which you will look up preconfigured sessions. By convention, all such
+ names should resolve to the <code>mail</code> subcontext (relative to the
+ standard <code>java:comp/env</code> naming context that is the root of
+ all provided resource factories. A typical <code>web.xml</code> entry
+ might look like this:</p>
+<source>
+<resource-ref>
+ <description>
+ Resource reference to a factory for javax.mail.Session
+ instances that may be used for sending electronic mail
+ messages, preconfigured to connect to the appropriate
+ SMTP server.
+ </description>
+ <res-ref-name>
+ mail/Session
+ </res-ref-name>
+ <res-type>
+ javax.mail.Session
+ </res-type>
+ <res-auth>
+ Container
+ </res-auth>
+</resource-ref>
+</source>
+
+ <p><strong>WARNING</strong> - Be sure you respect the element ordering
+ that is required by the DTD for web application deployment descriptors!
+ See the
+ <a href="http://java.sun.com/products/servlet/download.html">Servlet
+ Specification</a> for details.</p>
+
+ <h3>2. Code Your Application's Use Of This Resource</h3>
+
+ <p>A typical use of this resource reference might look like this:</p>
+<source>
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+Session session = (Session) envCtx.lookup("mail/Session");
+
+Message message = new MimeMessage(session);
+message.setFrom(new InternetAddress(request.getParameter("from"));
+InternetAddress to[] = new InternetAddress[1];
+to[0] = new InternetAddress(request.getParameter("to"));
+message.setRecipients(Message.RecipientType.TO, to);
+message.setSubject(request.getParameter("subject"));
+message.setContent(request.getParameter("content"), "text/plain");
+Transport.send(message);
+</source>
+
+ <p>Note that the application uses the same resource reference name
+ that was declared in the web application deployment descriptor. This
+ is matched up against the resource factory that is configured in
+ <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
+
+ <h3>3. Configure Tomcat's Resource Factory</h3>
+
+ <p>To configure Tomcat's resource factory, add an elements like this to the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
+ <code>Context</code> element for this web application.</p>
+<source>
+<Context ...>
+ ...
+ <Resource name="mail/Session" auth="Container"
+ type="javax.mail.Session"
+ mail.smtp.host="localhost"/>
+ ...
+</Context>
+</source>
+
+ <p>Note that the resource name (here, <code>mail/Session</code>) must
+ match the value specified in the web application deployment descriptor.
+ Customize the value of the <code>mail.smtp.host</code> parameter to
+ point at the server that provides SMTP service for your network.</p>
+
+ <h3>4. Install the JavaMail libraries</h3>
+
+ <p><a href="http://java.sun.com/products/javamail/downloads/index.html" target="_blank">
+ Download the JavaMail API</a>. The JavaMail API requires the Java Activation
+ Framework (JAF) API as well. The Java Activation Framework can be downloaded
+ from <a href="http://java.sun.com/products/javabeans/glasgow/jaf.html">Sun's site</a>.
+ </p>
+
+ <p>This download includes 2 vital libraries for the configuration;
+ activation.jar and mail.jar. Unpackage both distributions and place
+ them into $CATALINA_HOME/common/lib so that they are available to
+ Tomcat during the initialization of the mail Session Resource.
+ <strong>Note:</strong> placing these jars in both common/lib and a
+ web application's lib folder will cause an error, so ensure you have
+ them in the $CATALINA_HOME/common/lib location only.
+ </p>
+
+ <h3>Example Application</h3>
+
+ <p>The <code>/examples</code> application included with Tomcat contains
+ an example of utilizing this resource factory. It is accessed via the
+ "JSP Examples" link. The source code for the servlet that actually
+ sends the mail message is in
+ <code>/WEB-INF/classes/SendMailServlet.java</code>.</p>
+
+ <p><strong>WARNING</strong> - The default configuration assumes that
+ there is an SMTP server listing on port 25 on <code>localhost</code>.
+ If this is not the case, edit the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, and modify the
+ parameter value for the <code>mail.smtp.host</code> parameter to be
+ the host name of an SMTP server on your network.</p>
+
+ </subsection>
+
+ <subsection name="JDBC Data Sources">
+
+ <h3>0. Introduction</h3>
+
+ <p>Many web applications need to access a database via a JDBC driver,
+ to support the functionality required by that application. The J2EE
+ Platform Specification requires J2EE Application Servers to make
+ available a <em>DataSource</em> implementation (that is, a connection
+ pool for JDBC connections) for this purpose. Tomcat 5 offers exactly
+ the same support, so that database-based applications you develop on
+ Tomcat using this service will run unchanged on any J2EE server.</p>
+
+ <p>For information about JDBC, you should consult the following:</p>
+ <ul>
+ <li><a href="http://java.sun.com/products/jdbc/">http://java.sun.com/products/jdbc/</a> -
+ Home page for information about Java Database Connectivity.</li>
+ <li><a href="http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html">http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html</a> -
+ The JDBC 2.1 API Specification.</li>
+ <li><a href="http://java.sun.com/products/jdbc/jdbc20.stdext.pdf">http://java.sun.com/products/jdbc/jdbc20.stdext.pdf</a> -
+ The JDBC 2.0 Standard Extension API (including the
+ <code>javax.sql.DataSource</code> API). This package is now known
+ as the "JDBC Optional Package".</li>
+ <li><a href="http://java.sun.com/j2ee/download.html">http://java.sun.com/j2ee/download.html</a> -
+ The J2EE Platform Specification (covers the JDBC facilities that
+ all J2EE platforms must provide to applications).</li>
+ </ul>
+
+ <p><strong>NOTE</strong> - The default data source support in Tomcat
+ is based on the <strong>DBCP</strong> connection pool from the
+ <a href="http://jakarta.apache.org/commons">Jakarta Commons</a>
+ subproject. However, it is possible to use any other connection pool
+ that implements <code>javax.sql.DataSource</code>, by writing your
+ own custom resource factory, as described
+ <a href="#Adding Custom Resource Factories">below</a>.</p>
+
+ <h3>1. Install Your JDBC Driver</h3>
+
+ <p>Use of the <em>JDBC Data Sources</em> JNDI Resource Factory requires
+ that you make an appropriate JDBC driver available to both Tomcat internal
+ classes and to your web application. This is most easily accomplished by
+ installing the driver's JAR file(s) into the
+ <code>$CATALINA_HOME/common/lib</code> directory, which makes the driver
+ available both to the resource factory and to your application.</p>
+
+ <h3>2. Declare Your Resource Requirements</h3>
+
+ <p>Next, modify the web application deployment descriptor
+ (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
+ which you will look up preconfigured data source. By convention, all such
+ names should resolve to the <code>jdbc</code> subcontext (relative to the
+ standard <code>java:comp/env</code> naming context that is the root of
+ all provided resource factories. A typical <code>web.xml</code> entry
+ might look like this:</p>
+<source>
+<resource-ref>
+ <description>
+ Resource reference to a factory for java.sql.Connection
+ instances that may be used for talking to a particular
+ database that is configured in the server.xml file.
+ </description>
+ <res-ref-name>
+ jdbc/EmployeeDB
+ </res-ref-name>
+ <res-type>
+ javax.sql.DataSource
+ </res-type>
+ <res-auth>
+ Container
+ </res-auth>
+</resource-ref>
+</source>
+
+ <p><strong>WARNING</strong> - Be sure you respect the element ordering
+ that is required by the DTD for web application deployment descriptors!
+ See the
+ <a href="http://java.sun.com/products/servlet/download.html">Servlet
+ Specification</a> for details.</p>
+
+ <h3>3. Code Your Application's Use Of This Resource</h3>
+
+ <p>A typical use of this resource reference might look like this:</p>
+<source>
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+DataSource ds = (DataSource)
+ envCtx.lookup("jdbc/EmployeeDB");
+
+Connection conn = ds.getConnection();
+... use this connection to access the database ...
+conn.close();
+</source>
+
+ <p>Note that the application uses the same resource reference name
+ that was declared in the web application deployment descriptor. This
+ is matched up against the resource factory that is configured in
+ <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
+
+ <h3>4. Configure Tomcat's Resource Factory</h3>
+
+ <p>To configure Tomcat's resource factory, add an element like this to the
+ <code>/META-INF/context.xml</code> file in the web application.</p>
+<source>
+<Context ...>
+ ...
+ <Resource name="jdbc/EmployeeDB" auth="Container"
+ type="javax.sql.DataSource" username="dbusername" password="dbpassword"
+ driverClassName="org.hsql.jdbcDriver" url="jdbc:HypersonicSQL:database"
+ maxActive="8" maxIdle="4"/>
+ ...
+</Context>
+</source>
+
+ <p>Note that the resource name (here, <code>jdbc/EmployeeDB</code>) must
+ match the value specified in the web application deployment descriptor.</p>
+
+ <p>This example assumes that you are using the HypersonicSQL database
+ JDBC driver. Customize the <code>driverClassName</code> and
+ <code>driverName</code> parameters to match your actual database's
+ JDBC driver and connection URL.</p>
+
+ <p>The configuration properties for Tomcat's standard data source
+ resource factory
+ (<code>org.apache.tomcat.dbcp.dbcp.BasicDataSourceFactory</code>) are
+ as follows:</p>
+ <ul>
+ <li><strong>driverClassName</strong> - Fully qualified Java class name
+ of the JDBC driver to be used.</li>
+ <li><strong>maxActive</strong> - The maximum number of active instances
+ that can be allocated from this pool at the same time.</li>
+ <li><strong>maxIdle</strong> - The maximum number of connections that
+ can sit idle in this pool at the same time.</li>
+ <li><strong>maxWait</strong> - The maximum number of milliseconds that the
+ pool will wait (when there are no available connections) for a
+ connection to be returned before throwing an exception.</li>
+ <li><strong>password</strong> - Database password to be passed to our
+ JDBC driver.</li>
+ <li><strong>url</strong> - Connection URL to be passed to our JDBC driver.
+ (For backwards compatibility, the property <code>driverName</code>
+ is also recognized.)</li>
+ <li><strong>user</strong> - Database username to be passed to our
+ JDBC driver.</li>
+ <li><strong>validationQuery</strong> - SQL query that can be used by the
+ pool to validate connections before they are returned to the
+ application. If specified, this query MUST be an SQL SELECT
+ statement that returns at least one row.</li>
+ </ul>
+ <p>For more details, please refer to the commons-dbcp documentation.</p>
+
+ </subsection>
+
+</section>
+
+
+<section name="Adding Custom Resource Factories">
+
+ <p>If none of the standard resource factories meet your needs, you can
+ write your own factory and integrate it into Tomcat 5, and then configure
+ the use of this factory in the <code>conf/server.xml</code> configuration
+ file. In the example below, we will create a factory that only knows how
+ to create <code>com.mycompany.MyBean</code> beans, from the
+ <a href="#Generic JavaBean Resources">Generic JavaBean Resources</a>
+ example, above.</p>
+
+ <h3>1. Write A Resource Factory Class</h3>
+
+ <p>You must write a class that implements the JNDI service provider
+ <code>javax.naming.spi.ObjectFactory</code> inteface. Every time your
+ web application calls <code>lookup()</code> on a context entry that is
+ bound to this factory, the <code>getObjectInstance()</code> method is
+ called, with the following arguments:</p>
+ <ul>
+ <li><strong>Object obj</strong> - The (possibly null) object containing
+ location or reference information that can be used in creating an
+ object. For Tomcat, this will always be an object of type
+ <code>javax.naming.Reference</code>, which contains the class name
+ of this factory class, as well as the configuration properties
+ (from <code>conf/server.xml</code>) to use in creating objects
+ to be returned.</li>
+ <li><strong>Name name</strong> - The name to which this factory is bound
+ relative to <code>nameCtx</code>, or <code>null</code> if no name
+ is specified.</li>
+ <li><strong>Context nameCtx</strong> - The context relative to which the
+ <code>name</code> parameter is specified, or <code>null</code> if
+ <code>name</code> is relative to the default initial context.</li>
+ <li><strong>Hashtable environment</strong> - The (possibly null)
+ environment that is used in creating this object. This is generally
+ ignored in Tomcat object factories.</li>
+ </ul>
+
+ <p>To create a resource factory that knows how to produce <code>MyBean</code>
+ instances, you might create a class like this:</p>
+
+<source>
+package com.mycompany;
+
+import java.util.Enumeration;
+import java.util.Hashtable;
+import javax.naming.Context;
+import javax.naming.Name;
+import javax.naming.NamingException;
+import javax.naming.RefAddr;
+import javax.naming.Reference;
+import javax.naming.spi.ObjectFactory;
+
+public class MyBeanFactory implements ObjectFactory {
+
+ public Object getObjectInstance(Object obj,
+ Name name, Context nameCtx, Hashtable environment)
+ throws NamingException {
+
+ // Acquire an instance of our specified bean class
+ MyBean bean = new MyBean();
+
+ // Customize the bean properties from our attributes
+ Reference ref = (Reference) obj;
+ Enumeration addrs = ref.getAll();
+ while (addrs.hasMoreElements()) {
+ RefAddr addr = (RefAddr) addrs.nextElement();
+ String name = addr.getType();
+ String value = (String) addr.getContent();
+ if (name.equals("foo")) {
+ bean.setFoo(value);
+ } else if (name.equals("bar")) {
+ try {
+ bean.setBar(Integer.parseInt(value));
+ } catch (NumberFormatException e) {
+ throw new NamingException("Invalid 'bar' value " + value);
+ }
+ }
+ }
+
+ // Return the customized instance
+ return (bean);
+
+ }
+
+}
+</source>
+
+ <p>In this example, we are unconditionally creating a new instance of
+ the <code>com.mycompany.MyBean</code> class, and populating its properties
+ based on the parameters included in the <code><ResourceParams></code>
+ element that configures this factory (see below). You should note that any
+ parameter named <code>factory</code> should be skipped - that parameter is
+ used to specify the name of the factory class itself (in this case,
+ <code>com.mycompany.MyBeanFactory</code>) rather than a property of the
+ bean being configured.</p>
+
+ <p>For more information about <code>ObjectFactory</code>, see the
+ <a href="http://java.sun.com/products/jndi/docs.html">JNDI 1.2 Service
+ Provider Interface (SPI) Specification</a>.</p>
+
+ <p>You will need to compile this class against a class path that includes
+ all of the JAR files in the <code>$CATALINA_HOME/common/lib</code> and
+ <code>$CATALINA_HOME/server/lib</code> directories. When you are through,
+ place the factory class (and the corresponding bean class) unpacked under
+ <code>$CATALINA_HOME/common/classes</code>, or in a JAR file inside
+ <code>$CATALINA_HOME/common/lib</code>. In this way, the required class
+ files are visible to both Catalina internal resources and your web
+ application.</p>
+
+ <h3>2. Declare Your Resource Requirements</h3>
+
+ <p>Next, modify your web application deployment descriptor
+ (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
+ you will request new instances of this bean. The simplest approach is
+ to use a <code><resource-env-ref></code> element, like this:</p>
+
+<source>
+<resource-env-ref>
+ <description>
+ Object factory for MyBean instances.
+ </description>
+ <resource-env-ref-name>
+ bean/MyBeanFactory
+ </resource-env-ref-name>
+ <resource-env-ref-type>
+ com.mycompany.MyBean
+ </resource-env-ref-type>
+<resource-env-ref>
+</source>
+
+ <p><strong>WARNING</strong> - Be sure you respect the element ordering
+ that is required by the DTD for web application deployment descriptors!
+ See the
+ <a href="http://java.sun.com/products/servlet/download.html">Servlet
+ Specification</a> for details.</p>
+
+ <h3>3. Code Your Application's Use Of This Resource</h3>
+
+ <p>A typical use of this resource environment reference might look
+ like this:</p>
+
+<source>
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
+
+writer.println("foo = " + bean.getFoo() + ", bar = " +
+ bean.getBar());
+</source>
+
+ <h3>4. Configure Tomcat's Resource Factory</h3>
+
+ <p>To configure Tomcat's resource factory, add an elements like this to the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
+ <code>Context</code> element for this web application.</p>
+<source>
+<Context ...>
+ ...
+ <Resource name="bean/MyBeanFactory" auth="Container"
+ type="com.mycompany.MyBean"
+ factory="com.mycompany.MyBeanFactory"
+ bar="23"/>
+ ...
+</Context>
+</source>
+
+ <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
+ must match the value specified in the web application deployment
+ descriptor. We are also initializing the value of the <code>bar</code>
+ property, which will cause <code>setBar(23)</code> to be called before
+ the new bean is returned. Because we are not initializing the
+ <code>foo</code> property (although we could have), the bean will
+ contain whatever default value is set up by its constructor.</p>
+
+ <p>You will also note that, from the application developer's perspective,
+ the declaration of the resource environment reference, and the programming
+ used to request new instances, is identical to the approach used for the
+ <em>Generic JavaBean Resources</em> example. This illustrates one of the
+ advantages of using JNDI resources to encapsulate functionality - you can
+ change the underlying implementation without necessarily having to
+ modify applications using the resources, as long as you maintain
+ compatible APIs.</p>
+
+</section>
+
+
+
+</body>
+
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/tc6.0.x/trunk/webapps/docs/logging.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/logging.xml?rev=420006&view=auto
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/logging.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/logging.xml Fri Jul 7 15:40:04 2006
@@ -0,0 +1,272 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="logging.html">
+
+ &project;
+
+ <properties>
+ <title>Logging in Tomcat</title>
+ <author>Allistair Crossley</author>
+ <author email="yoavs@apache.org">Yoav Shapira</author>
+ </properties>
+
+<body>
+
+ <section name="Introduction">
+ <p>
+ Tomcat 5.5 uses
+ <a href="http://jakarta.apache.org/commons/logging">Commons Logging</a>
+ throughout its internal code allowing the
+ developer to choose a logging configuration that suits their needs, e.g
+ java.util.logging or
+ <a href="http://logging.apache.org/log4j">Log4J</a>.
+ Commons Logging provides Tomcat the ability to log
+ hierarchially across various log levels without needing to rely on a particular
+ logging implementation.
+ </p>
+ <p>
+ An important consequence for Tomcat 5.5 is that the <Logger> element found in
+ previous versions to create a <code>localhost_log</code> is no longer a valid nested element
+ of <Context>. Instead, the default Tomcat configuration will use java.util.logging.
+ If the developer wishes to collect detailed internal Tomcat logging (i.e what is happening
+ within the Tomcat engine), then they should configure a logging system such as java.util.logging
+ or log4j as detailed next.
+ </p>
+
+ </section>
+
+ <section name="log4j">
+ <p>
+ Tomcat 5.5 has done away with <code>localhost_log</code> which you may be familiar with
+ as the runtime exception/stack trace log. These types of error are usually thrown
+ by uncaught exceptions, but are still valuable to the developer. They can now be
+ found in the <code>stdout</code> log.
+ </p>
+
+ <p>
+ If you need to setup cross-context detailed logging from within Tomcat's code,
+ then you can use a simple log4j configuration. Note that this logging van be very
+ verbose depending on the log level you chose to use. Note also that a log4j logging
+ configuration is not going to produce stack trace type logging: those stack traces
+ are output to <code>stdout</code> as discussed above.
+ </p>
+
+ <p>
+ Follow the following steps to setup a file named tomcat.log that has internal
+ Tomcat logging output to it:
+ </p>
+
+ <p>
+ <ol>
+ <li>Create a file called log4j.properties with the following content
+ and save it into common/classes.
+ <source>
+ log4j.rootLogger=debug, R <br />
+ log4j.appender.R=org.apache.log4j.RollingFileAppender <br />
+ log4j.appender.R.File=${catalina.home}/logs/tomcat.log <br />
+ log4j.appender.R.MaxFileSize=10MB <br />
+ log4j.appender.R.MaxBackupIndex=10 <br />
+ log4j.appender.R.layout=org.apache.log4j.PatternLayout <br />
+ log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n <br />
+ log4j.logger.org.apache.catalina=DEBUG, R
+ </source>
+ </li>
+
+ <li><a href="http://logging.apache.org/log4j">Download Log4J</a>
+ (v1.2 or later) and place the log4j jar in $CATALINA_HOME/common/lib.</li>
+
+ <li><a href="http://jakarta.apache.org/site/downloads/downloads_commons-logging.cgi">
+ Download Commons Logging</a> and place the commons-logging.jar
+ (not commons-logging-api.jar) in $CATALINA_HOME/common/lib with
+ the log4j jar.</li>
+
+ <li>Start Tomcat</li>
+ </ol>
+ </p>
+
+ <p>
+ This log4j configuration sets up a file called tomcat.log in your
+ Tomcat logs folder with a maximum file size of 10MB and
+ up to 10 backups. DEBUG level is specified which will result in the
+ most verbose output from Tomcat.
+ </p>
+
+ <p>
+ You can (and should) be more picky about which packages to include
+ in the logging. Tomcat 5.5 uses defines loggers by Engine and Host names.
+ For example, for a default Catalina localhost log, add this to the
+ end of the log4j.properties above. Note that there are known issues with
+ using this naming convention (with square brackets) in log4j XML based
+ configuration files, so we recommend you use a properties file as described
+ until a future version of log4j allows this convention.
+
+ <ul>
+ <li>log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG, R</li>
+ <li>log4j.logger.org.apache.catalina.core=DEBUG, R</li>
+ <li>log4j.logger.org.apache.catalina.session=DEBUG, R</li>
+ </ul>
+
+ Be warned a level of DEBUG will produce megabytes of logging and slow startup
+ of Tomcat. This level should be used sparingly when debugging of internal Tomcat
+ operations is required.
+ </p>
+
+ <p>
+ Your web applications should certainly use their own log4j configuration.
+ This is valid <i>with</i> the above configuration. You would place a similar log4j.properties
+ file in your web application's WEB-INF/classes folder, and log4j1.2.8.jar into
+ WEB-INF/lib. Then specify your package level logging. This is a basic setup of log4j
+ which does *not* require Commons-Logging,
+ and you should consult the
+ <a href="http://logging.apache.org/log4j/docs/documentation.html">log4j documentation</a>
+ for more options. This page is intended only as a bootstrapping guide.
+ </p>
+
+ </section>
+
+ <section name="java.util.logging">
+
+ <p>
+ In order to configure JDK logging you should have JDK 1.4+. Tomcat 5.5 is intended for
+ JDK 5.0, but can be run on JDK 1.4 using a compatibility package.
+ </p>
+ <p>
+ The default implemenatation of java.util.logging provided in the JDK is too limited to be
+ useful. A limitation of JDK Logging appears to be the inability to have per-web application logging,
+ as the configuration is per-VM. As a result, Tomcat will, in the default configuration,
+ replace the default LogManager implementation with a container friendly implementation
+ called JULI, which addresses these shortcomings. It supports the same configuration mechanisms
+ as the standard JDK java.util.logging, using either a programmatic approach, or properties
+ files. The main difference is that per-classloader properties files can be set (which enables easy
+ redeployment friendly webapp configuration), and the properties files support slightly extended
+ constructs which allows more freedom for defining handlers and assigning them to loggers.
+ </p>
+ <p>
+ JULI is enabled by default in Tomcat 5.5, and supports per classloader configuration, in addition to
+ the regular global java.util.logging configuration. This means that logging can be configured at
+ the following layers:
+ <ul>
+ <li>In the JDK's logging.properties file. Check
+ your JAVA_HOME environment setting to see which JDK Tomcat is using (or maybe JRE 5.0 as Tomcat
+ can now run on a JRE from version 5.5). The file will be in <code>$JAVA_HOME/jre/lib</code>.
+ Alternately, it can also use a global configuration file located elsewhere by using the
+ system property <code>java.util.logging.config.file</code>, or programmatic configuration using
+ <code>java.util.logging.config.class</code>.</li>
+ <li>In each classloader using a logging.properties file. This means that it is possible to have a
+ configuration for the Tomcat core, as well as separate configurations for each webapps which will
+ have the same lifecycle as the webapps.</li>
+ </ul>
+ </p>
+ <p>
+ The default logging.properties specifies a ConsoleHandler for routing logging to stdout and
+ also a FileHandler. A handler's log level threshold can be set using SEVERE, CONFIG, INFO,
+ WARN, FINE, FINEST or ALL. The logging.properties shipped with JDK is set to INFO. You
+ can also target specific packages to collect logging from and specify a level. Here is how
+ you would set debugging from Tomcat. You would need to ensure the ConsoleHandler's level is also
+ set to collect this threshold, so FINEST or ALL should be set. Please refer to Sun's java.util.logging
+ documentation for the complete details.
+ </p>
+ <p>
+ <source>org.apache.catalina.level=FINEST</source>
+ </p>
+ <p>
+ The configuration used by JULI is extremely similar, but uses a few extensions to allow better
+ flexibility in assigning loggers. The main differences are:
+ <ul>
+ <li>A prefix may be added to handler names, so that multiple handlers of a single class may be
+ instantiated. A prefix is a String which starts with a digit, and ends with '.'. For example,
+ <code>22foobar.</code> is a valid prefix.</li>
+ <li>As in Java 5.0, loggers can define a list of handlers using the <code>loggerName.handlers</code>
+ property.</li>
+ <li>By default, loggers will not delegate to their parent if they have associated handlers. This
+ may be changed per logger using the <code>loggerName.useParentHandlers</code> property, which accepts
+ a boolean value.</li>
+ <li>The root logger can define its set of handlers using a <code>.handlers</code> property.</li>
+ <li>System property replacement for property values which start with ${sytstemPropertyName}.</li>
+ </ul>
+ </p>
+ <p>
+ Example logging.properties file to be placed in common/classes:
+ <source>
+handlers = 1catalina.org.apache.juli.FileHandler, 2localhost.org.apache.juli.FileHandler, \
+ 3manager.org.apache.juli.FileHandler, 4admin.org.apache.juli.FileHandler, \
+ java.util.logging.ConsoleHandler
+
+.handlers = 1catalina.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
+
+############################################################
+# Handler specific properties.
+# Describes specific configuration info for Handlers.
+############################################################
+
+1catalina.org.apache.juli.FileHandler.level = FINE
+1catalina.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
+1catalina.org.apache.juli.FileHandler.prefix = catalina.
+
+2localhost.org.apache.juli.FileHandler.level = FINE
+2localhost.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
+2localhost.org.apache.juli.FileHandler.prefix = localhost.
+
+3manager.org.apache.juli.FileHandler.level = FINE
+3manager.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
+3manager.org.apache.juli.FileHandler.prefix = manager.
+
+4admin.org.apache.juli.FileHandler.level = FINE
+4admin.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
+4admin.org.apache.juli.FileHandler.prefix = admin.
+
+java.util.logging.ConsoleHandler.level = FINE
+java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
+
+
+############################################################
+# Facility specific properties.
+# Provides extra control for each logger.
+############################################################
+
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = INFO
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].handlers = \
+ 2localhost.org.apache.juli.FileHandler
+
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].level = INFO
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].handlers = \
+ 3manager.org.apache.juli.FileHandler
+
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/admin].level = INFO
+org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/admin].handlers = \
+ 4admin.org.apache.juli.FileHandler
+
+# For example, set the com.xyz.foo logger to only log SEVERE
+# messages:
+#org.apache.catalina.startup.ContextConfig.level = FINE
+#org.apache.catalina.startup.HostConfig.level = FINE
+#org.apache.catalina.session.ManagerBase.level = FINE
+ </source>
+ </p>
+
+ <p>
+ Example logging.properties for the servlet-examples web application to be placed
+ in WEB-INF/classes inside the web application:
+ <source>
+handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
+
+############################################################
+# Handler specific properties.
+# Describes specific configuration info for Handlers.
+############################################################
+
+org.apache.juli.FileHandler.level = FINE
+org.apache.juli.FileHandler.directory = ${catalina.base}/logs
+org.apache.juli.FileHandler.prefix = servlet-examples.
+
+java.util.logging.ConsoleHandler.level = FINE
+java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
+ </source>
+ </p>
+
+ </section>
+
+</body>
+</document>
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/logging.xml
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org