Merge pull request #1058 from jasonleaster/master

add more comments for PooledDataSource and eliminate magic number

Author: kazuki43zoo

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,20 @@ 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
+   *
+   * @since 3.4.5
+   */
+  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 +272,10 @@ public int getPoolMaximumIdleConnections() {
     return poolMaximumIdleConnections;
   }
 
+  public int getPoolMaximumLocalBadConnectionTolerance() {
+    return poolMaximumLocalBadConnectionTolerance;
+  }
+
   public int getPoolMaximumCheckoutTime() {
     return poolMaximumCheckoutTime;
   }
@@ -400,6 +419,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 +457,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 +475,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.");
               }

src/site/es/xdoc/configuration.xml

@@ -1650,6 +1650,14 @@ SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader,properti
           </li>
           <li><code>poolTimeToWait</code> – Este es un parámetro de bajo nivel que permite escribir un log y reintentar la adquisición de una conexión en caso de que no se haya conseguido la conexión transcurrido un tiempo razonable (esto evita que se produzcan fallos constantes y silenciosos si el pool está mal configurado). Por defecto:  20000ms (20 segundos)
           </li>
+          <li><code>poolMaximumLocalBadConnectionTolerance</code> – This is a low level setting about
+            tolerance of bad connections got for any thread. If a thread got a bad connection, it may
+            still have another chance to re-attempt to get another connection which is valid. But the
+            retrying times should not more than the sum of <code>poolMaximumIdleConnections</code>
+            and <code>poolMaximumLocalBadConnectionTolerance</code>.
+            Default:
+            3 (Since: 3.4.5)
+          </li>
           <li><code>poolPingQuery</code> – La query de ping (sondeo) que se envía a la base de datos para verificar que la conexión funciona correctamente y que está lista para aceptar nuevas peticiones de conexión. El valor por defecto es "NO PING QUERY SET", que hará que la mayoría de los drivers de base de datos devuelvan un error con un mensaje de error decente.
           </li>
           <li><code>poolPingEnabled</code> – Habilita o inhabilita la query de ping. Si está habilitada deberías informar también la propiedad poolPingQuery con una sentencia SQL (preferentemente una rápida).  Por defecto:  false.

src/site/ja/xdoc/configuration.xml

@@ -1752,6 +1752,14 @@ SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader,properti
           <li>poolTimeToWait – 接続の取得に長時間を要した場合にログを出力し、接続の再取得を試みる機会を与えるための低レベルの設定です（プールが誤って設定された場合、無限に待機状態となってしまうのを防ぐため）。
             デフォルト: 20000ms （20秒）
           </li>
+          <li><code>poolMaximumLocalBadConnectionTolerance</code> – This is a low level setting about
+            tolerance of bad connections got for any thread. If a thread got a bad connection, it may
+            still have another chance to re-attempt to get another connection which is valid. But the
+            retrying times should not more than the sum of <code>poolMaximumIdleConnections</code>
+            and <code>poolMaximumLocalBadConnectionTolerance</code>.
+            Default:
+            3 (Since: 3.4.5)
+          </li>
           <li>poolPingQuery – プールされた接続が正常で、リクエストを受け付けられる状態にあるかどうか確認するためにデータベースに送信される ping クエリを設定します。
             デフォルトは "NO PING QUERY SET" で、一般的なドライバーであれば問い合わせは失敗し、適切なエラーメッセージが出力されるはずです。
           </li>

src/site/ko/xdoc/configuration.xml

@@ -1614,6 +1614,14 @@ SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader,properti
 		  디폴트는 20000ms(20 초)</li>
           <li><code>poolTimeToWait</code> - 풀이 로그 상태를 출력하고 비정상적으로 긴 경우 커넥션을 다시 얻을려고 시도하는 로우 레벨 설정. 
 		  디폴트는 20000ms(20 초)</li>
+          <li><code>poolMaximumLocalBadConnectionTolerance</code> – This is a low level setting about
+            tolerance of bad connections got for any thread. If a thread got a bad connection, it may
+            still have another chance to re-attempt to get another connection which is valid. But the
+            retrying times should not more than the sum of <code>poolMaximumIdleConnections</code>
+            and <code>poolMaximumLocalBadConnectionTolerance</code>.
+            Default:
+            3 (Since: 3.4.5)
+          </li>
           <li><code>poolPingQuery</code> - 커넥션이 작업하기 좋은 상태이고 요청을 받아서 처리할 준비가 되었는지 체크하기 위해 데이터베이스에 던지는 핑쿼리(Ping Query). 
 		  디폴트는 “핑 쿼리가 없음” 이다. 
 		  이 설정은 대부분의 데이터베이스로 하여금 에러메시지를 보게 할수도 있다.</li>

src/site/xdoc/configuration.xml

@@ -1947,6 +1947,14 @@ SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, propert
             Default:
             20000ms (i.e. 20 seconds)
           </li>
+          <li><code>poolMaximumLocalBadConnectionTolerance</code> – This is a low level setting about
+            tolerance of bad connections got for any thread. If a thread got a bad connection, it may
+            still have another chance to re-attempt to get another connection which is valid. But the
+            retrying times should not more than the sum of <code>poolMaximumIdleConnections</code>
+            and <code>poolMaximumLocalBadConnectionTolerance</code>.
+            Default:
+            3 (Since: 3.4.5)
+          </li>
           <li><code>poolPingQuery</code> – The Ping Query is sent to the database to
             validate that a connection is in good working order and is ready
             to

src/site/zh/xdoc/configuration.xml

@@ -1639,6 +1639,11 @@ SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader,properti
           </li>
           <li><code>poolTimeToWait</code> – 这是一个底层设置，如果获取连接花费的相当长的时间，它会给连接池打印状态日志并重新尝试获取一个连接（避免在误配置的情况下一直安静的失败），默认值：20000 毫秒（即 20 秒）。
           </li>
+          <li><code>poolMaximumLocalBadConnectionTolerance</code> – 这是一个关于坏连接容忍度的底层设置，
+            作用于每一个尝试从缓存池获取连接的线程. 如果这个线程获取到的是一个坏的连接，那么这个数据源允许这
+            个线程尝试重新获取一个新的连接，但是这个重新尝试的次数不应该超过 <code>poolMaximumIdleConnections</code>
+            与 <code>poolMaximumLocalBadConnectionTolerance</code> 之和。 默认值：3 (Since: 3.4.5)
+          </li>
           <li><code>poolPingQuery</code> – 发送到数据库的侦测查询，用来检验连接是否处在正常工作秩序中并准备接受请求。默认是“NO PING QUERY SET”，这会导致多数数据库驱动失败时带有一个恰当的错误消息。
           </li>
           <li><code>poolPingEnabled</code> – 是否启用侦测查询。若开启，也必须使用一个可执行的 SQL 语句设置 <code>poolPingQuery</code> 属性（最好是一个非常快的 SQL），默认值：false。