Author: jfrederic.clere(a)jboss.com
Date: 2011-09-08 12:22:12 -0400 (Thu, 08 Sep 2011)
New Revision: 1833
Removed:
trunk/webapps/docs/jndi-datasource-examples-howto.xml
trunk/webapps/docs/jndi-resources-howto.xml
Modified:
trunk/build.xml
trunk/webapps/docs/index.xml
trunk/webapps/docs/project.xml
Log:
remove more old docs.
Modified: trunk/build.xml
===================================================================
--- trunk/build.xml 2011-09-08 16:06:13 UTC (rev 1832)
+++ trunk/build.xml 2011-09-08 16:22:12 UTC (rev 1833)
@@ -165,14 +165,6 @@
includes="*.xml">
<param name="relative-path" expression=".."/>
</xslt>
- <xslt basedir="webapps/docs/architecture"
- destdir="${tomcat.build}/webapps/docs/architecture"
- extension=".html"
- style="webapps/docs/tomcat-docs.xsl"
- excludes="project.xml"
- includes="*.xml">
- <param name="relative-path" expression=".."/>
- </xslt>
<!-- Print friendly version -->
<mkdir dir="${tomcat.build}/webapps/docs/printer" />
@@ -229,15 +221,6 @@
<param name="relative-path" expression="../.."/>
<param name="project-menu" expression="nomenu"/>
</xslt>
- <xslt basedir="webapps/docs/architecture"
- destdir="${tomcat.build}/webapps/docs/architecture/printer"
- extension=".html"
- style="webapps/docs/tomcat-docs.xsl"
- excludes="project.xml"
- includes="*.xml">
- <param name="relative-path" expression="../.."/>
- <param name="project-menu" expression="nomenu"/>
- </xslt>
<!-- Website version -->
<mkdir dir="${jbossweb.site}" />
@@ -314,17 +297,6 @@
<param name="bodyonly" expression="true"/>
<param name="usehead" expression="true"/>
</xslt>
- <xslt basedir="webapps/docs/architecture"
- destdir="${jbossweb.site}/architecture"
- extension=".html"
- style="webapps/docs/tomcat-docs.xsl"
- excludes="project.xml"
- includes="*.xml">
- <param name="relative-path" expression=".."/>
- <param name="project-menu" expression="nomenu"/>
- <param name="bodyonly" expression="true"/>
- <param name="usehead" expression="true"/>
- </xslt>
</target>
Modified: trunk/webapps/docs/index.xml
===================================================================
--- trunk/webapps/docs/index.xml 2011-09-08 16:06:13 UTC (rev 1832)
+++ trunk/webapps/docs/index.xml 2011-09-08 16:22:12 UTC (rev 1833)
@@ -63,13 +63,6 @@
- Configuring and using a Java Security Manager to
support fine-grained control over the behavior of your web applications.
</li>
-<li><a href="jndi-resources-howto.html"><strong>JNDI
Resources</strong></a>
- - Configuring standard and custom resources in the JNDI naming context
- that is provided to each web application.</li>
-<li><a href="jndi-datasource-examples-howto.html">
- <strong>JDBC DataSource</strong></a>
- - Configuring a JNDI DataSoure with a DB connection pool.
- Examples for many popular databases.</li>
<li><a
href="class-loader-howto.html"><strong>Classloading</strong></a>
- Information about class loading in JBoss Web, including where to place
your application classes so that they are visible.</li>
Deleted: trunk/webapps/docs/jndi-datasource-examples-howto.xml
===================================================================
--- trunk/webapps/docs/jndi-datasource-examples-howto.xml 2011-09-08 16:06:13 UTC (rev
1832)
+++ trunk/webapps/docs/jndi-datasource-examples-howto.xml 2011-09-08 16:22:12 UTC (rev
1833)
@@ -1,645 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document url="jndi-datasource-examples-howto.html">
-
- &project;
-
- <properties>
- <author email="leslie.hughes(a)rubus.com">Les
Hughes</author>
- <author email="david-tomcat(a)haraburda.com">David
Haraburda</author>
- <author>Glenn Nielsen</author>
- <author email="yoavs(a)apache.org">Yoav Shapira</author>
- <title>JNDI Datasource HOW-TO</title>
- </properties>
-
-<body>
-
-<section name="Table of Contents">
-<p>
-<a href="#Introduction">Introduction</a><br />
-<a href="#Database Connection Pool (DBCP) Configurations">
-Database Connection Pool (DBCP) Configurations</a><br />
-<a href="#Non DBCP Solutions">Non DBCP Solutions</a><br />
-<a href="#Oracle 8i with OCI client">Oracle 8i with OCI
client</a><br />
-<a href="#Common Problems">Common Problems</a><br />
-</p>
-</section>
-
-<section name="Introduction">
-
-<p>JNDI Datasource configuration is covered extensively in the
-JNDI-Resources-HOWTO. However, feedback from <code>tomcat-user</code> has
-shown that specifics for individual configurations can be rather tricky.</p>
-
-<p>Here then are some example configurations that have been posted to
-tomcat-user for popular databases and some general tips for db useage.</p>
-
-<p>You should be aware that since these notes are derived from configuration
-and/or feedback posted to <code>tomcat-user</code> YMMV :-). Please let us
-know if you have any other tested configurations that you feel may be of use
-to the wider audience, or if you feel we can improve this section in anyway.</p>
-
-<p>
-<b>Please note that JNDI resource configuration 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 and JBoss Web.
-</p>
-
-<p>
-Also, please note that JNDI DataSource configuration in general, and this
-tutorial in particular, assumes that you have read and understood the
-<a href="config/context.html">Context</a> and
-<a href="config/host.html">Host</a> configuration references,
including
-the section about Automatic Application Deployment in the latter reference.
-</p>
-</section>
-
-<section name="Database Connection Pool (DBCP) Configurations">
-
-<p>DBCP provides support for JDBC 2.0. On systems using a 1.4 JVM DBCP
-will support JDBC 3.0. Please let us know if you have used DBCP and its
-JDBC 3.0 features with a 1.4 JVM.
-</p>
-
-<p>See the <a
href="http://jakarta.apache.org/commons/dbcp/configuration.html"...
-DBCP documentation</a> for a complete list of configuration parameters.
-</p>
-
-<subsection name="Installation">
-<p>DBCP uses the Jakarta-Commons Database Connection Pool. It relies on
-number of Jakarta-Commons components:
-<ul>
-<li>Jakarta-Commons DBCP</li>
-<li>Jakarta-Commons Collections</li>
-<li>Jakarta-Commons Pool</li>
-</ul>
-These libraries are located in a single JAR at
-<code>$CATALINA_HOME/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>
-
-</subsection>
-
-<subsection name="Preventing dB connection pool leaks">
-
-<p>
-A database connection pool creates and manages a pool of connections
-to a database. Recycling and reusing already existing connections
-to a dB is more efficient than opening a new connection.
-</p>
-
-<p>
-There is one problem with connection pooling. A web application has
-to explicetely close ResultSet's, Statement's, and Connection's.
-Failure of a web application to close these resources can result in
-them never being available again for reuse, a db connection pool "leak".
-This can eventually result in your web application db connections failing
-if there are no more available connections.</p>
-
-<p>
-There is a solution to this problem. The Jakarta-Commons DBCP can be
-configured to track and recover these abandoned dB connections. Not
-only can it recover them, but also generate a stack trace for the code
-which opened these resources and never closed them.</p>
-
-<p>
-To configure a DBCP DataSource so that abandoned dB connections are
-removed and recycled add the following attribute to the
-<code>Resource</code> configuration for your DBCP DataSource:
-<source>
- removeAbandoned="true"
-</source>
-When available db connections run low DBCP will recover and recyle
-any abandoned dB connections it finds. The default is <code>false</code>.
-</p>
-
-<p>
-Use the <code>removeAbandonedTimeout</code> attribute to set the number
-of seconds a dB connection has been idle before it is considered abandoned.
-<source>
- removeAbandonedTimeout="60"
-</source>
-The default timeout for removing abandoned connections is 300 seconds.
-</p>
-
-<p>
-The <code>logAbandoned</code> attribute can be set to
<code>true</code>
-if you want DBCP to log a stack trace of the code which abandoned the
-dB connection resources.
-<source>
- logAbandoned="true"
-</source>
-The default is <code>false</code>.
-</p>
-
-</subsection>
-
-<subsection name="MySQL DBCP Example">
-
-<h3>0. Introduction</h3>
-<p>Versions of <a
href="http://www.mysql.com/products/mysql/index.html">MySQL&... 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...
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.
-<source>
-mysql> GRANT ALL PRIVILEGES ON *.* TO javauser@localhost
- -> IDENTIFIED BY 'javadude' WITH GRANT OPTION;
-mysql> create database javatest;
-mysql> use javatest;
-mysql> create table testdata (
- -> id int not null auto_increment primary key,
- -> foo varchar(25),
- -> bar int);
-</source>
-<blockquote>
-<strong>Note:</strong> the above user should be removed once testing is
-complete!
-</blockquote>
-</p>
-
-<p>Next insert some test data into the testdata table.
-<source>
-mysql> insert into testdata values(null, 'hello', 12345);
-Query OK, 1 row affected (0.00 sec)
-
-mysql> select * from testdata;
-+----+-------+-------+
-| ID | FOO | BAR |
-+----+-------+-------+
-| 1 | hello | 12345 |
-+----+-------+-------+
-1 row in set (0.00 sec)
-
-mysql>
-</source>
-</p>
-
-<h3>2. Context configuration</h3>
-<p>Configure the JNDI DataSource in JBoss Web by adding a declaration for your
-resource to your <a
href="config/context.html">Context</a>.</p>
-<p>For example:
-
-<source>
-<Context path="/DBTest" docBase="DBTest"
- debug="5" reloadable="true"
crossContext="true">
-
- <!-- maxActive: Maximum number of dB connections in pool. Make sure you
- configure your mysqld max_connections large enough to handle
- all of your db connections. Set to 0 for no limit.
- -->
-
- <!-- maxIdle: Maximum number of idle dB connections to retain in pool.
- Set to -1 for no limit. See also the DBCP documentation on this
- and the minEvictableIdleTimeMillis configuration parameter.
- -->
-
- <!-- maxWait: Maximum time to wait for a dB connection to become available
- in ms, in this example 10 seconds. An Exception is thrown if
- this timeout is exceeded. Set to -1 to wait indefinitely.
- -->
-
- <!-- username and password: MySQL dB username and password for dB connections
-->
-
- <!-- driverClassName: Class name for the old mm.mysql JDBC driver is
- org.gjt.mm.mysql.Driver - we recommend using Connector/J though.
- Class name for the official MySQL Connector/J driver is com.mysql.jdbc.Driver.
- -->
-
- <!-- url: The JDBC connection url for connecting to your MySQL dB.
- The autoReconnect=true argument to the url makes sure that the
- mm.mysql JDBC Driver will automatically reconnect if mysqld closed the
- connection. mysqld by default closes idle connections after 8 hours.
- -->
-
- <Resource name="jdbc/TestDB" auth="Container"
type="javax.sql.DataSource"
- maxActive="100" maxIdle="30"
maxWait="10000"
- username="javauser" password="javadude"
driverClassName="com.mysql.jdbc.Driver"
-
url="jdbc:mysql://localhost:3306/javatest?autoReconnect=true"/>
-
-</Context>
-</source>
-</p>
-
-<h3>3. web.xml configuration</h3>
-
-<p>Now create a <code>WEB-INF/web.xml</code> for this test
application.
-<source>
-<web-app
xmlns="http://java.sun.com/xml/ns/j2ee"
-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
-http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
- version="2.4">
- <description>MySQL Test App</description>
- <resource-ref>
- <description>DB Connection</description>
- <res-ref-name>jdbc/TestDB</res-ref-name>
- <res-type>javax.sql.DataSource</res-type>
- <res-auth>Container</res-auth>
- </resource-ref>
-</web-app>
-</source>
-</p>
-
-<h3>4. Test code</h3>
-<p>Now create a simple <code>test.jsp</code> page for use later.
-<source>
-<%@ taglib
uri="http://java.sun.com/jsp/jstl/sql" prefix="sql"
%>
-<%@ taglib
uri="http://java.sun.com/jsp/jstl/core" prefix="c"
%>
-
-<sql:query var="rs" dataSource="jdbc/TestDB">
-select id, foo, bar from testdata
-</sql:query>
-
-<html>
- <head>
- <title>DB Test</title>
- </head>
- <body>
-
- <h2>Results</h2>
-
-<c:forEach var="row" items="${rs.rows}">
- Foo ${row.foo}<br/>
- Bar ${row.bar}<br/>
-</c:forEach>
-
- </body>
-</html>
-</source>
-</p>
-
-<p>That JSP page makes use of <a
href="http://java.sun.com/products/jsp/jstl">JSTL</a>&... SQL and
Core taglibs. You can get it from Sun's <a
href="http://java.sun.com/webservices/downloads/webservicespack.html...
Web Services Developer Pack</a> or <a
href="http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html&...
Taglib Standard 1.1</a> project - just make sure you get a 1.1.x release. Once you
have JSTL, copy <code>jstl.jar</code> and
<code>standard.jar</code> to your web app's
<code>WEB-INF/lib</code> directory.
-
-</p>
-
-<p>Finally deploy your web app into <code>$CATALINA_HOME/webapps</code>
either
-as a warfile called <code>DBTest.war</code> or into a sub-directory called
-<code>DBTest</code></p>
-<p>Once deployed, point a browser at
-<code>http://localhost:8080/DBTest/test.jsp</code> to view the fruits of
-your hard work.</p>
-
-</subsection>
-
-<subsection name="Oracle 8i, 9i & 10g">
-<h3>0. Introduction</h3>
-
-<p>Oracle requires minimal changes from the MySQL configuration except for the
-usual gotchas :-)</p>
-<p>Drivers for older Oracle versions may be distributed as *.zip files rather
-than *.jar files. JBoss Web 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.
-<source>
-<Resource name="jdbc/myoracle" auth="Container"
- type="javax.sql.DataSource"
driverClassName="oracle.jdbc.OracleDriver"
- url="jdbc:oracle:thin:@127.0.0.1:1521:mysid"
- username="scott" password="tiger"
maxActive="20" maxIdle="10"
- maxWait="-1"/>
-</source>
-</p>
-
-<h3>2. web.xml configuration</h3>
-<p>You should ensure that you respect the element ordering defined by the DTD when
you
-create you applications web.xml file.</p>
-<source>
-<resource-ref>
- <description>Oracle Datasource example</description>
- <res-ref-name>jdbc/myoracle</res-ref-name>
- <res-type>javax.sql.DataSource</res-type>
- <res-auth>Container</res-auth>
-</resource-ref>
-</source>
-<h3>3. Code example</h3>
-<p>You can use the same example application as above (asuming you create the
required DB
-instance, tables etc.) replacing the Datasource code with something like</p>
-<source>
-Context initContext = new InitialContext();
-Context envContext = (Context)initContext.lookup("java:/comp/env");
-DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle");
-Connection conn = ds.getConnection();
-//etc.
-</source>
-</subsection>
-
-
-<subsection name="PostgreSQL">
-<h3>0. Introduction</h3>
-<p>PostgreSQL is configured in a similar manner to Oracle.</p>
-
-<h3>1. Required files </h3>
-<p>
-Copy the Postgres JDBC jar to $CATALINA_HOME/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 JBoss Web
-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 JBoss Web applications, or if you just prefer defining your datasource
-in this file.
-</p>
-<p><i>This author has not had success here, although others have reported
so.
-Clarification would be appreciated here.</i></p>
-
-<source>
-<Resource name="jdbc/postgres" auth="Container"
- type="javax.sql.DataSource"
driverClassName="org.postgresql.Driver"
- url="jdbc:postgresql://127.0.0.1:5432/mydb"
- username="myuser" password="mypasswd"
maxActive="20" maxIdle="10" maxWait="-1"/>
-</source>
-<h4>2b. Application-specific resource configuration</h4>
-
-<p>
-Use this option if you wish to define a datasource specific to your application,
-not visible to other JBoss Web applications. This method is less invasive to your
-JBoss Web 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>
-
-<source>
-<Context path="/someApp" docBase="someApp"
- crossContext="true" reloadable="true" debug="1">
-
-<Resource name="jdbc/postgres" auth="Container"
- type="javax.sql.DataSource"
driverClassName="org.postgresql.Driver"
- url="jdbc:postgresql://127.0.0.1:5432/mydb"
- username="myuser" password="mypasswd"
maxActive="20" maxIdle="10"
-maxWait="-1"/>
-</Context>
-</source>
-
-<h3>3. web.xml configuration</h3>
-<source>
-<resource-ref>
- <description>postgreSQL Datasource example</description>
- <res-ref-name>jdbc/postgres</res-ref-name>
- <res-type>javax.sql.DataSource</res-type>
- <res-auth>Container</res-auth>
-</resource-ref>
-</source>
-
-<h4>4. Accessing the datasource</h4>
-<p>
-When accessing the datasource programmatically, remember to prepend
-<code>java:/comp/env</code> to your JNDI lookup, as in the following snippet
of
-code. Note also that "jdbc/postgres" can be replaced with any value you prefer,
provided
-you change it in the above resource definition file as well.
-</p>
-
-<source>
-InitialContext cxt = new InitialContext();
-if ( cxt == null ) {
- throw new Exception("Uh oh -- no context!");
-}
-
-DataSource ds = (DataSource) cxt.lookup( "java:/comp/env/jdbc/postgres" );
-
-if ( ds == null ) {
- throw new Exception("Data source not found!");
-}
-</source>
-
-</subsection>
-</section>
-
-<section name="Non-DBCP Solutions">
-<p>
-These solutions either utilise a single connection to the database (not recommended for
anything other
-than testing!) or some other pooling technology.
-</p>
-</section>
-
-<section name="Oracle 8i with OCI client">
-<subsection name="Introduction">
-<p>Whilst not strictly addressing the creation of a JNDI DataSource using the OCI
client, these notes can be combined with the
-Oracle and DBCP solution above.</p>
-<p>
-In order to use OCI driver, you should have an Oracle client installed. You should have
installed
-Oracle8i(8.1.7) client from cd, and download the suitable JDBC/OCI
-driver(Oracle8i 8.1.7.1 JDBC/OCI Driver) from <a
href="http://otn.oracle.com/">otn.oracle.com</a>.
-</p>
-<p>
-After renaming <code>classes12.zip</code> file to
<code>classes12.jar</code>
-for JBoss Web, 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 JBoss Web and JDK you are using.
-</p>
-</subsection>
-
-<subsection name="Putting it all together">
-<p>
-Ensure that you have the <code>ocijdbc8.dll</code> or
<code>.so</code> in your <code>$PATH</code> or
<code>LD_LIBRARY_PATH</code>
- (possibly in <code>$ORAHOME\bin</code>) and also confirm that the native
library can be loaded by a simple test program
-using <code>System.loadLibrary("ocijdbc8");</code>
-</p>
-<p>
-You should next create a simple test servlet or jsp that has these
-<strong>critical lines</strong>:
-</p>
-<source>
-DriverManager.registerDriver(new
-oracle.jdbc.driver.OracleDriver());
-conn =
-DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password");
-</source>
-<p>
-where database is of the form <code>host:port:SID</code> Now if you try to
access the URL of your
-test servlet/jsp and what you get is a
-<code>ServletException</code> with a root cause of
<code>java.lang.UnsatisfiedLinkError:get_env_handle</code>.
-</p>
-<p>
-First, the <code>UnsatisfiedLinkError</code> indicates that you have
-<ul>
-<li>a mismatch between your JDBC classes file and
-your Oracle client version. The giveaway here is the message stating that a needed
library file cannot be
-found. For example, you may be using a classes12.zip file from Oracle Version 8.1.6 with
a Version 8.1.5
-Oracle client. The classeXXXs.zip file and Oracle client software versions must match.
-</li>
-<li>A <code>$PATH</code>, <code>LD_LIBRARY_PATH</code>
problem.</li>
-<li>It has been reported that ignoring the driver you have downloded from otn and
using
-the classes12.zip file from the directory <code>$ORAHOME\jdbc\lib</code> will
also work.
-</li>
-</ul>
-</p>
-<p>
-Next you may experience the error <code>ORA-06401 NETCMN: invalid driver
designator</code>
-</p>
-<p>
-The Oracle documentation says : "Cause: The login (connect) string contains an
invalid
-driver designator. Action: Correct the string and re-submit."
-
-Change the database connect string (of the form <code>host:port:SID</code>)
with this one:
-<code>(description=(address=(host=myhost)(protocol=tcp)(port=1521))(connect_data=(sid=orcl)))</code>
-</p>
-<p>
-<i>Ed. Hmm, I don't think this is really needed if you sort out your TNSNames -
but I'm not an Oracle DBA :-)</i>
-</p>
-</subsection>
-</section>
-
-<section name="Common Problems">
-<p>Here are some common problems encountered with a web application which
-uses a database and tips for how to solve them.</p>
-
-<subsection name="Intermittent dB Connection Failures">
-<p>
-JBoss Web 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 JBoss Web 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 JBoss Web. When verbose gc is enabled
-your <code>$CATALINA_BASE/logs/catalina.out</code> log file will include
-data for every garbage collection including how long it took.</p>
-
-<p>When your JVM is tuned correctly 99% of the time a GC will take less
-than one second. The remainder will only take a few seconds. Rarely,
-if ever should a GC take more than 10 seconds.</p>
-
-<p>Make sure that the db connection timeout is set to 10-15 seconds.
-For the DBCP you set this using the parameter
<code>maxWait</code>.</p>
-
-</subsection>
-
-<subsection name="Random Connection Closed Exceptions">
-<p>
-These can occur when one request gets a db connection from the connection
-pool and closes it twice. When using a connection pool, closing the
-connection just returns it to the pool for reuse by another request,
-it doesn't close the connection. And JBoss Web uses multiple threads to
-handle concurrent requests. Here is an example of the sequence
-of events which could cause this error in JBoss Web:
-<pre>
- Request 1 running in Thread 1 gets a db connection.
-
- Request 1 closes the db connection.
-
- The JVM switches the running thread to Thread 2
-
- Request 2 running in Thread 2 gets a db connection
- (the same db connection just closed by Request 1).
-
- The JVM switches the running thread back to Thread 1
-
- Request 1 closes the db connection a second time in a finally block.
-
- The JVM switches the running thread back to Thread 2
-
- Request 2 Thread 2 tries to use the db connection but fails
- because Request 1 closed it.
-</pre>
-Here is an example of properly written code to use a db connection
-obtained from a connection pool:
-<pre>
- Connection conn = null;
- Statement stmt = null; // Or PreparedStatement if needed
- ResultSet rs = null;
- try {
- conn = ... get connection from connection pool ...
- stmt = conn.createStatement("select ...");
- rs = stmt.executeQuery();
- ... iterate through the result set ...
- rs.close();
- rs = null;
- stmt.close();
- stmt = null;
- conn.close(); // Return to connection pool
- conn = null; // Make sure we don't close it twice
- } catch (SQLException e) {
- ... deal with errors ...
- } finally {
- // Always make sure result sets and statements are closed,
- // and the connection is returned to the pool
- if (rs != null) {
- try { rs.close(); } catch (SQLException e) { ; }
- rs = null;
- }
- if (stmt != null) {
- try { stmt.close(); } catch (SQLException e) { ; }
- stmt = null;
- }
- if (conn != null) {
- try { conn.close(); } catch (SQLException e) { ; }
- conn = null;
- }
- }
-</pre>
-</p>
-
-</subsection>
-
-<subsection name="Context versus GlobalNamingResources">
-<p>
- Please note that although the above instructions place the JNDI declarations in a
Context
- element, it is possible and sometimes desirable to place these declarations in the
- <a href="config/globalresources.html">GlobalNamingResources</a>
section of the server
- configuration file. A resource placed in the GlobalNamingResources section will be
shared
- among the Contexts of the server.
-</p>
-</subsection>
-
-<subsection name="JNDI Resource Naming and Realm Interaction">
-<p>
- In order to get Realms to work, the realm must refer to the datasource as
- defined in the <GlobalNamingResources> or <Context>
section, not a datasource as renamed
- using <ResourceLink>.
-</p>
-</subsection>
-
-</section>
-
-</body>
-</document>
Deleted: trunk/webapps/docs/jndi-resources-howto.xml
===================================================================
--- trunk/webapps/docs/jndi-resources-howto.xml 2011-09-08 16:06:13 UTC (rev 1832)
+++ trunk/webapps/docs/jndi-resources-howto.xml 2011-09-08 16:22:12 UTC (rev 1833)
@@ -1,764 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document url="jndi-resources-howto.html">
-
- &project;
-
- <properties>
- <author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
- <author email="yoavs(a)apache.org">Yoav Shapira</author>
- <title>JNDI Resources HOW-TO</title>
- </properties>
-
-<body>
-
-
-<section name="Introduction">
-
-<p>JBoss Web provides a JNDI <strong>InitialContext</strong>
implementation
-instance for each web application running under it, in a manner that is
-compatible with those provided by a
-<a
href="http://java.sun.com/j2ee">Java2 Enterprise Edition</a>
application
-server.
-
-The J2EE standard provides a standard set of elements in
-the <code>/WEB-INF/web.xml</code> file to reference resources; resources
-referenced in these elements must be defined in an application-server-specific
configuration.
-</p>
-
-<p>For JBoss Web, these entries in per-web-application
-<code>InitialContext</code> are configured in the
-<code><strong><Context></strong></code> elements
that can be specified
-in either <code>$CATALINA_HOME/conf/server.xml</code> or, preferably,
-the per-web-application context XML file (either
<code>META-INF/context.xml</code>).
-</p>
-
-<p>JBoss Web maintains a separate namespace of global resources for the
-entire server. These are configured in the
-<a href="config/globalresources.html">
-<code><strong><GlobalNameingResources></strong></code></a>
element of
-<code>$CATALINA_HOME/conf/server.xml</code>. You may expose these resources
to
-web applications by using
-<code><strong><ResourceLink></strong></code>
elements.
-</p>
-
-<p>The resources defined in these elements
-may be referenced by the following elements in the web application deployment
-descriptor (<code>/WEB-INF/web.xml</code>) of your web
application:</p>
-<ul>
-<li><code><strong><env-entry></strong></code>
- Environment entry, a
- single-value parameter that can be used to configure how the application
- will operate.</li>
-<li><code><strong><resource-ref></strong></code>
- Resource reference,
- which is typically to an object factory for resources such as a JDBC
- <code>DataSource</code>, a JavaMail <code>Session</code>, or
custom
- object factories configured into JBoss Web.</li>
-<li><code><strong><resource-env-ref></strong></code>
- Resource
- environment reference, a new variation of <code>resource-ref</code>
- added in Servlet 2.4 that is simpler to configure for resources
- that do not require authentication information.</li>
-</ul>
-
-<p>The <code>InitialContext</code> is configured as a web application
is
-initially deployed, and is made available to web application components (for
-read-only access). All configured entries and resources are placed in
-the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
-access to a resource - in this case, to a JDBC <code>DataSource</code> -
-would look something like this:</p>
-
-<source>
-// Obtain our environment naming context
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-
-// Look up our data source
-DataSource ds = (DataSource)
- envCtx.lookup("jdbc/EmployeeDB");
-
-// Allocate and use a connection from the pool
-Connection conn = ds.getConnection();
-... use this connection to access the database ...
-conn.close();
-</source>
-
-<p>See the following Specifications for more information about programming APIs
-for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE)
-servers, which JBoss Web emulates for the services that it provides:</p>
-<ul>
-<li><a
href="http://java.sun.com/products/jndi/#download">Java
Naming and
- Directory Interface</a> (included in JDK 1.4, available separately for
- prior JDK versions)</li>
-<li><a
href="http://java.sun.com/j2ee/download.html">J2EE Platform
- Specification</a> (in particular, see Chapter 5 on
<em>Naming</em>)</li>
-</ul>
-
-</section>
-
-
-<section name="Configuring JNDI Resources">
-
-<p>Each available JNDI Resource is configured based on inclusion of the
-following elements in the
<code><strong><Context></strong></code> or
-<code><strong><DefaultContext></strong></code>
elements:</p>
-
-<ul>
-<li><a href="config/context.html#Environment
Entries"><Environment></a> -
- Configure names and values for scalar environment entries that will be
- exposed to the web application through the JNDI
- <code>InitialContext</code> (equivalent to the inclusion of an
- <code><env-entry></code> element in the web application
- deployment descriptor).</li>
-<li><a href="config/context.html#Resource
Definitions"><Resource></a> -
- Configure the name and data type of a resource made available to the
- application (equivalent to the inclusion of a
- <code><resource-ref></code> element in the web application
- deployment descriptor).</li>
-<li><a href="config/context.html#Resource
Links"><ResourceLink></a> -
- Add a link to a resource defined in the global JNDI context. Use resource
- links to give a web application access to a resource defined in
- the<a
href="config/globalresources.html"><GlobalNamingResources></a>
- child element of the <a
href="config/server.html"><Server></a>
- element.</li>
-<li><a
href="config/context.html#Transaction"><Transaction></a>
-
- Add a resource factory for instantiating the UserTransaction object
- instance that is available at
<code>java:comp/UserTransaction</code>.</li>
-
-</ul>
-
-<p>Any number of these elements may be nested inside a
-<a href="config/context.html"><Context></a> element
(to be associated
-only with that particular web application).</p>
-
-<p>In addition, the names and values of all
<code><env-entry></code>
-elements included in the web application deployment descriptor
-(<code>/WEB-INF/web.xml</code>) are configured into the initial context as
-well, overriding corresponding values from <code>conf/server.xml</code>
-<strong>only</strong> if allowed by the corresponding
-<code><Environment></code> element (by setting the
-<code>override</code> attribute to "true").</p>
-
-<p>Global resources can be defined in the server-wide JNDI context, by adding
-the resource elements described above to the
-<a
href="config/globalresources.html"><GlobalNamingResources></a>
-child element of the <a
href="config/server.html"><Server></a>
-element and using a
-<a href="config/context.html#Resource
Links"><ResourceLink></a> to
-include it in the per-web-application context.</p>
-
-</section>
-
-
-<section name="JBoss Web Standard Resource Factories">
-
- <p>JBoss Web includes a series of standard resource factories that can
- provide services to your web applications, but give you configuration
- flexibility (in <code>$CATALINA_HOME/conf/server.xml</code>) without
- modifying the web application or the deployment descriptor. Each
- subsection below details the configuration and usage of the standard
- resource factories.</p>
-
- <p>See <a href="#Adding Custom Resource Factories">Adding Custom
- Resource Factories</a> for information about how to create, install,
- configure, and use your own custom resource factory classes with
- JBoss Web.</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 JBoss Web and cannot be assumed
- to be available on other containers.</p>
-
- <subsection name="Generic JavaBean Resources">
-
- <h3>0. Introduction</h3>
-
- <p>This resource factory can be used to create objects of
<em>any</em>
- Java class that conforms to standard JavaBeans naming conventions (i.e.
- it has a zero-arguments constructor, and has property setters that
- conform to the setFoo() naming pattern. The resource factory will
- create a new instance of the appropriate bean class every time a
- <code>lookup()</code> for this entry is made.</p>
-
- <p>The steps required to use this facility are described below.</p>
-
- <h3>1. Create Your JavaBean Class</h3>
-
- <p>Create the JavaBean class which will be instantiated each time
- that the resource factory is looked up. For this example, assume
- you create a class <code>com.mycompany.MyBean</code>, which looks
- like this:</p>
-
-<source>
-package com.mycompany;
-
-public class MyBean {
-
- private String foo = "Default Foo";
-
- public String getFoo() {
- return (this.foo);
- }
-
- public void setFoo(String foo) {
- this.foo = foo;
- }
-
- private int bar = 0;
-
- public int getBar() {
- return (this.bar);
- }
-
- public void setBar(int bar) {
- this.bar = bar;
- }
-
-
-}
-</source>
-
- <h3>2. Declare Your Resource Requirements</h3>
-
- <p>Next, modify your web application deployment descriptor
- (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
- you will request new instances of this bean. The simplest approach is
- to use a <code><resource-env-ref></code> element, like
this:</p>
-
-<source>
-<resource-env-ref>
- <description>
- Object factory for MyBean instances.
- </description>
- <resource-env-ref-name>
- bean/MyBeanFactory
- </resource-env-ref-name>
- <resource-env-ref-type>
- com.mycompany.MyBean
- </resource-env-ref-type>
-</resource-env-ref>
-</source>
-
- <p><strong>WARNING</strong> - Be sure you respect the element
ordering
- that is required by the DTD for web application deployment descriptors!
- See the
- <a
href="http://java.sun.com/products/servlet/download.html">Se...
- Specification</a> for details.</p>
-
- <h3>3. Code Your Application's Use Of This Resource</h3>
-
- <p>A typical use of this resource environment reference might look
- like this:</p>
-
-<source>
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
-
-writer.println("foo = " + bean.getFoo() + ", bar = " +
- bean.getBar());
-</source>
-
- <h3>4. Configure JBoss Web's Resource Factory</h3>
-
- <p>To configure JBoss Web's resource factory, add an elements like this to
the
- <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
- <code>Context</code> element for this web application.</p>
-<source>
-<Context ...>
- ...
- <Resource name="bean/MyBeanFactory" auth="Container"
- type="com.mycompany.MyBean"
- factory="org.apache.naming.factory.BeanFactory"
- bar="23"/>
- ...
-</Context>
-</source>
-
- <p>Note that the resource name (here,
<code>bean/MyBeanFactory</code>
- must match the value specified in the web application deployment
- descriptor. We are also initializing the value of the <code>bar</code>
- property, which will cause <code>setBar(23)</code> to be called before
- the new bean is returned. Because we are not initializing the
- <code>foo</code> property (although we could have), the bean will
- contain whatever default value is set up by its constructor.</p>
-
- </subsection>
-
-
- <subsection name="JavaMail Sessions">
-
- <h3>0. Introduction</h3>
-
- <p>In many web applications, sending electronic mail messages is a
- required part of the system's functionality. The
- <a
href="http://java.sun.com/products/javamail">Java Mail</a>
API
- makes this process relatively straightforward, but requires many
- configuration details that the client application must be aware of
- (including the name of the SMTP host to be used for message sending).</p>
-
- <p>JBoss Web includes a standard resource factory that will create
- <code>javax.mail.Session</code> session instances for you, already
- connected to the SMTP server that is configured in
<code>server.xml</code>.
- In this way, the application is totally insulated from changes in the
- email server configuration environment - it simply asks for, and receives,
- a preconfigured session whenever needed.</p>
-
- <p>The steps required for this are outlined below.</p>
-
- <h3>1. Declare Your Resource Requirements</h3>
-
- <p>The first thing you should do is modify the web application deployment
- descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name
under
- which you will look up preconfigured sessions. By convention, all such
- names should resolve to the <code>mail</code> subcontext (relative to
the
- standard <code>java:comp/env</code> naming context that is the root of
- all provided resource factories. A typical <code>web.xml</code> entry
- might look like this:</p>
-<source>
-<resource-ref>
- <description>
- Resource reference to a factory for javax.mail.Session
- instances that may be used for sending electronic mail
- messages, preconfigured to connect to the appropriate
- SMTP server.
- </description>
- <res-ref-name>
- mail/Session
- </res-ref-name>
- <res-type>
- javax.mail.Session
- </res-type>
- <res-auth>
- Container
- </res-auth>
-</resource-ref>
-</source>
-
- <p><strong>WARNING</strong> - Be sure you respect the element
ordering
- that is required by the DTD for web application deployment descriptors!
- See the
- <a
href="http://java.sun.com/products/servlet/download.html">Se...
- Specification</a> for details.</p>
-
- <h3>2. Code Your Application's Use Of This Resource</h3>
-
- <p>A typical use of this resource reference might look like this:</p>
-<source>
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-Session session = (Session) envCtx.lookup("mail/Session");
-
-Message message = new MimeMessage(session);
-message.setFrom(new InternetAddress(request.getParameter("from"));
-InternetAddress to[] = new InternetAddress[1];
-to[0] = new InternetAddress(request.getParameter("to"));
-message.setRecipients(Message.RecipientType.TO, to);
-message.setSubject(request.getParameter("subject"));
-message.setContent(request.getParameter("content"), "text/plain");
-Transport.send(message);
-</source>
-
- <p>Note that the application uses the same resource reference name
- that was declared in the web application deployment descriptor. This
- is matched up against the resource factory that is configured in
- <code>$CATALINA_HOME/conf/server.xml</code>, as described
below.</p>
-
- <h3>3. Configure JBoss Web's Resource Factory</h3>
-
- <p>To configure JBoss Web's resource factory, add an elements like this to
the
- <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
- <code>Context</code> element for this web application.</p>
-<source>
-<Context ...>
- ...
- <Resource name="mail/Session" auth="Container"
- type="javax.mail.Session"
- mail.smtp.host="localhost"/>
- ...
-</Context>
-</source>
-
- <p>Note that the resource name (here, <code>mail/Session</code>)
must
- match the value specified in the web application deployment descriptor.
- Customize the value of the <code>mail.smtp.host</code> parameter to
- point at the server that provides SMTP service for your network.</p>
-
- <h3>4. Install the JavaMail libraries</h3>
-
- <p><a
href="http://java.sun.com/products/javamail/downloads/index.html"
target="_blank">
- Download the JavaMail API</a>. The JavaMail API requires the Java Activation
- Framework (JAF) API as well. The Java Activation Framework can be downloaded
- from <a
href="http://java.sun.com/products/javabeans/glasgow/jaf.html"&...
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
- JBoss Web during the initialization of the mail Session Resource.
- <strong>Note:</strong> placing these jars in both common/lib and a
- web application's lib folder will cause an error, so ensure you have
- them in the $CATALINA_HOME/lib location only.
- </p>
-
- <h3>Example Application</h3>
-
- <p>The <code>/examples</code> application included with JBoss Web
contains
- an example of utilizing this resource factory. It is accessed via the
- "JSP Examples" link. The source code for the servlet that actually
- sends the mail message is in
- <code>/WEB-INF/classes/SendMailServlet.java</code>.</p>
-
- <p><strong>WARNING</strong> - The default configuration assumes
that
- there is an SMTP server listing on port 25 on <code>localhost</code>.
- If this is not the case, edit the
- <code>$CATALINA_HOME/conf/server.xml</code> file, and modify the
- parameter value for the <code>mail.smtp.host</code> parameter to be
- the host name of an SMTP server on your network.</p>
-
- </subsection>
-
- <subsection name="JDBC Data Sources">
-
- <h3>0. Introduction</h3>
-
- <p>Many web applications need to access a database via a JDBC driver,
- to support the functionality required by that application. The J2EE
- Platform Specification requires J2EE Application Servers to make
- available a <em>DataSource</em> implementation (that is, a connection
- pool for JDBC connections) for this purpose. JBoss Web offers exactly
- the same support, so that database-based applications you develop on
- JBoss Web 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.co...
-
- 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.fra...
-
- The JDBC 2.1 API Specification.</li>
- <li><a
href="http://java.sun.com/products/jdbc/jdbc20.stdext.pdf">h...
-
- 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.su...
-
- 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 JBoss
Web
- is based on the <strong>DBCP</strong> connection pool from the
- <a
href="http://jakarta.apache.org/commons">Jakarta
Commons</a>
- subproject. However, it is possible to use any other connection pool
- that implements <code>javax.sql.DataSource</code>, by writing your
- own custom resource factory, as described
- <a href="#Adding Custom Resource
Factories">below</a>.</p>
-
- <h3>1. Install Your JDBC Driver</h3>
-
- <p>Use of the <em>JDBC Data Sources</em> JNDI Resource Factory
requires
- that you make an appropriate JDBC driver available to both JBoss Web 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>
-<source>
-<resource-ref>
- <description>
- Resource reference to a factory for java.sql.Connection
- instances that may be used for talking to a particular
- database that is configured in the server.xml file.
- </description>
- <res-ref-name>
- jdbc/EmployeeDB
- </res-ref-name>
- <res-type>
- javax.sql.DataSource
- </res-type>
- <res-auth>
- Container
- </res-auth>
-</resource-ref>
-</source>
-
- <p><strong>WARNING</strong> - Be sure you respect the element
ordering
- that is required by the DTD for web application deployment descriptors!
- See the
- <a
href="http://java.sun.com/products/servlet/download.html">Se...
- Specification</a> for details.</p>
-
- <h3>3. Code Your Application's Use Of This Resource</h3>
-
- <p>A typical use of this resource reference might look like this:</p>
-<source>
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-DataSource ds = (DataSource)
- envCtx.lookup("jdbc/EmployeeDB");
-
-Connection conn = ds.getConnection();
-... use this connection to access the database ...
-conn.close();
-</source>
-
- <p>Note that the application uses the same resource reference name
- that was declared in the web application deployment descriptor. This
- is matched up against the resource factory that is configured in
- <code>$CATALINA_HOME/conf/server.xml</code>, as described
below.</p>
-
- <h3>4. Configure JBoss Web's Resource Factory</h3>
-
- <p>To configure JBoss Web's resource factory, add an element like this to
the
- <code>/META-INF/context.xml</code> file in the web
application.</p>
-<source>
-<Context ...>
- ...
- <Resource name="jdbc/EmployeeDB" auth="Container"
- type="javax.sql.DataSource" username="dbusername"
password="dbpassword"
- driverClassName="org.hsql.jdbcDriver"
url="jdbc:HypersonicSQL:database"
- maxActive="8" maxIdle="4"/>
- ...
-</Context>
-</source>
-
- <p>Note that the resource name (here, <code>jdbc/EmployeeDB</code>)
must
- match the value specified in the web application deployment descriptor.</p>
-
- <p>This example assumes that you are using the HypersonicSQL database
- JDBC driver. Customize the <code>driverClassName</code> and
- <code>driverName</code> parameters to match your actual database's
- JDBC driver and connection URL.</p>
-
- <p>The configuration properties for JBoss Web's standard data source
- resource factory
- (<code>org.apache.tomcat.dbcp.dbcp.BasicDataSourceFactory</code>) are
- as follows:</p>
- <ul>
- <li><strong>driverClassName</strong> - Fully qualified Java class
name
- of the JDBC driver to be used.</li>
- <li><strong>maxActive</strong> - The maximum number of active
instances
- that can be allocated from this pool at the same time.</li>
- <li><strong>maxIdle</strong> - The maximum number of connections
that
- can sit idle in this pool at the same time.</li>
- <li><strong>maxWait</strong> - The maximum number of milliseconds
that the
- pool will wait (when there are no available connections) for a
- connection to be returned before throwing an exception.</li>
- <li><strong>password</strong> - Database password to be passed to
our
- JDBC driver.</li>
- <li><strong>url</strong> - Connection URL to be passed to our JDBC
driver.
- (For backwards compatibility, the property <code>driverName</code>
- is also recognized.)</li>
- <li><strong>user</strong> - Database username to be passed to our
- JDBC driver.</li>
- <li><strong>validationQuery</strong> - SQL query that can be used
by the
- pool to validate connections before they are returned to the
- application. If specified, this query MUST be an SQL SELECT
- statement that returns at least one row.</li>
- </ul>
- <p>For more details, please refer to the commons-dbcp documentation.</p>
-
- </subsection>
-
-</section>
-
-
-<section name="Adding Custom Resource Factories">
-
- <p>If none of the standard resource factories meet your needs, you can
- write your own factory and integrate it into JBoss Web, and then configure
- the use of this factory in the <code>conf/server.xml</code> configuration
- file. In the example below, we will create a factory that only knows how
- to create <code>com.mycompany.MyBean</code> beans, from the
- <a href="#Generic JavaBean Resources">Generic JavaBean
Resources</a>
- example, above.</p>
-
- <h3>1. Write A Resource Factory Class</h3>
-
- <p>You must write a class that implements the JNDI service provider
- <code>javax.naming.spi.ObjectFactory</code> inteface. Every time your
- web application calls <code>lookup()</code> on a context entry that is
- bound to this factory, the <code>getObjectInstance()</code> method is
- called, with the following arguments:</p>
- <ul>
- <li><strong>Object obj</strong> - The (possibly null) object
containing
- location or reference information that can be used in creating an
- object. For JBoss Web, this will always be an object of type
- <code>javax.naming.Reference</code>, which contains the class name
- of this factory class, as well as the configuration properties
- (from <code>conf/server.xml</code>) to use in creating objects
- to be returned.</li>
- <li><strong>Name name</strong> - The name to which this factory is
bound
- relative to <code>nameCtx</code>, or <code>null</code> if
no name
- is specified.</li>
- <li><strong>Context nameCtx</strong> - The context relative to which
the
- <code>name</code> parameter is specified, or
<code>null</code> if
- <code>name</code> is relative to the default initial
context.</li>
- <li><strong>Hashtable environment</strong> - The (possibly null)
- environment that is used in creating this object. This is generally
- ignored in JBoss Web object factories.</li>
- </ul>
-
- <p>To create a resource factory that knows how to produce
<code>MyBean</code>
- instances, you might create a class like this:</p>
-
-<source>
-package com.mycompany;
-
-import java.util.Enumeration;
-import java.util.Hashtable;
-import javax.naming.Context;
-import javax.naming.Name;
-import javax.naming.NamingException;
-import javax.naming.RefAddr;
-import javax.naming.Reference;
-import javax.naming.spi.ObjectFactory;
-
-public class MyBeanFactory implements ObjectFactory {
-
- public Object getObjectInstance(Object obj,
- Name name, Context nameCtx, Hashtable environment)
- throws NamingException {
-
- // Acquire an instance of our specified bean class
- MyBean bean = new MyBean();
-
- // Customize the bean properties from our attributes
- Reference ref = (Reference) obj;
- Enumeration addrs = ref.getAll();
- while (addrs.hasMoreElements()) {
- RefAddr addr = (RefAddr) addrs.nextElement();
- String name = addr.getType();
- String value = (String) addr.getContent();
- if (name.equals("foo")) {
- bean.setFoo(value);
- } else if (name.equals("bar")) {
- try {
- bean.setBar(Integer.parseInt(value));
- } catch (NumberFormatException e) {
- throw new NamingException("Invalid 'bar' value " +
value);
- }
- }
- }
-
- // Return the customized instance
- return (bean);
-
- }
-
-}
-</source>
-
- <p>In this example, we are unconditionally creating a new instance of
- the <code>com.mycompany.MyBean</code> class, and populating its properties
- based on the parameters included in the
<code><ResourceParams></code>
- element that configures this factory (see below). You should note that any
- parameter named <code>factory</code> should be skipped - that parameter is
- used to specify the name of the factory class itself (in this case,
- <code>com.mycompany.MyBeanFactory</code>) rather than a property of the
- bean being configured.</p>
-
- <p>For more information about <code>ObjectFactory</code>, see the
- <a
href="http://java.sun.com/products/jndi/docs.html">JNDI 1.2 Service
- Provider Interface (SPI) Specification</a>.</p>
-
- <p>You will need to compile this class against a class path that includes
- all of the JAR files in the <code>$CATALINA_HOME/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>
-
-<source>
-<resource-env-ref>
- <description>
- Object factory for MyBean instances.
- </description>
- <resource-env-ref-name>
- bean/MyBeanFactory
- </resource-env-ref-name>
- <resource-env-ref-type>
- com.mycompany.MyBean
- </resource-env-ref-type>
-<resource-env-ref>
-</source>
-
- <p><strong>WARNING</strong> - Be sure you respect the element
ordering
- that is required by the DTD for web application deployment descriptors!
- See the
- <a
href="http://java.sun.com/products/servlet/download.html">Se...
- Specification</a> for details.</p>
-
- <h3>3. Code Your Application's Use Of This Resource</h3>
-
- <p>A typical use of this resource environment reference might look
- like this:</p>
-
-<source>
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
-
-writer.println("foo = " + bean.getFoo() + ", bar = " +
- bean.getBar());
-</source>
-
- <h3>4. Configure JBoss Web's Resource Factory</h3>
-
- <p>To configure JBoss Web's resource factory, add an elements like this to
the
- <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
- <code>Context</code> element for this web application.</p>
-<source>
-<Context ...>
- ...
- <Resource name="bean/MyBeanFactory" auth="Container"
- type="com.mycompany.MyBean"
- factory="com.mycompany.MyBeanFactory"
- bar="23"/>
- ...
-</Context>
-</source>
-
- <p>Note that the resource name (here,
<code>bean/MyBeanFactory</code>
- must match the value specified in the web application deployment
- descriptor. We are also initializing the value of the <code>bar</code>
- property, which will cause <code>setBar(23)</code> to be called before
- the new bean is returned. Because we are not initializing the
- <code>foo</code> property (although we could have), the bean will
- contain whatever default value is set up by its constructor.</p>
-
- <p>You will also note that, from the application developer's perspective,
- the declaration of the resource environment reference, and the programming
- used to request new instances, is identical to the approach used for the
- <em>Generic JavaBean Resources</em> example. This illustrates one of
the
- advantages of using JNDI resources to encapsulate functionality - you can
- change the underlying implementation without necessarily having to
- modify applications using the resources, as long as you maintain
- compatible APIs.</p>
-
-</section>
-
-
-
-</body>
-
-</document>
Modified: trunk/webapps/docs/project.xml
===================================================================
--- trunk/webapps/docs/project.xml 2011-09-08 16:06:13 UTC (rev 1832)
+++ trunk/webapps/docs/project.xml 2011-09-08 16:22:12 UTC (rev 1833)
@@ -19,8 +19,6 @@
<item name="Deployer"
href="deployer-howto.html"/>
<item name="Realms and AAA"
href="realm-howto.html"/>
<item name="Security Manager"
href="security-manager-howto.html"/>
- <item name="JNDI Resources"
href="jndi-resources-howto.html"/>
- <item name="JDBC DataSources"
href="jndi-datasource-examples-howto.html"/>
<item name="Classloading"
href="class-loader-howto.html"/>
<item name="JSPs"
href="jasper-howto.html"/>
<item name="SSL"
href="ssl-howto.html"/>