add more comments for PooledDataSource and eliminate magic number

Author: jasonleaster

src/main/java/org/apache/ibatis/datasource/pooled/PooledDataSource.java

@@ -50,6 +50,7 @@ public class PooledDataSource implements DataSource {
   protected int poolMaximumIdleConnections = 5;
   protected int poolMaximumCheckoutTime = 20000;
   protected int poolTimeToWait = 20000;
+  protected int poolMaximumLocalBadConnectionTolerance = 3;
   protected String poolPingQuery = "NO PING QUERY SET";
   protected boolean poolPingEnabled;
   protected int poolPingConnectionsNotUsedFor;
@@ -169,6 +170,18 @@ public void setPoolMaximumIdleConnections(int poolMaximumIdleConnections) {
     forceCloseAll();
   }
 
+  /*
+   * The maximum number of tolerance for bad connection happens in one thread
+    * which are applying for new {@link PooledConnection}
+   *
+   * @param poolMaximumLocalBadConnectionTolerance
+   * max tolerance for bad connection happens in one thread
+   */
+  public void setPoolMaximumLocalBadConnectionTolerance(
+      int poolMaximumLocalBadConnectionTolerance) {
+    this.poolMaximumLocalBadConnectionTolerance = poolMaximumLocalBadConnectionTolerance;
+  }
+
   /*
    * The maximum time a connection can be used before it *may* be
    * given away again.
@@ -257,6 +270,10 @@ public int getPoolMaximumIdleConnections() {
     return poolMaximumIdleConnections;
   }
 
+  public int getPoolMaximumLocalBadConnectionTolerance() {
+    return poolMaximumLocalBadConnectionTolerance;
+  }
+
   public int getPoolMaximumCheckoutTime() {
     return poolMaximumCheckoutTime;
   }
@@ -400,6 +417,14 @@ private PooledConnection popConnection(String username, String password) throws
                 try {
                   oldestActiveConnection.getRealConnection().rollback();
                 } catch (SQLException e) {
+                  /*
+                     Just log a message for debug and continue to execute the following
+                     statement like nothing happend.
+                     Wrap the bad connection with a new PooledConnection, this will help
+                     to not intterupt current executing thread and give current thread a
+                     chance to join the next competion for another valid/good database
+                     connection. At the end of this loop, bad {@link @conn} will be set as null.
+                   */
                   log.debug("Bad connection. Could not roll back");
                 }  
               }
@@ -430,6 +455,7 @@ private PooledConnection popConnection(String username, String password) throws
           }
         }
         if (conn != null) {
+          // ping to server and check the connection is valid or not
           if (conn.isValid()) {
             if (!conn.getRealConnection().getAutoCommit()) {
               conn.getRealConnection().rollback();
@@ -447,7 +473,7 @@ private PooledConnection popConnection(String username, String password) throws
             state.badConnectionCount++;
             localBadConnectionCount++;
             conn = null;
-            if (localBadConnectionCount > (poolMaximumIdleConnections + 3)) {
+            if (localBadConnectionCount > (poolMaximumIdleConnections + poolMaximumLocalBadConnectionTolerance)) {
               if (log.isDebugEnabled()) {
                 log.debug("PooledDataSource: Could not get a good connection to the database.");
               }