http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/jndi-resources-howto.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/jndi-resources-howto.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/jndi-resources-howto.html new file mode 100644 index 0000000..2a60573 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/jndi-resources-howto.html @@ -0,0 +1,835 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - JNDI Resources HOW-TO</title><meta content="Craig R. McClanahan" name="author"><meta content="Yoav Shapira" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + The Apache Tomcat Servlet/JSP Container + " align="right" src="./images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="./images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ";>FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a hr ef="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-ho sting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/";>JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions";>Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Apache Tomcat 6.0</h1> <h2>JNDI Resources HOW-TO</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#web.xml_configuration">web.xml configuration</a></li><li><a href="#context.xml_configuration">context.xml configuration</a></li><li><a href="#Global_configuration">Global configuration</a></li><li><a href="#Using_resources">Using resources</a></li><li><a href="#Tomcat_Standard_Resource_Factories">Tomcat Standard Resource Factories</a><ol><li><a href="#Generic_JavaBean_Resources">Generic JavaBean Resources</a></li><li><a href="#UserDatabase_Resources">UserDatabase Resources</a></li><li><a href="#JavaMail_Sessions">JavaMail Sessions</a></li><li><a href="#JDBC_Data_Sources">JDBC Data Sources</a></li></ol></li><li><a href="#Adding_Custom_Resource_Factories">Adding Custom Resource Factories</a></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> + +<p>Tomcat 6 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/define resources.</p> + +<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";>Java Naming and Directory + Interface</a> (included in JDK 1.4 onwards)</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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="web.xml configuration"><!--()--></a><a name="web.xml_configuration"><strong>web.xml configuration</strong></a></font></td></tr><tr><td><blockquote> + +<p>The following elements may be used in the web application deployment +descriptor (<code>/WEB-INF/web.xml</code>) of your web application to define +resources:</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 6.</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>Providing that Tomcat is able to identify an appropriate resource factory to +use to create the resource and that no further configuration information is +required, Tomcat will use the information in <code>/WEB-INF/web.xml</code> to +create the resource.</p> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="context.xml configuration"><!--()--></a><a name="context.xml_configuration"><strong>context.xml configuration</strong></a></font></td></tr><tr><td><blockquote> + +<p>If Tomcat is unable to identify the appropriate resource factory and/or +additional configuration information is required, additional Tomcat specific +configuration must be specified before Tomcat can create the resource. +Tomcat specific resource configuration is entered in +the <a href="config/context.html"><code><Context></code></a> elements that +can be specified in either <code>$CATALINA_BASE/conf/server.xml</code> or, +preferably, the per-web-application context XML file +(<code>META-INF/context.xml</code>).</p> + +<p>Tomcat specific resource configuration is performed using the following +elements in the <a href="config/context.html"><code><Context></code></a> +element:</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"><code><Context></code></a> element and will +be associated only with that particular web application.</p> + +<p>If a resource has been defined in a +<a href="config/context.html"><code><Context></code></a> element it is not +necessary for that resource to be defined in <code>/WEB-INF/web.xml</code>. +However, it is recommended to keep the entry in <code>/WEB-INF/web.xml</code> +to document the resource requirements for the web application.</p> + +<p>Where the same resource name has been defined for a +<code><env-entry></code> element included in the web application +deployment descriptor (<code>/WEB-INF/web.xml</code>) and in an +<code><Environment></code> element as part of the +<a href="config/context.html"><code><Context></code></a> element for the +web application, the values in the deployment descriptor will take precedence +<strong>only</strong> if allowed by the corresponding +<code><Environment></code> element (by setting the <code>override</code> +attribute to "true").</p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Global configuration"><!--()--></a><a name="Global_configuration"><strong>Global configuration</strong></a></font></td></tr><tr><td><blockquote> + +<p>Tomcat 6 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_BASE/conf/server.xml</code>. You may expose these resources to +web applications by using a +<a href="config/context.html#Resource Links"><ResourceLink></a> to +include it in the per-web-application context.</p> + +<p>If a resource has been defined using a +<a href="config/context.html#Resource Links"><ResourceLink></a>, it is not +necessary for that resource to be defined in <code>/WEB-INF/web.xml</code>. +However, it is recommended to keep the entry in <code>/WEB-INF/web.xml</code> +to document the resource requirements for the web application.</p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Using resources"><!--()--></a><a name="Using_resources"><strong>Using resources</strong></a></font></td></tr><tr><td><blockquote> + +<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> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +// 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(); +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Tomcat Standard Resource Factories"><!--()--></a><a name="Tomcat_Standard_Resource_Factories"><strong>Tomcat Standard Resource Factories</strong></a></font></td></tr><tr><td><blockquote> + + <p>Tomcat 6 includes a series of standard resource factories that can + provide services to your web applications, but give you configuration + flexibility (via the + <a href="config/context.html"><code><Context></code></a> element) + 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 6.</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> + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Generic JavaBean Resources"><!--()--></a><a name="Generic_JavaBean_Resources"><strong>Generic JavaBean Resources</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +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; + } + + +} +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<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> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +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()); +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <h3>4. Configure Tomcat's Resource Factory</h3> + + <p>To configure Tomcat's resource factory, add an element like this to the + <a href="config/context.html"><code><Context></code></a> element for + this web application.</p> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<Context ...> + ... + <Resource name="bean/MyBeanFactory" auth="Container" + type="com.mycompany.MyBean" + factory="org.apache.naming.factory.BeanFactory" + bar="23"/> + ... +</Context> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="UserDatabase Resources"><!--()--></a><a name="UserDatabase_Resources"><strong>UserDatabase Resources</strong></a></font></td></tr><tr><td><blockquote> + + <h3>0. Introduction</h3> + + <p>UserDatabase resources are typically configured as global resources for + use by a UserDatabase realm. Tomcat includes a UserDatabaseFactoory that + creates UserDatabase resources backed by an XML file - usually + <code>tomcat-users.xml</code></p> + + <p>The steps required to set up a global UserDatabase resource are described + below.</p> + + <h3>1. Create/edit the XML file</h3> + + <p>The XMl file is typically located at + <code>$CATALINA_BASE/conf/tomcat-users.xml</code> however, you are free to + locate the file anywhere on the file system. It is recommended that the XML + files are placed in <code>$CATALINA_BASE/conf</code>. A typical XML would + look like:</p> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<?xml version='1.0' encoding='utf-8'?> +<tomcat-users> + <role rolename="tomcat"/> + <role rolename="role1"/> + <user username="tomcat" password="tomcat" roles="tomcat"/> + <user username="both" password="tomcat" roles="tomcat,role1"/> + <user username="role1" password="tomcat" roles="role1"/> +</tomcat-users> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <h3>2. Declare Your Resource</h3> + + <p>Next, modify <code>$CATALINA_BASE/conf/server.xml</code> to create the + UserDatabase resource based on your XMl file. It should look something like + this:</p> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<Resource name="UserDatabase" + auth="Container" + type="org.apache.catalina.UserDatabase" + description="User database that can be updated and saved" + factory="org.apache.catalina.users.MemoryUserDatabaseFactory" + pathname="conf/tomcat-users.xml" + readonly="false" /> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <p>The <code>pathname</code> attribute can be absolute or relative. If + relative, it is relative to <code>$CATALINA_BASE</code>.</p> + + <p>The <code>readonly</code> attribute is optional and defaults to + <code>true</code> if not supplied. If the XML is writeable then it will be + written to when Tomcat starts. <strong>WARNING:</strong> When the file is + written it will inherit the default file permissions for the user Tomcat + is running as. Ensure that these are appropriate to maintain the security + of your installation.</p> + + <h3>3. Configure the Realm</h3> + + <p>Configure a UserDatabase Realm to use this resource as described in the + <a href="config/realm.html">Realm configuration documentation</a>.</p> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="JavaMail Sessions"><!--()--></a><a name="JavaMail_Sessions"><strong>JavaMail Sessions</strong></a></font></td></tr><tr><td><blockquote> + + <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 6 includes a standard resource factory that will create + <code>javax.mail.Session</code> session instances for you, already + configured to connect to an SMTP server. + 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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<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> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +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); +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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 the + <a href="config/context.html"><code><Context></code></a> element + for the web application 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 + <a href="config/context.html"><code><Context></code></a> element for + this web application.</p> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<Context ...> + ... + <Resource name="mail/Session" auth="Container" + type="javax.mail.Session" + mail.smtp.host="localhost"/> + ... +</Context> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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";> + 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/lib so that they are available to + Tomcat during the initialization of the mail Session Resource. + <strong>Note:</strong> placing these jars in both $CATALINA_HOME/lib and a + web application's lib folder will cause an error, so ensure you have + them in the $CATALINA_HOME/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 + <a href="config/context.html"><code><Context></code></a> element for + this web application 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> + + </blockquote></td></tr></table> + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="JDBC Data Sources"><!--()--></a><a name="JDBC_Data_Sources"><strong>JDBC Data Sources</strong></a></font></td></tr><tr><td><blockquote> + + <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 6 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://commons.apache.org/";>Commons</a> + project. 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/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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<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 <Context> + configurartion for the web application. + </description> + <res-ref-name> + jdbc/EmployeeDB + </res-ref-name> + <res-type> + javax.sql.DataSource + </res-type> + <res-auth> + Container + </res-auth> +</resource-ref> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +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(); +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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 the + <a href="config/context.html"><code><Context></code></a> element for + the web application 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 + <a href="config/context.html"><code><Context></code></a> element for + the web application.</p> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<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> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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>username</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> + + </blockquote></td></tr></table> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Adding Custom Resource Factories"><!--()--></a><a name="Adding_Custom_Resource_Factories"><strong>Adding Custom Resource Factories</strong></a></font></td></tr><tr><td><blockquote> + + <p>If none of the standard resource factories meet your needs, you can write + your own factory and integrate it into Tomcat 6, and then configure the use + of this factory in the + <a href="config/context.html"><code><Context></code></a> element for + the web application. 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 the + <a href="config/context.html"><code><Context></code></a> for the + web application) 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> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +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); + + } + +} +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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/lib</code> directory. When you are through, + place the factory class (and the corresponding bean class) unpacked under + <code>$CATALINA_HOME/lib</code>, or in a JAR file inside + <code>$CATALINA_HOME/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> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<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> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +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()); +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <h3>4. Configure Tomcat's Resource Factory</h3> + + <p>To configure Tomcat's resource factory, add an elements like this to the + <a href="config/context.html"><code><Context></code></a> element for + this web application.</p> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<Context ...> + ... + <Resource name="bean/MyBeanFactory" auth="Container" + type="com.mycompany.MyBean" + factory="com.mycompany.MyBeanFactory" + bar="23"/> + ... +</Context> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + <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> + +</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/logging.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/logging.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/logging.html new file mode 100644 index 0000000..d9d863d --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/logging.html @@ -0,0 +1,289 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Logging in Tomcat</title><meta content="Allistair Crossley" name="author"><meta content="Yoav Shapira" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + The Apache Tomcat Servlet/JSP Container + " align="right" src="./images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="./images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ";>FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a hr ef="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-ho sting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/";>JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions";>Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Apache Tomcat 6.0</h1> <h2>Logging in Tomcat</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#java.util.logging">java.util.logging</a></li><li><a href="#log4j">log4j</a></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> + <p> + Tomcat uses + <a href="http://commons.apache.org/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 with the ability to log + hierarchically across various log levels without needing to rely on a + particular logging implementation. + </p> + + <p> + By default, only java.util.logging is available for the logs generated by + the Tomcat internal loggers, as Tomcat uses a package renamed commons + logging implementation which is hardcoded to use java.util.logging. Use of + alternative logging frameworks requires building or downloading the + <a href="extras.html">extras</a> components which include a full + commons-logging implementation. Instructions for configuring the extras + components to enable log4j to be used for Tomcat's internal logging may be + found below. + </p> + + <p> + Tomcat no longer uses <code>localhost_log</code> 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> + + </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="java.util.logging"><strong>java.util.logging</strong></a></font></td></tr><tr><td><blockquote> + + <p> + The default implementation 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, 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. 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, WARNING, INFO, CONFIG, FINE, FINER, 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> + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>org.apache.catalina.level=FINEST</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#0 23264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + </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 6.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>Logging is not buffered by default. To configure buffering, use the + <code>bufferSize</code> property of a handler. A value of <code>0</code> + uses system default buffering (typically an 8K buffer will be used). A + value of <code><0</code> forces a writer flush upon each log write. A + value <code>>0</code> uses a BufferedOutputStream with the defined + value but note that the system default buffering will also be + applied.</li> + <li>System property replacement is performed for property values which + contain ${systemPropertyName}.</li> + </ul> + </p> + <p> + Example logging.properties file to be placed in $CATALINA_BASE/conf: + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +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. +4admin.org.apache.juli.FileHandler.bufferSize = 16384 + +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 + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + </p> + + <p> + Example logging.properties for the servlet-examples web application to be + placed in WEB-INF/classes inside the web application: + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +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 + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + </p> + + </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="log4j"><strong>log4j</strong></a></font></td></tr><tr><td><blockquote> + <p> + This section explains how to configure Tomcat to use log4j rather than + java.util.logging for all Tomcat's internal logging. The following steps + describe configuring log4j to output Tomcat's internal logging to a file + named tomcat.log. + </p> + + <p> + <ol> + <li>Create a file called log4j.properties with the following content + and save it into $CATALINA_HOME/lib. + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +log4j.rootLogger=INFO, R +log4j.appender.R=org.apache.log4j.RollingFileAppender +log4j.appender.R.File=${catalina.base}/logs/tomcat.log +log4j.appender.R.MaxFileSize=10MB +log4j.appender.R.MaxBackupIndex=10 +log4j.appender.R.layout=org.apache.log4j.PatternLayout +log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + </li> + + <li><a href="http://logging.apache.org/log4j";>Download Log4J</a> + (v1.2 or later) and place the log4j jar in $CATALINA_HOME/lib.</li> + + <li>Build or download the additional logging components. See the + <a href="extras.html">extras components</a> documentation for + details.</li> + + <li>Replace <code>$CATALINA_HOME/bin/tomcat-juli.jar</code> with + <code>output/extras/tomcat-juli.jar</code>.</li> + + <li>Place <code>output/extras/tomcat-juli-adapters.jar</code> in + $CATALINA_HOME/lib.</li> + + <li>Delete <code>$CATALINA_BASE/conf/logging.properties</code> to + prevent java.util.logging generating zero length log files.</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. INFO level is specified which will result in a similar + level of detail to the standard java.util.logging confgiuration. Use DEBUG + level logging for the most verbose output from Tomcat. + </p> + + <p> + You can (and should) be more picky about which packages to include + in the logging. Tomcat defines loggers by Engine and Host names. + For example, for a more detailed 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. + + <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG +log4j.logger.org.apache.catalina.core=DEBUG +log4j.logger.org.apache.catalina.session=DEBUG + </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + 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 + directory, and log4jx.y.z.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> + + <p> + If you have multiple instances of Tomcat, each with a separate + <code>$CATALINA_HOME</code> but a shared <code>$CATALINA_BASE</code>, then + you can configure log4j on a per instance basis by replacing references to + <code>$CATALINA_HOME</code> in the above instructions with + <code>$CATALINA_BASE</code>. Note that you may need to create a + <code>$CATALINA_BASE/lib</code> directory. + </p> + </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file
