http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/introduction.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/introduction.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/introduction.html new file mode 100644 index 0000000..f8537c3 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/introduction.html @@ -0,0 +1,109 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Introduction</title><meta content="Robert Slifka" 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>Introduction</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="#Terminology">Terminology</a></li><li><a href="#Directories_and_Files">Directories and Files</a></li><li><a href="#Configuring_Tomcat">Configuring Tomcat</a></li><li><a href="#Where_to_Go_for_Help">Where to Go for Help</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>For administrators and web developers alike, there are some important bits +of information you should familiarize yourself with before starting out. This +document serves as a brief introduction to some of the concepts and +terminology behind the Tomcat container. As well, where to go when you need +help.</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="Terminology"><strong>Terminology</strong></a></font></td></tr><tr><td><blockquote> + +<p>In the course of reading these documents, you'll run across a number of +terms; some specific to Tomcat, and others defined by the +<a href="http://java.sun.com/products/servlet/";>Servlet</a> or +<a href="http://java.sun.com/products/jsp/";>JSP</a> specifications.</p> + +<ul> +<li><strong>Context</strong> - In a nutshell, a Context is a + web application.</li> +<li><strong>Term2</strong> - This is it.</li> +<li><strong>Term3</strong> - This is it!</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="Directories and Files"><!--()--></a><a name="Directories_and_Files"><strong>Directories and Files</strong></a></font></td></tr><tr><td><blockquote> + +<p>Throughout the docs, you'll notice there are numerous references to +<strong>$CATALINA_HOME</strong>. This represents the root of your Tomcat +installation. When we say, "This information can be found in your +$CATALINA_HOME/README.txt file" we mean to look at the README.txt file at the +root of your Tomcat install. Optionally, Tomcat may be configured for multiple +instances by defining <strong>$CATALINA_BASE</strong> for each instance. If +multiple instances are not configured, <strong>$CATALINA_BASE</strong> is the +same as <strong>$CATALINA_HOME</strong>.</p> + +<p>These are some of the key tomcat directories:</p> + +<ul> +<li><strong>/bin</strong> - Startup, shutdown, and other scripts. The + <code>*.sh</code> files (for Unix systems) are functional duplicates of + the <code>*.bat</code> files (for Windows systems). Since the Win32 + command-line lacks certain functionality, there are some additional + files in here.</li> +<li><strong>/conf</strong> - Configuration files and related DTDs. The most + important file in here is server.xml. It is the main configuration file + for the container.</li> +<li><strong>/logs</strong> - Log files are here by default.</li> +<li><strong>/webapps</strong> - This is where your webapps go.</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="Configuring Tomcat"><!--()--></a><a name="Configuring_Tomcat"><strong>Configuring Tomcat</strong></a></font></td></tr><tr><td><blockquote> + +<p>This section will acquaint you with the basic information used during +the configuration of the container.</p> + +<p>All of the information in the configuration files is read at startup, +meaning that any change to the files necessitates a restart of the container. +</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="Where to Go for Help"><!--()--></a><a name="Where_to_Go_for_Help"><strong>Where to Go for Help</strong></a></font></td></tr><tr><td><blockquote> + +<p>While we've done our best to ensure that these documents are clearly +written and easy to understand, we may have missed something. Provided +below are various web sites and mailing lists in case you get stuck.</p> + +<p>As Tomcat 6 is a new release of Tomcat, keep in mind that some of the +issues and solutions vary between the major versions of Tomcat (4.x versus +5). As you search around the web, there will be some documentation that +is not relevant to Tomcat 6, but 3.x, 4.x and 5.x. Doing 3.x or 4.x things to 6 +will probably not work in most cases as the server.xml files are very +different.</p> + +<ul> +<li>Current document - most documents will list potential hangups. Be sure + to fully read the relevant documentation as it will save you much time + and effort. There's nothing like scouring the web only to find out that + the answer was right in front of you all along!</li> +<li><a href="http://wiki.apache.org/tomcat/FAQ";>Tomcat FAQ</a> as maintained by the developers.</li> +<li><a href="http://wiki.apache.org/tomcat/";>Tomcat WIKI</a></li> +<li>Tomcat FAQ at <a href="http://www.jguru.com/faq/home.jsp?topic=Tomcat";>jGuru</a></li> +<li>Tomcat mailing list archives - numerous sites archive the Tomcat mailing + lists. Since the links change over time, clicking here will search + <a href="http://www.google.com/search?q=tomcat+mailing+list+archives";>Google</a>. + </li> +<li>The TOMCAT-USER mailing list, which you can subscribe to + <a href="http://tomcat.apache.org/lists.html";>here</a>. If you don't + get a reply, then there's a good chance that your question was probably + answered in the list archives or one of the FAQs. Although questions + about web application development in general are sometimes asked and + answered, please focus your questions on Tomcat-specific issues.</li> +<li>The TOMCAT-DEV mailing list, which you can subscribe to + <a href="http://tomcat.apache.org/lists.html";>here</a>. This list is + <strong>reserved</strong> for discussions about the development of Tomcat + itself. Questions about Tomcat configuration, and the problems you run + into while developing and running applications, will normally be more + appropriate on the TOMCAT-USER list instead.</li> +</ul> + +<p>And, if you think something should be in the docs, by all means let us know +on the TOMCAT-DEV list, or send one of the doc authors email.</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/jasper-howto.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/jasper-howto.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/jasper-howto.html new file mode 100644 index 0000000..8289ce1 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/jasper-howto.html @@ -0,0 +1,356 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Jasper 2 JSP Engine How To</title><meta content="Glenn L. Nielsen" name="author"><meta content="Peter Rossbach" 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>Jasper 2 JSP Engine 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="#Configuration">Configuration</a></li><li><a href="#Known_issues">Known issues</a></li><li><a href="#Production_Configuration">Production Configuration</a></li><li><a href="#Web_Application_Compilation">Web Application Compilation</a></li><li><a href="#Using_Jikes">Using Jikes</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.0 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 original 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 availability +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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Configuration"><strong>Configuration</strong></a></font></td></tr><tr><td><blockquote> + +<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 checkInterval +is greater than zero, background compiles are enabled. checkInterval is the time +in seconds between checks to see if a JSP page (and its dependent files) needs +to be recompiled. Default <code>0</code> seconds.</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> - Defines the class path to be used to compile +the generated servlets. This parameter only has an effect if the ServletContext +attribute org.apache.jasper.Constants.SERVLET_CLASSPATH is not set. This +attribute is always set when Jasper is used within Tomcat. By default the +classpath is created dynamically based on the current web application.</li> + +<li><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>compilerSourceVM</strong> - What JDK version are the source files +compatible with? (Default value: <code>1.5</code>)</li> + +<li><strong>compilerTargetVM</strong> - What JDK version are the generated files +compatible with? (Default value: <code>1.5</code>)</li> + +<li><strong>development</strong> - Is Jasper used in development mode? If true, +the frequency at which JSPs are checked for modification may be specified via +the modificationTestInterval parameter.<code>true</code> or <code>false</code>, +default <code>true</code>.</li> + +<li><strong>displaySourceFragment</strong> - Should a source fragment be +included in exception messages? <code>true</code> or <code>false</code>, +default <code>true</code>.</li> + +<li><strong>dumpSmap</strong> - Should the SMAP info for JSR45 debugging be +dumped to a file? <code>true</code> or <code>false</code>, default +<code>false</code>. <code>false</code> if suppressSmap is true.</li> + +<li><strong>enablePooling</strong> - Determines whether tag handler pooling is +enabled. This is a compilation option. It will not alter the behaviour of JSPs +that have already been compiled. <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>errorOnUseBeanInvalidClassAttribute</strong> - Should Jasper issue +an error when the value of the class attribute in an useBean action is not a +valid bean class? <code>true</code> or <code>false</code>, default +<code>true</code>.</li> + +<li><strong>fork</strong> - Have Ant fork JSP page compiles so they are +performed in a separate JVM from Tomcat? <code>true</code> or +<code>false</code>, default <code>true</code>.</li> + +<li><strong>genStrAsCharArray</strong> - Should text strings be generated as char +arrays, to improve performance in some cases? Default <code>false</code>.</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>javaEncoding</strong> - Java file encoding to use for generating +java source files. Default <code>UTF8</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> - Causes a JSP (and its dependent +files) to not be checked for modification during the specified time interval +(in seconds) from the last time the JSP was checked for modification. A value of +0 will cause the JSP to be checked on every access. Used in development mode +only. Default is <code>4</code> seconds.</li> + +<li><strong>recompileOnFail</strong> - If a JSP compilation fails should the +modificationTestInterval be ignored and the next access trigger a re-compilation +attempt? Used in development mode only and is disabled by default as compilation +may be expensive and could lead to excessive resource usage.</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>suppressSmap</strong> - Should the generation of SMAP info for JSR45 +debugging be suppressed? <code>true</code> or <code>false</code>, default +<code>false</code>.</li> + +<li><strong>trimSpaces</strong> - Should white spaces in template text between +actions or directives be trimmed ?, default <code>false</code>.</li> + +<li><strong>xpoweredBy</strong> - Determines whether X-Powered-By response +header is added by generated servlet. <code>true</code> or <code>false</code>, +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.</p> + +<p>Apache Ant, which was used in previous Tomcat releases, can be used instead +of the new compiler by simply removing the <code>lib/jasper-jdt.jar</code> file, +and placing the <code>ant.jar</code> file from the latest Ant distribution in +the <code>lib</code> folder. If you do this, you also need to use the "javac" +argument to catalina.sh.</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="Known issues"><!--()--></a><a name="Known_issues"><strong>Known issues</strong></a></font></td></tr><tr><td><blockquote> + +<p>As described in +<a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=39089";> +bug 39089</a>, a known JVM issue, +<a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6294277";> +bug 6294277</a>, may cause a +<code>java.lang.InternalError: name is too long to represent</code> exception +when compiling very large JSPs. If this is observed then it may be worked around +by using one of the following: +<ul> +<li>reduce the size of the JSP</li> +<li>disable SMAP generation and JSR-045 support by setting +<code>suppressSmap</code> to <code>true</code>.</li> +</ul> +</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="Production Configuration"><!--()--></a><a name="Production_Configuration"><strong>Production Configuration</strong></a></font></td></tr><tr><td><blockquote> + +<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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Web Application Compilation"><!--()--></a><a name="Web_Application_Compilation"><strong>Web Application Compilation</strong></a></font></td></tr><tr><td><blockquote> + +<p>Using Ant is the preferred way to compile web applications using JSPC. Note +that when pre-compiling JSPs, SMAP information only be included in the final +classes if suppressSmap is false and compile is true. +Use the script given below (a similar script is included in the "deployer" +download) to precompile a webapp: +</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> +<project name="Webapp Precompilation" default="all" basedir="."> + + <import file="${tomcat.home}/bin/catalina-tasks.xml"/> + + <target name="jspc"> + + <jasper + validateXml="false" + uriroot="${webapp.path}" + webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml" + outputDir="${webapp.path}/WEB-INF/src" /> + + </target> + + <target name="compile"> + + <mkdir dir="${webapp.path}/WEB-INF/classes"/> + <mkdir dir="${webapp.path}/WEB-INF/lib"/> + + <javac destdir="${webapp.path}/WEB-INF/classes" + optimize="off" + debug="on" failonerror="false" + srcdir="${webapp.path}/WEB-INF/src" + excludes="**/*.smap"> + <classpath> + <pathelement location="${webapp.path}/WEB-INF/classes"/> + <fileset dir="${webapp.path}/WEB-INF/lib"> + <include name="*.jar"/> + </fileset> + <pathelement location="${tomcat.home}/lib"/> + <fileset dir="${tomcat.home}/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> +</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> +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> +<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> +$ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH> +</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> +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 +features inside your jsp's, add the following javac compiler task attributes: +<code>source="1.5" target="1.5"</code>. For live +applications 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 the new Tomcat version.</li> +<li>Use java system property at server runtime to disable PageContext 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 it will vary +depending on the application.</li> +</ul> +</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 Jikes"><!--()--></a><a name="Using_Jikes"><strong>Using Jikes</strong></a></font></td></tr><tr><td><blockquote> + +<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_HOME/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> + +</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/jndi-datasource-examples-howto.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/jndi-datasource-examples-howto.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/jndi-datasource-examples-howto.html new file mode 100644 index 0000000..fdf9b19 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/jndi-datasource-examples-howto.html @@ -0,0 +1,610 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - JNDI Datasource HOW-TO</title><meta content="Les Hughes" name="author"><meta content="David Haraburda" name="author"><meta content="Glenn Nielsen" 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 Datasource 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="#Database_Connection_Pool_(DBCP)_Configurations">Database Connection Pool (DBCP) Configurations</a><ol><li><a href="#Installation">Installation</a></li><li><a href="#Preventing_dB_connection_pool_leaks">Preventing dB connection pool leaks</a></li><li><a href="#MySQL_DBCP_Example">MySQL DBCP Example</a></li><li><a href="#Oracle_8i,_9i_&_10g">Oracle 8i, 9i & 10g</a></li><li><a href="#PostgreSQL">PostgreSQL</a></li></ol></li><li><a href="#Non-DBCP_Solutions">Non-DBCP Solutions</a></li><li><a href="#Oracle_8i_with_OCI_client">Oracle 8i with OCI client</a><ol><li><a href="#Oracle_8i_with_OCI_client/Introduction">Introduction</a></li><li><a href="#Putting_it_all_together">Putting it all together</a></li></ol></li><li><a href="#Common_Problems">Common Problems</a><ol><li><a href="#Intermittent_dB_Connection_Failures">Intermittent dB Connection Failures</a></li><li><a href="#Random_Connection_Closed_Exceptions">Random Con nection Closed Exceptions</a></li><li><a href="#Context_versus_GlobalNamingResources">Context versus GlobalNamingResources</a></li><li><a href="#JNDI_Resource_Naming_and_Realm_Interaction">JNDI Resource Naming and Realm Interaction</a></li></ol></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>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 usage.</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 changed somewhat between +Tomcat 5.0.x and Tomcat 5.5.x.</b> You will most likely need to modify older +JNDI resource configurations to match the syntax in the example below in order +to make them work in Tomcat 6.x.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> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Database Connection Pool (DBCP) Configurations"><!--()--></a><a name="Database_Connection_Pool_(DBCP)_Configurations"><strong>Database Connection Pool (DBCP) Configurations</strong></a></font></td></tr><tr><td><blockquote> + +<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://commons.apache.org/dbcp/configuration.html";> +DBCP documentation</a> for a complete list of configuration parameters. +</p> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote> +<p>DBCP uses the Commons Database Connection Pool. It relies on +number of Commons components: +<ul> +<li>Commons DBCP</li> +<li>Commons Pool</li> +</ul> +These libraries are located in a single JAR at +<code>$CATALINA_HOME/lib/tomcat-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> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Preventing dB connection pool leaks"><!--()--></a><a name="Preventing_dB_connection_pool_leaks"><strong>Preventing dB connection pool leaks</strong></a></font></td></tr><tr><td><blockquote> + +<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 explicitly 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. 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: +<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> + removeAbandoned="true" +</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> +When available db connections run low DBCP will recover and recycle +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. +<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> + removeAbandonedTimeout="60" +</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> +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. +<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> + logAbandoned="true" +</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> +The default is <code>false</code>. +</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="MySQL DBCP Example"><!--()--></a><a name="MySQL_DBCP_Example"><strong>MySQL DBCP Example</strong></a></font></td></tr><tr><td><blockquote> + +<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/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. +<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> +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); +</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> +<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. +<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> +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> +</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> + +<h3>2. Context configuration</h3> +<p>Configure the JNDI DataSource in Tomcat by adding a declaration for your +resource to your <a href="config/context.html">Context</a>.</p> +<p>For example: + +<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 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 -1 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. + --> + + <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"/> + +</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> + +<h3>3. web.xml configuration</h3> + +<p>Now create a <code>WEB-INF/web.xml</code> for this test 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> +<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> +</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> + +<h3>4. Test code</h3> +<p>Now create a simple <code>test.jsp</code> page for use later. +<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> +<%@ 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> +</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>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_BASE/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> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Oracle 8i, 9i & 10g"><!--()--></a><a name="Oracle_8i,_9i_&_10g"><strong>Oracle 8i, 9i & 10g</strong></a></font></td></tr><tr><td><blockquote> +<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/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>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. Context configuration</h3> +<p>In a similar manner to the mysql config above, you will need to define your +Datasource in your <a href="config/context.html">Context</a>. 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. +<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="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"/> +</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> + +<h3>2. web.xml configuration</h3> +<p>You should ensure that you respect the element ordering defined by the DTD when you +create you applications web.xml file.</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>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> +</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>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> +<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 initContext = new InitialContext(); +Context envContext = (Context)initContext.lookup("java:/comp/env"); +DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle"); +Connection conn = ds.getConnection(); +//etc. +</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="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="PostgreSQL"><strong>PostgreSQL</strong></a></font></td></tr><tr><td><blockquote> +<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/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> + +<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="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"/> +</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> +<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 for your <a href="config/context.html">Context</a>. +The Context element should look something like the following. +</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 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> +</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>3. web.xml configuration</h3> +<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>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> +</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> + +<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> + +<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> +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!"); +} +</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> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Non-DBCP Solutions"><!--()--></a><a name="Non-DBCP_Solutions"><strong>Non-DBCP Solutions</strong></a></font></td></tr><tr><td><blockquote> +<p> +These solutions either utilise a single connection to the database (not recommended for anything other +than testing!) or some other pooling technology. +</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="Oracle 8i with OCI client"><!--()--></a><a name="Oracle_8i_with_OCI_client"><strong>Oracle 8i with OCI client</strong></a></font></td></tr><tr><td><blockquote> +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Oracle 8i with OCI client/Introduction"><!--()--></a><a name="Oracle_8i_with_OCI_client/Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> +<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/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> +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Putting it all together"><!--()--></a><a name="Putting_it_all_together"><strong>Putting it all together</strong></a></font></td></tr><tr><td><blockquote> +<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> +<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> +DriverManager.registerDriver(new +oracle.jdbc.driver.OracleDriver()); +conn = +DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password"); +</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> +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> +</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="Common Problems"><!--()--></a><a name="Common_Problems"><strong>Common Problems</strong></a></font></td></tr><tr><td><blockquote> +<p>Here are some common problems encountered with a web application which +uses a database and tips for how to solve them.</p> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Intermittent dB Connection Failures"><!--()--></a><a name="Intermittent_dB_Connection_Failures"><strong>Intermittent dB Connection Failures</strong></a></font></td></tr><tr><td><blockquote> +<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> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Random Connection Closed Exceptions"><!--()--></a><a name="Random_Connection_Closed_Exceptions"><strong>Random Connection Closed Exceptions</strong></a></font></td></tr><tr><td><blockquote> +<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> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Context versus GlobalNamingResources"><!--()--></a><a name="Context_versus_GlobalNamingResources"><strong>Context versus GlobalNamingResources</strong></a></font></td></tr><tr><td><blockquote> +<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> +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="JNDI Resource Naming and Realm Interaction"><!--()--></a><a name="JNDI_Resource_Naming_and_Realm_Interaction"><strong>JNDI Resource Naming and Realm Interaction</strong></a></font></td></tr><tr><td><blockquote> +<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> +</blockquote></td></tr></table> + +</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
