From 062c6b8fe6f8c2648fb6ef7c0c35a0da680ad8fe Mon Sep 17 00:00:00 2001 From: "Erik C. Thauvin" Date: Wed, 17 Mar 2004 07:58:33 +0000 Subject: [PATCH] Javadoc first draft. --- .cvsignore | 3 +- build.properties | 5 + build.xml | 12 + src/net/java/dev/simplepool/SimplePool.java | 125 +++--- .../dev/simplepool/SimplePoolConnection.java | 367 ++++++++++++------ .../dev/simplepool/SimplePoolDataSource.java | 108 +++++- .../SimplePoolDataSourceFactory.java | 27 +- .../dev/simplepool/SimplePoolServlet.java | 68 ++-- src/net/java/dev/simplepool/package.html | 13 + 9 files changed, 482 insertions(+), 246 deletions(-) create mode 100644 src/net/java/dev/simplepool/package.html diff --git a/.cvsignore b/.cvsignore index 7a73f3b..754e821 100644 --- a/.cvsignore +++ b/.cvsignore @@ -4,4 +4,5 @@ bin dist build -classes \ No newline at end of file +classes +javadoc \ No newline at end of file diff --git a/build.properties b/build.properties index 9f05722..e2767e9 100644 --- a/build.properties +++ b/build.properties @@ -4,4 +4,9 @@ path.classes=build path.src=src path.dist=dist path.lib=lib +path.javadoc=javadoc +javadoc.title=SimplePool +javadoc.api.link=http://java.sun.com/j2se/1.4.2/docs/api +javadoc.servlet.link=http://java.sun.com/products/servlet/2.3/javadoc/ +javadoc.packages=net.java.dev.simplepool.* \ No newline at end of file diff --git a/build.xml b/build.xml index c790a3f..58a2be5 100644 --- a/build.xml +++ b/build.xml @@ -13,6 +13,7 @@ + @@ -27,10 +28,21 @@ + + + + + + + + + + + \ No newline at end of file diff --git a/src/net/java/dev/simplepool/SimplePool.java b/src/net/java/dev/simplepool/SimplePool.java index a2436ed..4891017 100644 --- a/src/net/java/dev/simplepool/SimplePool.java +++ b/src/net/java/dev/simplepool/SimplePool.java @@ -28,11 +28,11 @@ import java.text.SimpleDateFormat; import java.util.Date; /** - * SimplePool + * Creates and manages a pool of database connections. * - * @author Marc A. Mnich - * @author Russell Beattie - * @author Erik C. Thauvin + * @author Marc A. Mnich + * @author Russell Beattie + * @author Erik C. Thauvin * @version $Revision$, $Date$ * @since 1.0 */ @@ -64,18 +64,20 @@ public class SimplePool implements Runnable { /** - * Creates a new Connection Broker
- * driver: JDBC driver. e.g. 'oracle.jdbc.driver.OracleDriver'
- * jdbcUrl: JDBC connect string. e.g. 'jdbc:oracle:thin:@203.92.21.109:1526:orcl'
- * user: Database login name. e.g. 'Scott'
- * password: Database password. e.g. 'Tiger'
- * minConns: Minimum number of connections to start with.
- * maxConns: Maximum number of connections in dynamic pool.
- * maxConnTime: Time in days between connection resets. (Reset does a basic cleanup)
- * maxCheckoutSeconds: Max time a connection can be checked out before being recycled. Zero value turns option off, default is 60 seconds. + * Creates a new Connection Broker + * + * @param driver JDBC driver. e.g. 'oracle.jdbc.driver.OracleDriver' + * @param jdbcUrl JDBC connect string. e.g. 'jdbc:oracle:thin:@203.92.21.109:1526:orcl' + * @param user Database login name. e.g. 'Scott' + * @param password Database password. e.g. 'Tiger' + * @param minConns Minimum number of connections to start with. + * @param maxConns Maximum number of connections in dynamic pool. + * @param maxConnTime Time in days between connection resets. (Reset does a basic cleanup) + * @param maxCheckoutSeconds Max time a connection can be checked out before being recycled. Zero value turns option + * off, default is 60 seconds. */ public SimplePool(String driver, String jdbcUrl, String user, - String password, int minConns, int maxConns, double maxConnTime, int maxCheckoutSeconds) + String password, int minConns, int maxConns, double maxConnTime, int maxCheckoutSeconds) throws IOException { this.connPool = new Connection[maxConns]; @@ -109,9 +111,9 @@ public class SimplePool implements Runnable { // Initialize the pool of connections with the mininum connections: // Problems creating connections may be caused during reboot when the - // servlet is started before the database is ready. Handle this - // by waiting and trying again. The loop allows 5 minutes for - // db reboot. + // servlet is started before the database is ready. Handle this + // by waiting and trying again. The loop allows 5 minutes for + // db reboot. boolean connectionsSucceeded = false; int dbLoop = 20; @@ -154,12 +156,12 @@ public class SimplePool implements Runnable { /** - * Housekeeping thread. Runs in the background with low CPU overhead. - * Connections are checked for warnings and closure and are periodically - * restarted. - * This thread is a catchall for corrupted - * connections and prevents the buildup of open cursors. (Open cursors + * Housekeeping thread. Runs in the background with low CPU overhead. Connections are checked for warnings and + * closure and are periodically restarted. + *

+ * This thread is a catchall for corrupted connections and prevents the buildup of open cursors. (Open cursors * result when the application fails to close a Statement). + *

* This method acts as fault tolerance for bad connection/statement programming. */ public void run() { @@ -271,17 +273,13 @@ public class SimplePool implements Runnable { } // End run /** - * This method hands out the connections in round-robin order. - * This prevents a faulty connection from locking - * up an application entirely. A browser 'refresh' will - * get the next connection while the faulty - * connection is cleaned up by the housekeeping thread. + * This method hands out the connections in round-robin order. This prevents a faulty connection from locking up an + * application entirely. A browser 'refresh' will get the next connection while the faulty connection is cleaned up + * by the housekeeping thread. *

- * If the min number of threads are ever exhausted, new - * threads are added up the the max thread count. - * Finally, if all threads are in use, this method waits - * 2 seconds and tries again, up to ten times. After that, it - * returns a null. + * If the min number of threads are ever exhausted, new threads are added up the the max thread count. Finally, if + * all threads are in use, this method waits 2 seconds and tries again, up to ten times. After that, it returns a + * null. */ public Connection getConnection() { @@ -385,8 +383,7 @@ public class SimplePool implements Runnable { } /** - * Frees a connection. Replaces connection back into the main pool for - * reuse. + * Frees a connection. Replaces connection back into the main pool for reuse. */ public String freeConnection(Connection conn) { String res = ""; @@ -405,8 +402,7 @@ public class SimplePool implements Runnable { } /** - * Returns the age of a connection -- the time since it was handed out to - * an application. + * Returns the age of a connection -- the time since it was handed out to an application. */ public long getAge(Connection conn) { // Returns the age of the connection in millisec. int thisconn = idOfConnection(conn); @@ -435,31 +431,29 @@ public class SimplePool implements Runnable { log.debug("Opening connection [" + String.valueOf(i) + "]: " + connPool[i].toString()); } - - /** - * Shuts down the housekeeping thread and closes all connections - * in the pool. Call this method from the destroy() method of the servlet. - */ /** - * Multi-phase shutdown. having following sequence: - *

    - *
  1. getConnection() will refuse to return connections. - *
  2. The housekeeping thread is shut down.
    - * Up to the time of millis milliseconds after shutdown of - * the housekeeping thread, freeConnection() can still be - * called to return used connections. - *
  3. After millis milliseconds after the shutdown of the - * housekeeping thread, all connections in the pool are closed. - *
  4. If any connections were in use while being closed then a - * SQLException is thrown. - *
  5. The log is closed. - *

+ * Shuts down the housekeeping thread and closes all connections in the pool. Call this method from the destroy() + * method of the servlet. + *

+ * Multi-phase shutdown having following sequence: + *

+ *
    + *
  1. getConnection() will refuse to return connections.
    2. + *
  2. The housekeeping thread is shut down.
    + * Up to the time of millis milliseconds after shutdown of the housekeeping thread, + * freeConnection() can still be called to return used connections.
    + * After millis milliseconds after the shutdown of the housekeeping thread, all connections in the pool + * are closed.
    3. + *
  3. If any connections were in use while being closed then a SQLException is thrown.
    4. + *
  4. The log is closed.
    5. + *
+ *

* Call this method from a servlet destroy() method. * * @param millis the time to wait in milliseconds. - * @throws SQLException if connections were in use after - * millis. + * + * @throws SQLException if connections were in use after millis. */ public void destroy(int millis) throws SQLException { @@ -520,11 +514,10 @@ public class SimplePool implements Runnable { /** - * Less safe shutdown. Uses default timeout value. - * This method simply calls the destroy() method - * with a millis - * value of 10000 (10 seconds) and ignores SQLException - * thrown by that method. + * Less safe shutdown. Uses default timeout value. + *

+ * This method simply calls the destroy() method with a millis value of 10000 (10 seconds) + * and ignores SQLException thrown by that method. * * @see #destroy(int) */ @@ -539,13 +532,11 @@ public class SimplePool implements Runnable { /** * Returns the number of connections in use. + *

+ * This method could be reduced to return a counter that is maintained by all methods that update connStatus. + * However, it is more efficient to do it this way because: Updating the counter would put an additional burden on + * the most frequently used methods; in comparison, this method is rarely used (although essential). */ - // This method could be reduced to return a counter that is - // maintained by all methods that update connStatus. - // However, it is more efficient to do it this way because: - // Updating the counter would put an additional burden on the most - // frequently used methods; in comparison, this method is - // rarely used (although essential). public int getUseCount() { int useCount = 0; synchronized (connStatus) { diff --git a/src/net/java/dev/simplepool/SimplePoolConnection.java b/src/net/java/dev/simplepool/SimplePoolConnection.java index 42b620d..66ce9f4 100644 --- a/src/net/java/dev/simplepool/SimplePoolConnection.java +++ b/src/net/java/dev/simplepool/SimplePoolConnection.java @@ -1,276 +1,407 @@ /** - * $Source$ - * $Revision$ - * $Date$ - * - * Copyright (c) 2004, Russell Beattie (http://www.russellbeattie.com/) - * All rights reserved. - * - * Copyright (c) 2004, Erik C. Thauvin (http://www.thauvin.net/erik/) - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions are - * met: - * - * Redistributions of source code must retain the above copyright notice, - * this list of conditions and the following disclaimer. - * - * Redistributions in binary form must reproduce the above copyright notice, - * this list of conditions and the following disclaimer in the documentation - * and/or other materials provided with the distribution. - * - * Neither the name of the authors nor the names of its contributors may be - * used to endorse or promote products derived from this software without - * specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS - * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, - * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, - * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, - * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR - * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * $Source$ $Revision: 1.1 + * $ $Date$ Copyright (c) 2004, Russell Beattie (http://www.russellbeattie.com/) All rights + * reserved. Copyright (c) 2004, Erik C. Thauvin (http://www.thauvin.net/erik/) All rights reserved. Redistribution + * and use in source and binary forms, with or without modification, are permitted provided that the following + * conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions + * and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list + * of conditions and the following disclaimer in the documentation and/or other materials provided with the + * distribution. Neither the name of the authors nor the names of its contributors may be used to endorse or promote + * products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE + * COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, + * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL + * THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ package net.java.dev.simplepool; - import java.sql.*; import java.util.Map; + /** - * SimplePoolConnection + * Basic implementation of javax.sql.Connnection. * - * @author Russell Beattie - * @author Erik C. Thauvin + * @author Russell Beattie + * @author Erik C. Thauvin * @version $Revision$, $Date$ * @since 1.0 */ public class SimplePoolConnection implements Connection { - protected Connection conn; - protected SimplePool broker; + private Connection conn; + private SimplePool broker; + /** + * Creates a new SimplePoolConnection object. + * + * @param broker The connection pool. + */ public SimplePoolConnection(SimplePool broker) { this.broker = broker; conn = broker.getConnection(); } - public void setAutoCommit(boolean arg0) + /** + * See {@link java.sql.Connection#setAutoCommit(boolean)}. + * + * @see java.sql.Connection#setAutoCommit(boolean) + */ + public void setAutoCommit(boolean autoCommit) throws SQLException { - conn.setAutoCommit(arg0); + conn.setAutoCommit(autoCommit); } + /** + * See {@link java.sql.Connection#getAutoCommit}. + * + * @see java.sql.Connection#getAutoCommit + */ public boolean getAutoCommit() throws SQLException { return conn.getAutoCommit(); } - - public void setCatalog(String arg0) + /** + * See {@link java.sql.Connection#setCatalog(String)}. + * + * @see java.sql.Connection#setCatalog(String) + */ + public void setCatalog(String catalog) throws SQLException { - conn.setCatalog(arg0); + conn.setCatalog(catalog); } - + /** + * See {@link java.sql.Connection#getCatalog()}. + * + * @see java.sql.Connection#getCatalog() + */ public String getCatalog() throws SQLException { return conn.getCatalog(); } - + /** + * See {@link java.sql.Connection#isClosed}. + * + * @see java.sql.Connection#isClosed + */ public boolean isClosed() throws SQLException { return conn.isClosed(); } - - public void setHoldability(int arg0) + /** + * See {@link java.sql.Connection#setHoldability(int)}. + * + * @see java.sql.Connection#setHoldability(int) + */ + public void setHoldability(int holdability) throws SQLException { - conn.setHoldability(arg0); + conn.setHoldability(holdability); } - + /** + * See {@link java.sql.Connection#getHoldability}. + * + * @see java.sql.Connection#getHoldability + */ public int getHoldability() throws SQLException { return conn.getHoldability(); } - + /** + * See {@link java.sql.Connection#getMetaData}. + * + * @see java.sql.Connection#getMetaData + */ public DatabaseMetaData getMetaData() throws SQLException { return conn.getMetaData(); } - - public void setReadOnly(boolean arg0) + /** + * See {@link java.sql.Connection#setReadOnly(boolean)}. + * + * @see java.sql.Connection#setReadOnly(boolean) + */ + public void setReadOnly(boolean readOnly) throws SQLException { - conn.setReadOnly(arg0); + conn.setReadOnly(readOnly); } - + /** + * See {@link java.sql.Connection#isReadOnly}. + * + * @see java.sql.Connection#isReadOnly + */ public boolean isReadOnly() throws SQLException { return conn.isReadOnly(); } - + /** + * See {@link java.sql.Connection#setSavepoint}. + * + * @see java.sql.Connection#setSavepoint + */ public Savepoint setSavepoint() throws SQLException { return conn.setSavepoint(); } - - public Savepoint setSavepoint(String arg0) + /** + * See {@link java.sql.Connection#setSavepoint(String)}. + * + * @see java.sql.Connection#setSavepoint(String) + */ + public Savepoint setSavepoint(String savepoint) throws SQLException { - return conn.setSavepoint(arg0); + return conn.setSavepoint(savepoint); } - - public void setTransactionIsolation(int arg0) + /** + * See {@link java.sql.Connection#setTransactionIsolation(int)}. + * + * @see java.sql.Connection#setTransactionIsolation(int) + */ + public void setTransactionIsolation(int level) throws SQLException { - conn.setTransactionIsolation(arg0); + conn.setTransactionIsolation(level); } - + /** + * See {@link java.sql.Connection#getTransactionIsolation}. + * + * @see java.sql.Connection#getTransactionIsolation + */ public int getTransactionIsolation() throws SQLException { return conn.getTransactionIsolation(); } - - public void setTypeMap(Map arg0) + /** + * See {@link java.sql.Connection#setTypeMap(Map)}. + * + * @see java.sql.Connection#setTypeMap(Map) + */ + public void setTypeMap(Map map) throws SQLException { - conn.setTypeMap(arg0); + conn.setTypeMap(map); } - + /** + * See {@link java.sql.Connection#getTypeMap}. + * + * @see java.sql.Connection#getTypeMap + */ public Map getTypeMap() throws SQLException { return conn.getTypeMap(); } - + /** + * See {@link java.sql.Connection#getWarnings}. + * + * @see java.sql.Connection#getWarnings + */ public SQLWarning getWarnings() throws SQLException { return conn.getWarnings(); } - + /** + * See {@link java.sql.Connection#clearWarnings}. + * + * @see java.sql.Connection#clearWarnings + */ public void clearWarnings() throws SQLException { conn.clearWarnings(); } - + /** + * See {@link java.sql.Connection#close}. + * + * @see java.sql.Connection#close + */ public void close() throws SQLException { broker.freeConnection(conn); } - + /** + * See {@link java.sql.Connection#commit}. + * + * @see java.sql.Connection#commit + */ public void commit() throws SQLException { conn.commit(); } - + /** + * See {@link java.sql.Connection#createStatement}. + * + * @see java.sql.Connection#createStatement + */ public Statement createStatement() throws SQLException { return conn.createStatement(); } - - public Statement createStatement(int arg0, int arg1) + /** + * See {@link java.sql.Connection#createStatement(int, int)}. + * + * @see java.sql.Connection#createStatement(int, int) + */ + public Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException { - return conn.createStatement(arg0, arg1); + return conn.createStatement(resultSetType, resultSetConcurrency); } - - public Statement createStatement(int arg0, int arg1, int arg2) + /** + * See {@link java.sql.Connection#createStatement(int, int, int)}. + * + * @see java.sql.Connection#createStatement(int, int, int) + */ + public Statement createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException { - return conn.createStatement(arg0, arg1, arg2); + return conn.createStatement(resultSetType, resultSetConcurrency, resultSetHoldability); } - - public String nativeSQL(String arg0) + /** + * See {@link java.sql.Connection#nativeSQL(String)}. + * + * @see java.sql.Connection#nativeSQL(String) + */ + public String nativeSQL(String sql) throws SQLException { - return conn.nativeSQL(arg0); + return conn.nativeSQL(sql); } - - public CallableStatement prepareCall(String arg0) + /** + * See {@link java.sql.Connection#prepareCall(String)}. + * + * @see java.sql.Connection#prepareCall(String) + */ + public CallableStatement prepareCall(String sql) throws SQLException { - return conn.prepareCall(arg0); + return conn.prepareCall(sql); } - - public CallableStatement prepareCall(String arg0, int arg1, int arg2) + /** + * See {@link java.sql.Connection#prepareCall(String, int, int)}. + * + * @see java.sql.Connection#prepareCall(String, int, int) + */ + public CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency) throws SQLException { - return conn.prepareCall(arg0, arg1, arg2); + return conn.prepareCall(sql, resultSetType, resultSetConcurrency); } - - public CallableStatement prepareCall(String arg0, int arg1, int arg2, int arg3) + /** + * See {@link java.sql.Connection#prepareCall(String, int, int, int)}. + * + * @see java.sql.Connection#prepareCall(String, int, int, int) + */ + public CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException { - return conn.prepareCall(arg0, arg1, arg2, arg3); + return conn.prepareCall(sql, resultSetType, resultSetConcurrency, resultSetHoldability); } - - public PreparedStatement prepareStatement(String arg0) + /** + * See {@link java.sql.Connection#prepareStatement(String)}. + * + * @see java.sql.Connection#prepareStatement(String) + */ + public PreparedStatement prepareStatement(String sql) throws SQLException { - return conn.prepareStatement(arg0); + return conn.prepareStatement(sql); } - - public PreparedStatement prepareStatement(String arg0, int arg1) + /** + * See {@link java.sql.Connection#prepareStatement(String)}. + * + * @see java.sql.Connection#prepareStatement(String) + */ + public PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) throws SQLException { - return conn.prepareStatement(arg0); + return conn.prepareStatement(sql); } - - public PreparedStatement prepareStatement(String arg0, int arg1, int arg2) + /** + * See {@link java.sql.Connection#prepareStatement(String, int, int)}. + * + * @see java.sql.Connection#prepareStatement(String, int, int) + */ + public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) throws SQLException { - return conn.prepareStatement(arg0, arg1, arg2); + return conn.prepareStatement(sql, resultSetType, resultSetConcurrency); } - - public PreparedStatement prepareStatement(String arg0, int arg1, int arg2, int arg3) + /** + * See {@link java.sql.Connection#prepareStatement(String, int, int, int)}. + * + * @see java.sql.Connection#prepareStatement(String, int, int, int) + */ + public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException { - return conn.prepareStatement(arg0, arg1, arg2, arg3); + return conn.prepareStatement(sql, resultSetType, resultSetConcurrency, resultSetHoldability); } - - public PreparedStatement prepareStatement(String arg0, int[] arg1) + /** + * See {@link java.sql.Connection#prepareStatement(String, int[])}. + * + * @see java.sql.Connection#prepareStatement(String, int[]) + */ + public PreparedStatement prepareStatement(String sql, int[] columnIndexes) throws SQLException { - return conn.prepareStatement(arg0, arg1); + return conn.prepareStatement(sql, columnIndexes); } - - public PreparedStatement prepareStatement(String arg0, String[] arg1) + /** + * See {@link java.sql.Connection#prepareStatement(String, String[])}. + * + * @see java.sql.Connection#prepareStatement(String, String[]) + */ + public PreparedStatement prepareStatement(String sql, String[] columnNames) throws SQLException { - return conn.prepareStatement(arg0, arg1); + return conn.prepareStatement(sql, columnNames); } - - public void releaseSavepoint(Savepoint arg0) + /** + * See {@link java.sql.Connection#releaseSavepoint(Savepoint)}. + * + * @see java.sql.Connection#releaseSavepoint(Savepoint) + */ + public void releaseSavepoint(Savepoint savepoint) throws SQLException { - conn.releaseSavepoint(arg0); + conn.releaseSavepoint(savepoint); } - + /** + * See {@link java.sql.Connection#rollback}. + * + * @see java.sql.Connection#rollback + */ public void rollback() throws SQLException { conn.rollback(); } - - public void rollback(Savepoint arg0) + /** + * See {@link java.sql.Connection#rollback(Savepoint)}. + * + * @see java.sql.Connection#rollback(Savepoint) + */ + public void rollback(Savepoint savepoint) throws SQLException { - conn.rollback(arg0); + conn.rollback(savepoint); } } diff --git a/src/net/java/dev/simplepool/SimplePoolDataSource.java b/src/net/java/dev/simplepool/SimplePoolDataSource.java index 541dcd6..0d61f8f 100644 --- a/src/net/java/dev/simplepool/SimplePoolDataSource.java +++ b/src/net/java/dev/simplepool/SimplePoolDataSource.java @@ -44,17 +44,16 @@ import java.sql.Connection; import java.sql.SQLException; /** - * SimplePoolDataSource + * Basic implementation of javax.sql.DataSource. * - * @author Russell Beattie - * @author Erik C. Thauvin + * @author Russell Beattie + * @author Erik C. Thauvin * @version $Revision$, $Date$ * @since 1.0 */ public class SimplePoolDataSource implements DataSource { protected PrintWriter logWriter = new PrintWriter(System.out); - protected SimplePool broker = null; private String driver = ""; @@ -66,11 +65,12 @@ public class SimplePoolDataSource implements DataSource { private String maxConnTime = ""; private String maxCheckoutSeconds = ""; - public SimplePoolDataSource() { - ; - } - - public void init() throws Exception { + /** + * Initializes the connection pool. + * + * @throws Exception if the pool could not be intialized. + */ + protected void init() throws Exception { broker = new SimplePool(driver, jdbcUrl, user, password, Integer.parseInt(minConns), Integer.parseInt(maxConns), @@ -78,6 +78,11 @@ public class SimplePoolDataSource implements DataSource { } + /** + * See {@link javax.sql.DataSource#getConnection()}. + * + * @see javax.sql.DataSource#getConnection() + */ public Connection getConnection() throws SQLException { if (broker == null) { @@ -92,96 +97,169 @@ public class SimplePoolDataSource implements DataSource { } - public Connection getConnection(String user, String password) + /** + * See {@link javax.sql.DataSource#getConnection(String, String)}. + * + * @see javax.sql.DataSource#getConnection(String, String) + */ + public Connection getConnection(String username, String password) throws SQLException { throw new SQLException("Not supported in this DataSource."); } - public void setLogWriter(PrintWriter output) throws SQLException { - logWriter = output; + /** + * See {@link javax.sql.DataSource#setLogWriter(PrintWriter)}. + * + * @see javax.sql.DataSource#setLogWriter(PrintWriter) + */ + public void setLogWriter(PrintWriter out) throws SQLException { + logWriter = out; } + /** + * See {@link javax.sql.DataSource#getLogWriter}. + * + * @see javax.sql.DataSource#getLogWriter + */ public PrintWriter getLogWriter() { return logWriter; } + /** + * See {@link javax.sql.DataSource#setLoginTimeout(int)}. + * + * @see javax.sql.DataSource#setLoginTimeout(int) + */ public void setLoginTimeout(int seconds) throws SQLException { } + /** + * See {@link javax.sql.DataSource#getLoginTimeout}. + * + * @see javax.sql.DataSource#getLoginTimeout + */ public int getLoginTimeout() { return 0; } + /** + * Closes the connection pool. + */ public void close() { broker.destroy(); broker = null; } - -// GET/SETs - + /** + * Sets the JDBC driver. + */ public void setDriver(String val) { driver = val; } + /** + * Gets the JDBC driver. + */ public String getDriver() { return driver; } + /** + * Sets the JDBC connect string. + */ public void setJdbcUrl(String val) { jdbcUrl = val; } + /** + * Sets the JDBC connect string. + */ public String getJdbcUrl() { return jdbcUrl; } + /** + * Sets the database login name. + */ public void setUser(String val) { user = val; } + /** + * Gets the database login name. + */ public String getUser() { return user; } + /** + * Sets the database password. + */ public void setPassword(String val) { password = val; } + /** + * Gets the database password. + */ public String getPassword() { return password; } + /** + * Sets the minimum number of connections to start with. + */ public void setMinConns(String val) { minConns = val; } + /** + * Gets the minimum number of connections to start with. + */ public String getMinConns() { return minConns; } + /** + * Sets the maximum number of connections in dynamic pool. + */ public void setMaxConns(String val) { maxConns = val; } + /** + * Gets the maximum number of connections in dynamic pool. + */ public String getMaxConns() { return maxConns; } + /** + * Sets the time in days between connection resets. + */ public void setMaxConnTime(String val) { maxConnTime = val; } + /** + * Gets the time in days between connection resets. + */ public String getMaxConnTime() { return maxConnTime; } + /** + * Sets the max time a connection can be checked out before being recycled. + */ public void setMaxCheckoutSeconds(String val) { maxCheckoutSeconds = val; } + /** + * Sets the max time a connection can be checked out before being recycled. + */ public String getMaxCheckoutSeconds() { return maxCheckoutSeconds; } diff --git a/src/net/java/dev/simplepool/SimplePoolDataSourceFactory.java b/src/net/java/dev/simplepool/SimplePoolDataSourceFactory.java index 7ca1b2a..070d373 100644 --- a/src/net/java/dev/simplepool/SimplePoolDataSourceFactory.java +++ b/src/net/java/dev/simplepool/SimplePoolDataSourceFactory.java @@ -45,15 +45,29 @@ import javax.naming.spi.ObjectFactory; import java.util.Hashtable; /** - * SimplePoolDataSourceFactory + * JNDI object factory that creates an instance of {@link SimplePoolDataSource}. * - * @author Russell Beattie - * @author Erik C. Thauvin + * @author Russell Beattie + * @author Erik C. Thauvin * @version $Revision$, $Date$ * @since 1.0 */ public class SimplePoolDataSourceFactory implements ObjectFactory { - + /** + * Creates a SimplePool DataSource factory. + * + * @param obj The object containing location or reference information that is used in creating the + * DataSource. + * @param name The name of this object relative to ctx, or null if no name is specified. + * @param ctx The context relative to which the name parameter is specified, or null if + * name is relative to the default initial context. + * @param env The possibly null environment that is used in creating the DataSource. + * + * @return The DataSource; null if it cannot be created. + * + * @throws Exception if the factory encountered an exception while attempting to create the DataSource, + * and no other object factories are to be tried. + */ public Object getObjectInstance(Object obj, Name name, Context ctx, Hashtable env) throws Exception { @@ -62,13 +76,14 @@ public class SimplePoolDataSourceFactory implements ObjectFactory { /* driver: JDBC driver. e.g. 'oracle.jdbc.driver.OracleDriver'
- jdbcUrl: JDBC connect string. e.g. 'jdbc:oracle:thin:@203.92.21.109:1526:orcl'
+ jdbcUrl: JDBC connect string. e.g. 'jdbc:oracle:thin:@203.92.21.109:1526:orcl'
user: Database login name. e.g. 'Scott'
password: Database password. e.g. 'Tiger'
minConns: Minimum number of connections to start with.
maxConns: Maximum number of connections in dynamic pool.
maxConnTime: Time in days between connection resets. (Reset does a basic cleanup)
- maxCheckoutSeconds: Max time a connection can be checked out before being recycled. Zero value turns option off, default is 60 seconds. + maxCheckoutSeconds: Max time a connection can be checked out before being recycled. Zero value turns option + off, default is 60 seconds. */ String driver = (String) ref.get("driver").getContent(); diff --git a/src/net/java/dev/simplepool/SimplePoolServlet.java b/src/net/java/dev/simplepool/SimplePoolServlet.java index 25a10e4..d122799 100644 --- a/src/net/java/dev/simplepool/SimplePoolServlet.java +++ b/src/net/java/dev/simplepool/SimplePoolServlet.java @@ -1,40 +1,20 @@ /** - * $Source$ - * $Revision$ - * $Date$ - * - * Copyright (c) 2004, Russell Beattie (http://www.russellbeattie.com/) - * All rights reserved. - * - * Copyright (c) 2004, Erik C. Thauvin (http://www.thauvin.net/erik/) - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions are - * met: - * - * Redistributions of source code must retain the above copyright notice, - * this list of conditions and the following disclaimer. - * - * Redistributions in binary form must reproduce the above copyright notice, - * this list of conditions and the following disclaimer in the documentation - * and/or other materials provided with the distribution. - * - * Neither the name of the authors nor the names of its contributors may be - * used to endorse or promote products derived from this software without - * specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS - * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, - * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, - * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, - * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR - * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * $Source$ $Revision$ + * $Date$ Copyright (c) 2004, Russell Beattie (http://www.russellbeattie.com/) All rights + * reserved. Copyright (c) 2004, Erik C. Thauvin (http://www.thauvin.net/erik/) All rights reserved. Redistribution + * and use in source and binary forms, with or without modification, are permitted provided that the following + * conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions + * and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list + * of conditions and the following disclaimer in the documentation and/or other materials provided with the + * distribution. Neither the name of the authors nor the names of its contributors may be used to endorse or promote + * products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE + * COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, + * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL + * THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ package net.java.dev.simplepool; @@ -47,10 +27,10 @@ import javax.servlet.http.HttpServlet; /** - * SimplePoolServlet + * Creates a pool of database connection based on the specific intialization parameters. * - * @author Russell Beattie - * @author Erik C. Thauvin + * @author Russell Beattie + * @author Erik C. Thauvin * @version $Revision$, $Date$ * @since 1.0 */ @@ -59,12 +39,22 @@ public class SimplePoolServlet extends HttpServlet { private static final Log log = LogFactory.getLog(SimplePoolServlet.class); private static SimplePoolDataSource dataSource; + /** + * Closes the connection pool. + * + * @see javax.servlet.http.HttpServlet#destroy + */ public void destroy() { if (dataSource != null) { dataSource.close(); } } + /** + * Initializes the connection pool. + * + * @see javax.servlet.http.HttpServlet#init(ServletConfig) + */ public void init(ServletConfig servletConfig) throws ServletException { log.info("Initializing " + servletConfig.getServletName() + " Servlet"); diff --git a/src/net/java/dev/simplepool/package.html b/src/net/java/dev/simplepool/package.html new file mode 100644 index 0000000..d7a1c29 --- /dev/null +++ b/src/net/java/dev/simplepool/package.html @@ -0,0 +1,13 @@ + + + + SimplePool + + +This package contains a simple database connection pool implementation for web applications, specifically those using JSTL. +

+The connection pool can be accessed via JNDI or through the {@link net.java.dev.simplepool.SimplePoolServlet}. + +@since 1.0 + +