Home » commons-dbcp-1.4-src » org.apache.commons » dbcp » [javadoc | source]
org.apache.commons.dbcp
public class: BasicDataSource [javadoc | source]
java.lang.Object
   org.apache.commons.dbcp.BasicDataSource

All Implemented Interfaces:
    DataSource

Direct Known Subclasses:
    BasicManagedDataSource

Basic implementation of javax.sql.DataSource that is configured via JavaBeans properties. This is not the only way to combine the commons-dbcp and commons-pool packages, but provides a "one stop shopping" solution for basic requirements.

Users extending this class should take care to use appropriate accessors rather than accessing protected fields directly to ensure thread-safety.

Field Summary
protected volatile  boolean defaultAutoCommit    The default auto-commit state of connections created by this pool. 
protected transient  Boolean defaultReadOnly    The default read-only state of connections created by this pool. 
protected volatile  int defaultTransactionIsolation    The default TransactionIsolation state of connections created by this pool. 
protected volatile  String defaultCatalog    The default "catalog" of connections created by this pool. 
protected  String driverClassName    The fully qualified Java class name of the JDBC driver to be used. 
protected  ClassLoader driverClassLoader    The class loader instance to use to load the JDBC driver. If not specified, Class#forName(String) is used to load the JDBC driver. If specified, Class#forName(String, boolean, ClassLoader) is used. 
protected  int maxActive    The maximum number of active connections that can be allocated from this pool at the same time, or negative for no limit. 
protected  int maxIdle    The maximum number of connections that can remain idle in the pool, without extra ones being released, or negative for no limit. If maxIdle is set too low on heavily loaded systems it is possible you will see connections being closed and almost immediately new connections being opened. This is a result of the active threads momentarily closing connections faster than they are opening them, causing the number of idle connections to rise above maxIdle. The best value for maxIdle for heavily loaded system will vary but the default is a good starting point. 
protected  int minIdle    The minimum number of active connections that can remain idle in the pool, without extra ones being created, or 0 to create none. 
protected  int initialSize    The initial number of connections that are created when the pool is started.
    since: 1.2 -
 
protected  long maxWait    The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or <= 0 to wait indefinitely. 
protected  boolean poolPreparedStatements    Prepared statement pooling for this pool. When this property is set to true both PreparedStatements and CallableStatements are pooled. 
protected  int maxOpenPreparedStatements   

The maximum number of open statements that can be allocated from the statement pool at the same time, or non-positive for no limit. Since a connection usually only uses one or two statements at a time, this is mostly used to help detect resource leaks.

Note: As of version 1.3, CallableStatements (those produced by Connection#prepareCall ) are pooled along with PreparedStatements (produced by Connection#prepareStatement ) and maxOpenPreparedStatements limits the total number of prepared or callable statements that may be in use at a given time.

 
protected  boolean testOnBorrow    The indication of whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another. 
protected  boolean testOnReturn    The indication of whether objects will be validated before being returned to the pool. 
protected  long timeBetweenEvictionRunsMillis    The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run. 
protected  int numTestsPerEvictionRun    The number of objects to examine during each run of the idle object evictor thread (if any). 
protected  long minEvictableIdleTimeMillis    The minimum amount of time an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any). 
protected  boolean testWhileIdle    The indication of whether objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool. 
protected volatile  String password    The connection password to be passed to our JDBC driver to establish a connection. 
protected  String url    The connection URL to be passed to our JDBC driver to establish a connection. 
protected  String username    The connection username to be passed to our JDBC driver to establish a connection. 
protected volatile  String validationQuery    The SQL query that will be used to validate connections from this pool before returning them to the caller. If specified, this query MUST be an SQL SELECT statement that returns at least one row. 
protected volatile  int validationQueryTimeout    Timeout in seconds before connection validation queries fail.
    since: 1.3 -
 
protected volatile  List connectionInitSqls    These SQL statements run once after a Connection is created.

This property can be used for example to run ALTER SESSION SET NLS_SORT=XCYECH in an Oracle Database only once after connection creation.

    since: 1.3 -
 
