Bug 33755 - Documentation enhancement to JNDI-Datasources-examples for Postgres
Documentation enhancement to JNDI-Datasources-examples for Postgres
Status: RESOLVED FIXED
Product: Tomcat 5
Classification: Unclassified
Component: Catalina
Nightly Build
PC Linux
: P3 enhancement (vote)
: ---
Assigned To: Tomcat Developers Mailing List
:
Depends on:
Blocks:
  Show dependency tree
 
Reported: 2005-02-27 06:51 UTC by Tom Witmer
Modified: 2005-03-25 19:17 UTC (History)
0 users



Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Tom Witmer 2005-02-27 06:51:18 UTC
I struggled quite a bit defining a Postgres datasource with Tomcat, but finally
succeeded. To prevent the suffering of others, here are some enhancements to the
JNDI datasource web page that should make things easier for others. Diff is
against the current CVS checkout of Tomcat 5.

Index: jndi-datasource-examples-howto.xml
===================================================================
RCS file:
/home/cvspublic/jakarta-tomcat-catalina/webapps/docs/jndi-datasource-examples-howto.xml,v
retrieving revision 1.13
diff -u -3 -p -u -r1.13 jndi-datasource-examples-howto.xml
--- jndi-datasource-examples-howto.xml  27 Sep 2004 16:00:31 -0000      1.13
+++ jndi-datasource-examples-howto.xml  27 Feb 2005 05:47:12 -0000
@@ -335,16 +335,66 @@ Connection conn = ds.getConnection();

 <subsection name="PostgreSQL">
 <h3>0.    Introduction</h3>
-<p>PostgreSQL is configured in a similar manner to Oracle. Again, highlighting
the differences.
-These notes are untested as yet and we would appreciate feedback.</p>
-<h3>1.    server.xml configuration</h3>
+<p>PostgreSQL is configured in a similar manner to Oracle.
+
+<h3>1. Required files </h3>
+<p>
+Copy the Postgres JDBC jar to $CATALINA_HOME/common/lib. As with Oracle, the
+jars need to be in this directory in order for DBCP's Classloader to find
+them. This has to be done regardless of which configuration step you take next.
+</p>
+
+<h3>2. Resource configuration</h3>
+
+<p>
+You have two choices here: define a datasource that is shared across all Tomcat
+applications, or define a datasource specifically for one application.
+</p>
+
+<h4>2a. Shared resource configuration</h4>
+<p>
+Use this option if you wish to define a datasource that is shared across
+multiple Tomcat applications, or if you just prefer defining your datasource
+in this file.
+</p>
+<p><i>This author has not had success here, although others have reported so.
+Clarification would be appreciated here.</i></p>
+
 <source>
 &lt;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"/>
+          username="myuser" password="mypasswd" maxActive="20" maxIdle="10"
maxWait="-1"/&gt;
+
 </source>
-<h3>2.    web.xml configuration</h3>
+
+<h4>2b. Application-specific resource configuration</h4>
+
+<p>
+Use this option if you wish to define a datasource specific to your application,
+not visible to other Tomcat applications. This method is less invasive to your
+Tomcat installation.
+</p>
+
+</p>
+Create a resource definition file for your application defining the
+datasource. This file must have the same name as your application, so if
+your application deploys as <code>someApp.war</code>, this filename must
+be <code>someApp.xml</code>. This file should look something like the following.
+</p>
+
+<source>
+&lt;Context path="/someApp" docBase="someApp"
+   crossContext="true" reloadable="true" debug="1"&gt;
+
+&lt;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"/&gt;
+&lt;/Context&gt;
+</source>
+
+<h3>3. web.xml configuration</h3>
 <source>
 &lt;resource-ref&gt;
  &lt;description&gt;postgreSQL Datasource example&lt;/description&gt;
@@ -353,6 +403,28 @@ These notes are untested as yet and we w
  &lt;res-auth&gt;Container&lt;/res-auth&gt;
 &lt;/resource-ref&gt;
 </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 ( cxt == null ) {
+   throw new Exception("Data source not found!");
+}
+</source>
+
 </subsection>
 </section>
Comment 1 Juergen Weber 2005-03-22 23:52:48 UTC
It also would help very much, if the JNDI Datasource HOW-TO for 5.5 would state,
that there was a big change in the Resource element since 5.0.
I copied an application to 5.5 that ran fine with 5.0 and mysql.
On 5.5 I simply got the SQLException below which is not a fine indicator to the
real problem.

Caused by: java.sql.SQLException: No suitable driver
        at java.sql.DriverManager.getDriver(DriverManager.java:243)
        at org.apache.tomcat.dbcp.dbcp.BasicDataSource.createDataSource(BasicDat
aSource.java:773)
Comment 2 Yoav Shapira 2005-03-26 04:17:00 UTC
Both suggestions accepted and implemented.  Thanks for submitting the patch.

In the future, please submit patches as attachments to the Bugzilla issue rather
than in the comments section.  Thanks ;)