Updated documentation and added wrappers for toString and added an example

git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@713522 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/modules/jdbc-pool/doc/jdbc-pool.xml b/modules/jdbc-pool/doc/jdbc-pool.xml
index cd68836..9bc11de 100644 (file)
--- a/modules/jdbc-pool/doc/jdbc-pool.xml
+++ b/modules/jdbc-pool/doc/jdbc-pool.xml
@@ -338,6 +338,98 @@
   </subsection>
 </section>
 
+<section name="Code Example">
+  <p>Other examples of Tomcat configuration for JDBC usage can be found <a href="http://tomcat.apache.org/tomcat-6.0-doc/jndi-datasource-examples-howto.html">in the Tomcat documentation</a>. </p>
+  <subsection name="Plain Ol' Java">
+    <p>Here is a simple example of how to create and use a data source.</p> 
+    <source>
+        import java.sql.Connection;
+        import java.sql.ResultSet;
+        import java.sql.Statement;
+        
+        import org.apache.tomcat.jdbc.pool.DataSource;
+        import org.apache.tomcat.jdbc.pool.PoolProperties;
+        
+        public class SimplePOJOExample {
+        
+            public static void main(String[] args) throws Exception {
+                PoolProperties p = new PoolProperties();
+                p.setUrl("jdbc:mysql://localhost:3306/mysql?autoReconnect=true");
+                p.setDriverClassName("com.mysql.jdbc.Driver");
+                p.setUsername("root");
+                p.setPassword("password");
+                p.setJmxEnabled(true);
+                p.setTestWhileIdle(false);
+                p.setTestOnBorrow(true);
+                p.setValidationQuery("SELECT 1");
+                p.setTestOnReturn(false);
+                p.setValidationInterval(30000);
+                p.setTimeBetweenEvictionRunsMillis(30000);
+                p.setMaxActive(100);
+                p.setInitialSize(10);
+                p.setMaxWait(10000);
+                p.setRemoveAbandonedTimeout(60);
+                p.setMinEvictableIdleTimeMillis(30000);
+                p.setMinIdle(10);
+                p.setLogAbandoned(true);
+                p.setRemoveAbandoned(true);
+                DataSource datasource = new DataSource();
+                datasource.setPoolProperties(p); 
+                
+                Connection con = null;
+                try {            
+                  con = datasource.getConnection();
+                  Statement st = con.createStatement();
+                  ResultSet rs = st.executeQuery("select * from user");
+                  int cnt = 1;
+                  while (rs.next()) {
+                      System.out.println((cnt++)+". Host:" +rs.getString("Host")+" User:"+rs.getString("User")+" Password:"+rs.getString("Password"));
+                  }
+                  rs.close();
+                  st.close();
+                } finally {
+                  if (con!=null) try {con.close();}catch (Exception ignore) {}
+                }  
+            }
+        
+        }
+    </source>
+  </subsection>
+  <subsection name="As a Resource">
+    <p>And here is an example on how to configure a resource for JNDI lookups</p>
+    <source>
+    &lt;Resource name=&quot;jdbc/TestDB&quot; 
+              auth=&quot;Container&quot; 
+              type=&quot;javax.sql.DataSource&quot; 
+              factory=&quot;org.apache.tomcat.jdbc.pool.DataSourceFactory&quot;
+              testWhileIdle=&quot;true&quot;
+              testOnBorrow=&quot;true&quot;
+              testOnReturn=&quot;false&quot;
+              validationQuery=&quot;SELECT 1&quot;
+              validationInterval=&quot;30000&quot;
+              timeBetweenEvictionRunsMillis=&quot;30000&quot;
+              maxActive=&quot;100&quot; 
+              minIdle=&quot;10&quot; 
+              maxWait=&quot;10000&quot; 
+              initialSize=&quot;10&quot;
+              removeAbandonedTimeout=&quot;60&quot;
+              removeAbandoned=&quot;true&quot;
+              logAbandoned=&quot;true&quot;
+              minEvictableIdleTimeMillis=&quot;30000&quot; 
+              jmxEnabled=&quot;true&quot;
+              username=&quot;root&quot; 
+              password=&quot;password&quot; 
+              driverClassName=&quot;com.mysql.jdbc.Driver&quot;
+              url=&quot;jdbc:mysql://localhost:3306/mysql?autoReconnect=true&quot;/&gt;
+
+    
+    </source>
+  
+  </subsection>
+  
+</section>
+
+
 </body>
 
 </document>

diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/JdbcInterceptor.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/JdbcInterceptor.java
index b48bf04..21e26b8 100644 (file)
--- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/JdbcInterceptor.java
+++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/JdbcInterceptor.java
@@ -25,6 +25,7 @@ import java.lang.reflect.Method;
  */
 public abstract class JdbcInterceptor implements InvocationHandler {
     public  static final String CLOSE_VAL = "close";
+    public  static final String TOSTRING_VAL = "toString";
 
     private JdbcInterceptor next = null;
 

diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/PooledConnection.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/PooledConnection.java
index 27767dd..364eeee 100644 (file)
--- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/PooledConnection.java
+++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/PooledConnection.java
@@ -300,5 +300,9 @@ public class PooledConnection {
             this.handler = new WeakReference<JdbcInterceptor>(handler);
         }
     }
+    
+    public String toString() {
+        return "PooledConnection["+(connection!=null?connection.toString():"null")+"]";
+    }
 
 }

diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/ProxyConnection.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/ProxyConnection.java
index feba58f..5aa2cf2 100644 (file)
--- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/ProxyConnection.java
+++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/ProxyConnection.java
@@ -74,6 +74,8 @@ public class ProxyConnection extends JdbcInterceptor {
             this.connection = null;
             pool.returnConnection(poolc);
             return null;
+        } else if (TOSTRING_VAL==method.getName()) {
+            return this.toString();
         }
         return method.invoke(connection.getConnection(),args);
     }
@@ -89,5 +91,9 @@ public class ProxyConnection extends JdbcInterceptor {
     public ConnectionPool getParentPool() {
         return pool;
     }
+    
+    public String toString() {
+        return "ProxyConnection["+(connection!=null?connection.toString():"null")+"]";
+    }
 
 }

diff --git a/modules/jdbc-pool/test/org/apache/tomcat/jdbc/test/SimplePOJOExample.java b/modules/jdbc-pool/test/org/apache/tomcat/jdbc/test/SimplePOJOExample.java
new file mode 100644 (file)
index 0000000..6298407
--- /dev/null
+++ b/modules/jdbc-pool/test/org/apache/tomcat/jdbc/test/SimplePOJOExample.java
@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.tomcat.jdbc.test;
+
+import java.sql.Connection;
+import java.sql.ResultSet;
+import java.sql.Statement;
+
+import org.apache.tomcat.jdbc.pool.DataSource;
+import org.apache.tomcat.jdbc.pool.PoolProperties;
+
+public class SimplePOJOExample {
+
+    public static void main(String[] args) throws Exception {
+        PoolProperties p = new PoolProperties();
+        p.setUrl("jdbc:mysql://localhost:3306/mysql?autoReconnect=true");
+        p.setDriverClassName("com.mysql.jdbc.Driver");
+        p.setUsername("root");
+        p.setPassword("password");
+        p.setJmxEnabled(true);
+        p.setTestWhileIdle(false);
+        p.setTestOnBorrow(true);
+        p.setValidationQuery("SELECT 1");
+        p.setTestOnReturn(false);
+        p.setValidationInterval(30000);
+        p.setTimeBetweenEvictionRunsMillis(30000);
+        p.setMaxActive(100);
+        p.setInitialSize(10);
+        p.setMaxWait(10000);
+        p.setRemoveAbandonedTimeout(60);
+        p.setMinEvictableIdleTimeMillis(30000);
+        p.setMinIdle(10);
+        p.setLogAbandoned(true);
+        p.setRemoveAbandoned(true);
+        DataSource datasource = new DataSource();
+        datasource.setPoolProperties(p); 
+        
+        Connection con = null;
+        try {            
+          con = datasource.getConnection();
+          Statement st = con.createStatement();
+          ResultSet rs = st.executeQuery("select * from user");
+          int cnt = 1;
+          while (rs.next()) {
+              System.out.println((cnt++)+". Host:" +rs.getString("Host")+" User:"+rs.getString("User")+" Password:"+rs.getString("Password"));
+          }
+          rs.close();
+          st.close();
+        } finally {
+          if (con!=null) try {con.close();}catch (Exception ignore) {}
+        }  
+    }
+
+}