protected volatile  GenericObjectPool connectionPool    The object pool that internally manages our connections. 
protected  Properties connectionProperties    The connection properties that will be sent to our JDBC driver when establishing new connections. NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here. 
protected volatile  DataSource dataSource    The data source we will use to manage connections. This object should be acquired ONLY by calls to the createDataSource() method. 
protected  PrintWriter logWriter    The PrintWriter to which log messages should be directed. 
protected  boolean closed     
Method from org.apache.commons.dbcp.BasicDataSource Summary:
addConnectionProperty,   close,   createConnectionFactory,   createConnectionPool,   createDataSource,   createDataSourceInstance,   createPoolableConnectionFactory,   getConnection,   getConnection,   getConnectionInitSqls,   getDefaultAutoCommit,   getDefaultCatalog,   getDefaultReadOnly,   getDefaultTransactionIsolation,   getDriverClassLoader,   getDriverClassName,   getInitialSize,   getLogAbandoned,   getLogWriter,   getLoginTimeout,   getMaxActive,   getMaxIdle,   getMaxOpenPreparedStatements,   getMaxWait,   getMinEvictableIdleTimeMillis,   getMinIdle,   getNumActive,   getNumIdle,   getNumTestsPerEvictionRun,   getPassword,   getRemoveAbandoned,   getRemoveAbandonedTimeout,   getTestOnBorrow,   getTestOnReturn,   getTestWhileIdle,   getTimeBetweenEvictionRunsMillis,   getUrl,   getUsername,   getValidationQuery,   getValidationQueryTimeout,   isAccessToUnderlyingConnectionAllowed,   isClosed,   isPoolPreparedStatements,   isWrapperFor,   log,   removeConnectionProperty,   setAccessToUnderlyingConnectionAllowed,   setConnectionInitSqls,   setConnectionProperties,   setDefaultAutoCommit,   setDefaultCatalog,   setDefaultReadOnly,   setDefaultTransactionIsolation,   setDriverClassLoader,   setDriverClassName,   setInitialSize,   setLogAbandoned,   setLogWriter,   setLoginTimeout,   setMaxActive,   setMaxIdle,   setMaxOpenPreparedStatements,   setMaxWait,   setMinEvictableIdleTimeMillis,   setMinIdle,   setNumTestsPerEvictionRun,   setPassword,   setPoolPreparedStatements,   setRemoveAbandoned,   setRemoveAbandonedTimeout,   setTestOnBorrow,   setTestOnReturn,   setTestWhileIdle,   setTimeBetweenEvictionRunsMillis,   setUrl,   setUsername,   setValidationQuery,   setValidationQueryTimeout,   unwrap,   validateConnectionFactory
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.apache.commons.dbcp.BasicDataSource Detail:
 public  void addConnectionProperty(String name,
    String value) 
    Add a custom connection property to the set that will be passed to our JDBC driver. This MUST be called before the first connection is retrieved (along with all the other configuration property setters). Calls to this method after the connection pool has been initialized have no effect.
 public synchronized  void close() throws SQLException 

    Closes and releases all idle connections that are currently stored in the connection pool associated with this data source.

    Connections that are checked out to clients when this method is invoked are not affected. When client applications subsequently invoke Connection#close() to return these connections to the pool, the underlying JDBC connections are closed.

    Attempts to acquire connections using #getConnection() after this method has been invoked result in SQLExceptions.

    This method is idempotent - i.e., closing an already closed BasicDataSource has no effect and does not generate exceptions.

 protected ConnectionFactory createConnectionFactory() throws SQLException 
    Creates a JDBC connection factory for this datasource. This method only exists so subclasses can replace the implementation class.
 protected  void createConnectionPool() 
    Creates a connection pool for this datasource. This method only exists so subclasses can replace the implementation class.
 protected synchronized DataSource createDataSource() throws SQLException 

    Create (if necessary) and return the internal data source we are using to manage our connections.

    IMPLEMENTATION NOTE - It is tempting to use the "double checked locking" idiom in an attempt to avoid synchronizing on every single call to this method. However, this idiom fails to work correctly in the face of some optimizations that are legal for a JVM to perform.

 protected  void createDataSourceInstance() throws SQLException 
    Creates the actual data source instance. This method only exists so subclasses can replace the implementation class.
 protected  void createPoolableConnectionFactory(ConnectionFactory driverConnectionFactory,
    KeyedObjectPoolFactory statementPoolFactory,
    AbandonedConfig configuration) throws SQLException 
    Creates the PoolableConnectionFactory and attaches it to the connection pool. This method only exists so subclasses can replace the default implementation.
 public Connection getConnection() throws SQLException 
    Create (if necessary) and return a connection to the database.
 public Connection getConnection(String user,
    String pass) throws SQLException 
    BasicDataSource does NOT support this method.
 public Collection getConnectionInitSqls() 
    Returns the list of SQL statements executed when a physical connection is first created. Returns an empty list if there are no initialization statements configured.
 public boolean getDefaultAutoCommit() 
    Returns the default auto-commit property.
 public String getDefaultCatalog() 
    Returns the default catalog.
 public boolean getDefaultReadOnly() 
    Returns the default readOnly property.
 public int getDefaultTransactionIsolation() 
    Returns the default transaction isolation state of returned connections.
 public synchronized ClassLoader getDriverClassLoader() 
    Returns the class loader specified for loading the JDBC driver. Returns null if no class loader has been explicitly specified.
 public synchronized String getDriverClassName() 
    Returns the jdbc driver class name.
 public synchronized int getInitialSize() 
    Returns the initial size of the connection pool.
 public boolean getLogAbandoned() 

    Flag to log stack traces for application code which abandoned a Statement or Connection.

    Defaults to false.

    Logging of abandoned Statements and Connections adds overhead for every Connection open or new Statement because a stack trace has to be generated.

 public PrintWriter getLogWriter() throws SQLException 

    Returns the log writer being used by this data source.

    Calls #createDataSource() , so has the side effect of initializing the connection pool.

 public int getLoginTimeout() throws SQLException 
    BasicDataSource does NOT support this method.

    Returns the login timeout (in seconds) for connecting to the database.

    Calls #createDataSource() , so has the side effect of initializing the connection pool.

 public synchronized int getMaxActive() 

    Returns the maximum number of active connections that can be allocated at the same time.

    A negative number means that there is no limit.

 public synchronized int getMaxIdle() 

    Returns the maximum number of connections that can remain idle in the pool.

    A negative value indicates that there is no limit

 public synchronized int getMaxOpenPreparedStatements() 
 public synchronized long getMaxWait() 

    Returns the maximum number of milliseconds that the pool will wait for a connection to be returned before throwing an exception.

    A value less than or equal to zero means the pool is set to wait indefinitely.

 public synchronized long getMinEvictableIdleTimeMillis() 
 public synchronized int getMinIdle() 
    Returns the minimum number of idle connections in the pool
 public synchronized int getNumActive() 
    [Read Only] The current number of active connections that have been allocated from this data source.
 public synchronized int getNumIdle() 
    [Read Only] The current number of idle connections that are waiting to be allocated from this data source.
 public synchronized int getNumTestsPerEvictionRun() 
 public String getPassword() 
    Returns the password passed to the JDBC driver to establish connections.
 public boolean getRemoveAbandoned() 
    Flag to remove abandoned connections if they exceed the removeAbandonedTimout. Set to true or false, default false. If set to true a connection is considered abandoned and eligible for removal if it has been idle longer than the removeAbandonedTimeout. Setting this to true can recover db connections from poorly written applications which fail to close a connection.

    Abandonded connections are identified and removed when #getConnection() is invoked and the following conditions hold

 public int getRemoveAbandonedTimeout() 
    Timeout in seconds before an abandoned connection can be removed. Defaults to 300 seconds.
 public synchronized boolean getTestOnBorrow() 
 public synchronized boolean getTestOnReturn() 
 public synchronized boolean getTestWhileIdle() 
 public synchronized long getTimeBetweenEvictionRunsMillis() 
 public synchronized String getUrl() 
    Returns the JDBC connection #url property.
 public String getUsername() 
    Returns the JDBC connection #username property.
 public String getValidationQuery() 
    Returns the validation query used to validate connections before returning them.
 public int getValidationQueryTimeout() 
    Returns the validation query timeout.
 public synchronized boolean isAccessToUnderlyingConnectionAllowed() 
    Returns the value of the accessToUnderlyingConnectionAllowed property.
 public synchronized boolean isClosed() 
    If true, this data source is closed and no more connections can be retrieved from this datasource.
 public synchronized boolean isPoolPreparedStatements() 
    Returns true if we are pooling statements.
 public boolean isWrapperFor(Class<?> iface) throws SQLException 
 protected  void log(String message) 
 public  void removeConnectionProperty(String name) 
    Remove a custom connection property.
 public synchronized  void setAccessToUnderlyingConnectionAllowed(boolean allow) 

    Sets the value of the accessToUnderlyingConnectionAllowed property. It controls if the PoolGuard allows access to the underlying connection. (Default: false)

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setConnectionInitSqls(Collection connectionInitSqls) 
    Sets the list of SQL statements to be executed when a physical connection is first created.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setConnectionProperties(String connectionProperties) 
    Sets the connection properties passed to driver.connect(...). Format of the string must be [propertyName=property;]* NOTE - The "user" and "password" properties will be added explicitly, so they do not need to be included here.
 public  void setDefaultAutoCommit(boolean defaultAutoCommit) 

    Sets default auto-commit state of connections returned by this datasource.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setDefaultCatalog(String defaultCatalog) 

    Sets the default catalog.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setDefaultReadOnly(boolean defaultReadOnly) 

    Sets defaultReadonly property.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setDefaultTransactionIsolation(int defaultTransactionIsolation) 

    Sets the default transaction isolation state for returned connections.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setDriverClassLoader(ClassLoader driverClassLoader) 

    Sets the class loader to be used to load the JDBC driver.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setDriverClassName(String driverClassName) 

    Sets the jdbc driver class name.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setInitialSize(int initialSize) 

    Sets the initial size of the connection pool.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setLogAbandoned(boolean logAbandoned) 
 public  void setLogWriter(PrintWriter logWriter) throws SQLException 

    Sets the log writer being used by this data source.

    Calls #createDataSource() , so has the side effect of initializing the connection pool.

 public  void setLoginTimeout(int loginTimeout) throws SQLException 
    BasicDataSource does NOT support this method.

    Set the login timeout (in seconds) for connecting to the database.

    Calls #createDataSource() , so has the side effect of initializing the connection pool.

 public synchronized  void setMaxActive(int maxActive) 
    Sets the maximum number of active connections that can be allocated at the same time. Use a negative value for no limit.
 public synchronized  void setMaxIdle(int maxIdle) 
    Sets the maximum number of connections that can remain idle in the pool.
 public synchronized  void setMaxOpenPreparedStatements(int maxOpenStatements) 

    Sets the value of the #maxOpenPreparedStatements property.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setMaxWait(long maxWait) 

    Sets the maxWait property.

    Use -1 to make the pool wait indefinitely.

 public synchronized  void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis) 
 public synchronized  void setMinIdle(int minIdle) 
    Sets the minimum number of idle connections in the pool.
 public synchronized  void setNumTestsPerEvictionRun(int numTestsPerEvictionRun) 
 public  void setPassword(String password) 

    Sets the #password .

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public synchronized  void setPoolPreparedStatements(boolean poolingStatements) 

    Sets whether to pool statements or not.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setRemoveAbandoned(boolean removeAbandoned) 
 public  void setRemoveAbandonedTimeout(int removeAbandonedTimeout) 
 public synchronized  void setTestOnBorrow(boolean testOnBorrow) 
    Sets the #testOnBorrow property. This property determines whether or not the pool will validate objects before they are borrowed from the pool. For a true value to have any effect, the validationQuery property must be set to a non-null string.
 public synchronized  void setTestOnReturn(boolean testOnReturn) 
    Sets the testOnReturn property. This property determines whether or not the pool will validate objects before they are returned to the pool. For a true value to have any effect, the validationQuery property must be set to a non-null string.
 public synchronized  void setTestWhileIdle(boolean testWhileIdle) 
    Sets the testWhileIdle property. This property determines whether or not the idle object evictor will validate connections. For a true value to have any effect, the validationQuery property must be set to a non-null string.
 public synchronized  void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis) 
 public synchronized  void setUrl(String url) 

    Sets the #url .

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setUsername(String username) 

    Sets the #username .

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setValidationQuery(String validationQuery) 

    Sets the #validationQuery .

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public  void setValidationQueryTimeout(int timeout) 
    Sets the validation query timeout, the amount of time, in seconds, that connection validation will wait for a response from the database when executing a validation query. Use a value less than or equal to 0 for no timeout.

    Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first time one of the following methods is invoked: getConnection, setLogwriter, setLoginTimeout, getLoginTimeout, getLogWriter.

 public T unwrap(Class<T> iface) throws SQLException 
 protected static  void validateConnectionFactory(PoolableConnectionFactory connectionFactory) throws Exception