All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.tomcat.jdbc.pool.PoolConfiguration Maven / Gradle / Ivy

There is a newer version: 11.0.0-M26
Show newest version
/*
 * 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.pool;

import java.util.Properties;

import org.apache.tomcat.jdbc.pool.PoolProperties.InterceptorDefinition;

/**
 * A list of properties that are configurable for a connection pool.
 * The {@link DataSource} object also implements this interface so that it can be easily configured through
 * an IoC container without having to specify a secondary object with a setter method.
 *
 */

public interface PoolConfiguration {

    /**
     * JMX prefix for interceptors that register themselves with JMX
     */
    String PKG_PREFIX = "org.apache.tomcat.jdbc.pool.interceptor.";

    /**
     * Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are
     * above the percentage defined by abandonWhenPercentageFull.
     * The value should be between 0-100.
     * The default value is 0, which implies that connections are eligible for
     * closure as soon as removeAbandonedTimeout has been reached.
     * @param percentage a value between 0 and 100 to indicate when connections that have been abandoned/timed out are considered abandoned
     */
    void setAbandonWhenPercentageFull(int percentage);

    /**
     * Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are
     * above the percentage defined by abandonWhenPercentageFull.
     * The value should be between 0-100.
     * The default value is 0, which implies that connections are eligible for
     * closure as soon as removeAbandonedTimeout has been reached.
     * @return percentage - a value between 0 and 100 to indicate when connections that have been abandoned/timed out are considered abandoned
     */
    int getAbandonWhenPercentageFull();

    /**
     * Returns true if a fair queue is being used by the connection pool
     * @return true if a fair waiting queue is being used
     */
    boolean isFairQueue();

    /**
     * Set to true if you wish that calls to getConnection
     * should be treated fairly in a true FIFO fashion.
     * This uses the {@link FairBlockingQueue} implementation for the list of the idle connections.
     * The default value is true.
     * This flag is required when you want to use asynchronous connection retrieval.
     * @param fairQueue true to use a fair queue
     */
    void setFairQueue(boolean fairQueue);

    /**
     * Property not used. Access is always allowed.
     * Access can be achieved by calling unwrap on the pooled connection. see {@link javax.sql.DataSource} interface
     * or call getConnection through reflection or cast the object as {@link javax.sql.PooledConnection}
     * @return true
     */
    boolean isAccessToUnderlyingConnectionAllowed();

    /**
     * No-op
     * @param accessToUnderlyingConnectionAllowed parameter ignored
     */
    void setAccessToUnderlyingConnectionAllowed(boolean accessToUnderlyingConnectionAllowed);

    /**
     * The connection properties that will be sent to the JDBC driver when establishing new connections.
     * Format of the string is [propertyName=property;] 
* NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here. * The default value is null. * @return the connection properties */ String getConnectionProperties(); /** * The properties that will be passed into {@link java.sql.Driver#connect(String, Properties)} method. * Username and password do not need to be stored here, they will be passed into the properties right before the connection is established. * @param connectionProperties properties - Format of the string is [propertyName=property;]* * Example: prop1=value1;prop2=value2 */ void setConnectionProperties(String connectionProperties); /** * Returns the database properties that are passed into the {@link java.sql.Driver#connect(String, Properties)} method. * @return database properties that are passed into the {@link java.sql.Driver#connect(String, Properties)} method. */ Properties getDbProperties(); /** * Overrides the database properties passed into the {@link java.sql.Driver#connect(String, Properties)} method. * @param dbProperties The database properties */ void setDbProperties(Properties dbProperties); /** * The default auto-commit state of connections created by this pool. * If not set (null), default is JDBC driver default (If set to null then the {@link java.sql.Connection#setAutoCommit(boolean)} method will not be called.) * @return the default auto commit setting, null is Driver default. */ Boolean isDefaultAutoCommit(); /** * The default auto-commit state of connections created by this pool. * If not set (null), default is JDBC driver default (If set to null then the {@link java.sql.Connection#setAutoCommit(boolean)} method will not be called.) * @return the default auto commit setting, null is Driver default. */ Boolean getDefaultAutoCommit(); /** * The default auto-commit state of connections created by this pool. * If not set (null), default is JDBC driver default (If set to null then the {@link java.sql.Connection#setAutoCommit(boolean)} method will not be called.) * @param defaultAutoCommit default auto commit setting, null is Driver default. */ void setDefaultAutoCommit(Boolean defaultAutoCommit); /** * If non null, during connection creation the method {@link java.sql.Connection#setCatalog(String)} will be called with the set value. * @return the default catalog, null if not set and accepting the driver default. */ String getDefaultCatalog(); /** * If non null, during connection creation the method {@link java.sql.Connection#setCatalog(String)} will be called with the set value. * @param defaultCatalog null if not set and accepting the driver default. */ void setDefaultCatalog(String defaultCatalog); /** * If non null, during connection creation the method {@link java.sql.Connection#setReadOnly(boolean)} will be called with the set value. * @return null if not set and accepting the driver default otherwise the read only value */ Boolean isDefaultReadOnly(); /** * If non null, during connection creation the method {@link java.sql.Connection#setReadOnly(boolean)} will be called with the set value. * @return null if not set and accepting the driver default otherwise the read only value */ Boolean getDefaultReadOnly(); /** * If non null, during connection creation the method {@link java.sql.Connection#setReadOnly(boolean)} will be called with the set value. * @param defaultReadOnly null if not set and accepting the driver default. */ void setDefaultReadOnly(Boolean defaultReadOnly); /** * Returns the default transaction isolation level. If set to {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION} the method * {@link java.sql.Connection#setTransactionIsolation(int)} will not be called during connection creation. * @return driver transaction isolation level, or -1 {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION} if not set. */ int getDefaultTransactionIsolation(); /** * If set to {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION} the method * {@link java.sql.Connection#setTransactionIsolation(int)} will not be called during connection creation. Otherwise the method * will be called with the isolation level set by this property. * @param defaultTransactionIsolation a value of {@link java.sql.Connection#TRANSACTION_NONE}, {@link java.sql.Connection#TRANSACTION_READ_COMMITTED}, * {@link java.sql.Connection#TRANSACTION_READ_UNCOMMITTED}, {@link java.sql.Connection#TRANSACTION_REPEATABLE_READ}, * {@link java.sql.Connection#TRANSACTION_SERIALIZABLE} or {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION} * The last value will not be set on the connection. */ void setDefaultTransactionIsolation(int defaultTransactionIsolation); /** * The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible from the same classloader as tomcat-jdbc.jar * @return fully qualified JDBC driver name. */ String getDriverClassName(); /** * The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible from the same classloader as tomcat-jdbc.jar * @param driverClassName a fully qualified Java class name of a {@link java.sql.Driver} implementation. */ void setDriverClassName(String driverClassName); /** * Returns the number of connections that will be established when the connection pool is started. * Default value is 10 * @return number of connections to be started when pool is started */ int getInitialSize(); /** * Set the number of connections that will be established when the connection pool is started. * Default value is 10. * If this value exceeds {@link #setMaxActive(int)} it will automatically be lowered. * @param initialSize the number of connections to be established. * */ void setInitialSize(int initialSize); /** * boolean flag to set if stack traces should be logged for application code which abandoned a Connection. * Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated. * The default value is false. * @return true if the connection pool logs stack traces when connections are borrowed from the pool. */ boolean isLogAbandoned(); /** * boolean flag to set if stack traces should be logged for application code which abandoned a Connection. * Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated. * The default value is false. * @param logAbandoned set to true if stack traces should be recorded when {@link DataSource#getConnection()} is called. */ void setLogAbandoned(boolean logAbandoned); /** * The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100 * @return the maximum number of connections used by this pool */ int getMaxActive(); /** * The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100 * @param maxActive hard limit for number of managed connections by this pool */ void setMaxActive(int maxActive); /** * The maximum number of connections that should be kept in the idle pool if {@link #isPoolSweeperEnabled()} returns false. * If the If {@link #isPoolSweeperEnabled()} returns true, then the idle pool can grow up to {@link #getMaxActive} * and will be shrunk according to {@link #getMinEvictableIdleTimeMillis()} setting. * Default value is maxActive:100 * @return the maximum number of idle connections. */ int getMaxIdle(); /** * The maximum number of connections that should be kept in the idle pool if {@link #isPoolSweeperEnabled()} returns false. * If the If {@link #isPoolSweeperEnabled()} returns true, then the idle pool can grow up to {@link #getMaxActive} * and will be shrunk according to {@link #getMinEvictableIdleTimeMillis()} setting. * Default value is maxActive:100 * @param maxIdle the maximum size of the idle pool */ void setMaxIdle(int maxIdle); /** * The maximum number of milliseconds that the pool will wait (when there are no available connections and the * {@link #getMaxActive} has been reached) for a connection to be returned * before throwing an exception. Default value is 30000 (30 seconds) * @return the number of milliseconds to wait for a connection to become available if the pool is maxed out. */ int getMaxWait(); /** * The maximum number of milliseconds that the pool will wait (when there are no available connections and the * {@link #getMaxActive} has been reached) for a connection to be returned * before throwing an exception. Default value is 30000 (30 seconds) * @param maxWait the maximum number of milliseconds to wait. */ void setMaxWait(int maxWait); /** * The minimum amount of time an object must sit idle in the pool before it is eligible for eviction. * The default value is 60000 (60 seconds). * @return the minimum amount of idle time in milliseconds before a connection is considered idle and eligible for eviction. */ int getMinEvictableIdleTimeMillis(); /** * The minimum amount of time an object must sit idle in the pool before it is eligible for eviction. * The default value is 60000 (60 seconds). * @param minEvictableIdleTimeMillis the number of milliseconds a connection must be idle to be eligible for eviction. */ void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis); /** * The minimum number of established connections that should be kept in the pool at all times. * The connection pool can shrink below this number if validation queries fail and connections get closed. * Default value is derived from {@link #getInitialSize()} (also see {@link #setTestWhileIdle(boolean)} * The idle pool will not shrink below this value during an eviction run, hence the number of actual connections * can be between {@link #getMinIdle()} and somewhere between {@link #getMaxIdle()} and {@link #getMaxActive()} * @return the minimum number of idle or established connections */ int getMinIdle(); /** * The minimum number of established connections that should be kept in the pool at all times. * The connection pool can shrink below this number if validation queries fail and connections get closed. * Default value is derived from {@link #getInitialSize()} (also see {@link #setTestWhileIdle(boolean)} * The idle pool will not shrink below this value during an eviction run, hence the number of actual connections * can be between {@link #getMinIdle()} and somewhere between {@link #getMaxIdle()} and {@link #getMaxActive()} * * @param minIdle the minimum number of idle or established connections */ void setMinIdle(int minIdle); /** * Returns the name of the connection pool. By default a JVM unique random name is assigned. * @return the name of the pool, should be unique in a JVM */ String getName(); /** * Sets the name of the connection pool * @param name the name of the pool, should be unique in a runtime JVM */ void setName(String name); /** * Property not used * @return unknown value */ int getNumTestsPerEvictionRun(); /** * Property not used * @param numTestsPerEvictionRun parameter ignored. */ void setNumTestsPerEvictionRun(int numTestsPerEvictionRun); /** * Returns the password used when establishing connections to the database. * @return the password in string format */ String getPassword(); /** * Sets the password to establish the connection with. * The password will be included as a database property with the name 'password'. * @param password The password * @see #getDbProperties() */ void setPassword(String password); /** * @see #getName() * @return the pool name */ String getPoolName(); /** * Returns the username used to establish the connection with * @return the username used to establish the connection with */ String getUsername(); /** * Sets the username used to establish the connection with * It will also be a property called 'user' in the database properties. * @param username The user name * @see #getDbProperties() */ void setUsername(String username); /** * boolean flag to remove abandoned connections if they exceed the removeAbandonedTimeout. * If set to true a connection is considered abandoned and eligible for removal if it has * been in use longer than the {@link #getRemoveAbandonedTimeout()} and the condition for * {@link #getAbandonWhenPercentageFull()} is met. * Setting this to true can recover db connections from applications that fail to close a connection. * See also {@link #isLogAbandoned()} The default value is false. * @return true if abandoned connections can be closed and expelled out of the pool */ boolean isRemoveAbandoned(); /** * boolean flag to remove abandoned connections if they exceed the removeAbandonedTimeout. * If set to true a connection is considered abandoned and eligible for removal if it has * been in use longer than the {@link #getRemoveAbandonedTimeout()} and the condition for * {@link #getAbandonWhenPercentageFull()} is met. * Setting this to true can recover db connections from applications that fail to close a connection. * See also {@link #isLogAbandoned()} The default value is false. * @param removeAbandoned set to true if abandoned connections can be closed and expelled out of the pool */ void setRemoveAbandoned(boolean removeAbandoned); /** * The time in seconds before a connection can be considered abandoned. * The timer can be reset upon queries using an interceptor. * @param removeAbandonedTimeout the time in seconds before a used connection can be considered abandoned * @see org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer */ void setRemoveAbandonedTimeout(int removeAbandonedTimeout); /** * The time in seconds before a connection can be considered abandoned. * The timer can be reset upon queries using an interceptor. * @see org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer * @return the time in seconds before a used connection can be considered abandoned */ int getRemoveAbandonedTimeout(); /** * 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. * NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. * Default value is false * In order to have a more efficient validation, see {@link #setValidationInterval(long)} * @return true if the connection is to be validated upon borrowing a connection from the pool * @see #getValidationInterval() */ boolean isTestOnBorrow(); /** * 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. * NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. * Default value is false * In order to have a more efficient validation, see {@link #setValidationInterval(long)} * @param testOnBorrow set to true if validation should take place before a connection is handed out to the application * @see #getValidationInterval() */ void setTestOnBorrow(boolean testOnBorrow); /** * The indication of whether objects will be validated after being returned to the pool. * If the object fails to validate, it will be dropped from the pool. * NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. * Default value is false * In order to have a more efficient validation, see {@link #setValidationInterval(long)} * @return true if validation should take place after a connection is returned to the pool * @see #getValidationInterval() */ boolean isTestOnReturn(); /** * The indication of whether objects will be validated after being returned to the pool. * If the object fails to validate, it will be dropped from the pool. * NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. * Default value is false * In order to have a more efficient validation, see {@link #setValidationInterval(long)} * @param testOnReturn true if validation should take place after a connection is returned to the pool * @see #getValidationInterval() */ void setTestOnReturn(boolean testOnReturn); /** * Set to true if query validation should take place while the connection is idle. * @return true if validation should take place during idle checks * @see #setTimeBetweenEvictionRunsMillis(int) */ boolean isTestWhileIdle(); /** * Set to true if query validation should take place while the connection is idle. * @param testWhileIdle true if validation should take place during idle checks * @see #setTimeBetweenEvictionRunsMillis(int) */ void setTestWhileIdle(boolean testWhileIdle); /** * The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner * and idle pool resizing. This value should not be set under 1 second. * It dictates how often we check for idle, abandoned connections, and how often we validate idle connection and resize the idle pool. * The default value is 5000 (5 seconds) * @return the sleep time in between validations in milliseconds */ int getTimeBetweenEvictionRunsMillis(); /** * The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner * and idle pool resizing. This value should not be set under 1 second. * It dictates how often we check for idle, abandoned connections, and how often we validate idle connection and resize the idle pool. * The default value is 5000 (5 seconds) * @param timeBetweenEvictionRunsMillis the sleep time in between validations in milliseconds */ void setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis); /** * The URL used to connect to the database * @return the configured URL for this connection pool * @see java.sql.Driver#connect(String, Properties) */ String getUrl(); /** * Sets the URL used to connect to the database * @param url the configured URL for this connection pool * @see java.sql.Driver#connect(String, Properties) */ void setUrl(String url); /** * The SQL query that will be used to validate connections from this * pool before returning them to the caller or pool. * If specified, this query does not have to return any data, * it just can't throw an SQLException. * The default value is null. * Example values are SELECT 1(mysql), * select 1 from dual(oracle), * SELECT 1(MS Sql Server) * @return the query used for validation or null if no validation is performed */ String getValidationQuery(); /** * The SQL query that will be used to validate connections from this * pool before returning them to the caller or pool. * If specified, this query does not have to return any data, * it just can't throw an SQLException. * The default value is null. * Example values are SELECT 1(mysql), * select 1 from dual(oracle), * SELECT 1(MS Sql Server) * @param validationQuery the query used for validation or null if no validation is performed */ void setValidationQuery(String validationQuery); /** * The timeout in seconds before a connection validation queries fail. * A value less than or equal to zero will disable this feature. Defaults to -1. * @return the timeout value in seconds */ int getValidationQueryTimeout(); /** * The timeout in seconds before a connection validation queries fail. * A value less than or equal to zero will disable this feature. Defaults to -1. * @param validationQueryTimeout The timeout value */ void setValidationQueryTimeout(int validationQueryTimeout); /** * Return the name of the optional validator class - may be null. * * @return the name of the optional validator class - may be null */ String getValidatorClassName(); /** * Set the name for an optional validator class which will be used in place of test queries. If set to * null, standard validation will be used. * * @param className the name of the optional validator class */ void setValidatorClassName(String className); /** * @return the optional validator object - may be null */ Validator getValidator(); /** * Sets the validator object * If this is a non null object, it will be used as a validator instead of the validationQuery * If this is null, remove the usage of the validator. * @param validator The validator object */ void setValidator(Validator validator); /** * avoid excess validation, only run validation at most at this frequency - time in milliseconds. * If a connection is due for validation, but has been validated previously * within this interval, it will not be validated again. * The default value is 3000 (3 seconds). * @return the validation interval in milliseconds */ long getValidationInterval(); /** * avoid excess validation, only run validation at most at this frequency - time in milliseconds. * If a connection is due for validation, but has been validated previously * within this interval, it will not be validated again. * The default value is 3000 (3 seconds). * @param validationInterval the validation interval in milliseconds */ void setValidationInterval(long validationInterval); /** * A custom query to be run when a connection is first created. The default value is null. * This query only runs once per connection, and that is when a new connection is established to the database. * If this value is non null, it will replace the validation query during connection creation. * @return the init SQL used to run against the DB or null if not set */ String getInitSQL(); /** * A custom query to be run when a connection is first created. The default value is null. * This query only runs once per connection, and that is when a new connection is established to the database. * If this value is non null, it will replace the validation query during connection creation. * @param initSQL the init SQL used to run against the DB or null if no query should be executed */ void setInitSQL(String initSQL); /** * Returns true if we should run the validation query when connecting to the database for the first time on a connection. * Normally this is always set to false, unless one wants to use the validationQuery as an init query. * @return true if we should run the validation query upon connect */ boolean isTestOnConnect(); /** * Set to true if we should run the validation query when connecting to the database for the first time on a connection. * Normally this is always set to false, unless one wants to use the validationQuery as an init query. * Setting an {@link #setInitSQL(String)} will override this setting, as the init SQL will be used instead of the validation query * @param testOnConnect set to true if we should run the validation query upon connect */ void setTestOnConnect(boolean testOnConnect); /** * A semicolon separated list of classnames extending {@link org.apache.tomcat.jdbc.pool.JdbcInterceptor} class. * These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object. * Example interceptors are {@link org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer StatementFinalizer} to close all * used statements during the session. * {@link org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer ResetAbandonedTimer} resets the timer upon every operation * on the connection or a statement. * {@link org.apache.tomcat.jdbc.pool.interceptor.ConnectionState ConnectionState} caches the auto commit, read only and catalog settings to avoid round trips to the DB. * The default value is null. * @return the interceptors that are used for connections. * Example format: 'ConnectionState(useEquals=true,fast=yes);ResetAbandonedTimer' */ String getJdbcInterceptors(); /** * A semicolon separated list of classnames extending {@link org.apache.tomcat.jdbc.pool.JdbcInterceptor} class. * These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object. * Example interceptors are {@link org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer StatementFinalizer} to close all * used statements during the session. * {@link org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer ResetAbandonedTimer} resets the timer upon every operation * on the connection or a statement. * {@link org.apache.tomcat.jdbc.pool.interceptor.ConnectionState ConnectionState} caches the auto commit, read only and catalog settings to avoid round trips to the DB. * The default value is null. * @param jdbcInterceptors the interceptors that are used for connections. * Example format: 'ConnectionState(useEquals=true,fast=yes);ResetAbandonedTimer' */ void setJdbcInterceptors(String jdbcInterceptors); /** * Returns the {@link #getJdbcInterceptors()} as an array of objects with properties and the classes. * @return an array of interceptors that have been configured */ InterceptorDefinition[] getJdbcInterceptorsAsArray(); /** * If set to true, the connection pool creates a {@link org.apache.tomcat.jdbc.pool.jmx.ConnectionPoolMBean} object * that can be registered with JMX to receive notifications and state about the pool. * The ConnectionPool object doesn't register itself, as there is no way to keep a static non changing ObjectName across JVM restarts. * @return true if the mbean object will be created upon startup. */ boolean isJmxEnabled(); /** * If set to true, the connection pool creates a {@link org.apache.tomcat.jdbc.pool.jmx.ConnectionPoolMBean} object * that can be registered with JMX to receive notifications and state about the pool. * The ConnectionPool object doesn't register itself, as there is no way to keep a static non changing ObjectName across JVM restarts. * @param jmxEnabled set to to if the mbean object should be created upon startup. */ void setJmxEnabled(boolean jmxEnabled); /** * Returns true if the pool sweeper is enabled for the connection pool. * The pool sweeper is enabled if any settings that require async intervention in the pool are turned on * * boolean result = getTimeBetweenEvictionRunsMillis()>0; * result = result && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0); * result = result || (isTestWhileIdle() && getValidationQuery()!=null); * return result; * * * @return true if a background thread is or will be enabled for this pool */ boolean isPoolSweeperEnabled(); /** * Set to true if you wish the ProxyConnection class to use String.equals instead of * == when comparing method names. * This property does not apply to added interceptors as those are configured individually. * The default value is false. * @return true if pool uses {@link String#equals(Object)} instead of == when comparing method names on {@link java.sql.Connection} methods */ boolean isUseEquals(); /** * Set to true if you wish the ProxyConnection class to use String.equals instead of * == when comparing method names. * This property does not apply to added interceptors as those are configured individually. * The default value is false. * @param useEquals set to true if the pool should use {@link String#equals(Object)} instead of == * when comparing method names on {@link java.sql.Connection} methods */ void setUseEquals(boolean useEquals); /** * Time in milliseconds to keep this connection before reconnecting. * When a connection is idle, returned to the pool or borrowed from the pool, the pool will * check to see if the ((now - time-when-connected) > maxAge) has been reached, and if so, * it reconnects. Note that the age of idle connections will only be checked if * {@link #getTimeBetweenEvictionRunsMillis()} returns a value greater than 0. * The default value is 0, which implies that connections will be left open and no * age checks will be done. * This is a useful setting for database sessions that leak memory as it ensures that the session * will have a finite life span. * @return the time in milliseconds a connection will be open for when used */ long getMaxAge(); /** * Time in milliseconds to keep this connection before reconnecting. * When a connection is idle, returned to the pool or borrowed from the pool, the pool will * check to see if the ((now - time-when-connected) > maxAge) has been reached, and if so, * it reconnects. Note that the age of idle connections will only be checked if * {@link #getTimeBetweenEvictionRunsMillis()} returns a value greater than 0. * The default value is 0, which implies that connections will be left open and no * age checks will be done. * This is a useful setting for database sessions that leak memory as it ensures that the session * will have a finite life span. * @param maxAge the time in milliseconds a connection will be open for when used */ void setMaxAge(long maxAge); /** * Return true if a lock should be used when operations are performed on the connection object. * Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking * such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting. * @return true if a lock is used. */ boolean getUseLock(); /** * Set to true if a lock should be used when operations are performed on the connection object. * Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking * such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting. * @param useLock set to true if a lock should be used on connection operations */ void setUseLock(boolean useLock); /** * Similar to {@link #setRemoveAbandonedTimeout(int)} but instead of treating the connection * as abandoned, and potentially closing the connection, this simply logs the warning if * {@link #isLogAbandoned()} returns true. If this value is equal or less than 0, no suspect * checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and * the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets * logged and a JMX notification gets sent once. * @param seconds - the amount of time in seconds that has to pass before a connection is marked suspect. */ void setSuspectTimeout(int seconds); /** * Returns the time in seconds to pass before a connection is marked an abandoned suspect. * Any value lesser than or equal to 0 means the check is disabled. * @return Returns the time in seconds to pass before a connection is marked an abandoned suspect. */ int getSuspectTimeout(); /** * Injects a datasource that will be used to retrieve/create connections. * If a data source is set, the {@link PoolConfiguration#getUrl()} and {@link PoolConfiguration#getDriverClassName()} methods are ignored * and not used by the pool. If the {@link PoolConfiguration#getUsername()} and {@link PoolConfiguration#getPassword()} * values are set, the method {@link javax.sql.DataSource#getConnection(String, String)} method will be called instead of the * {@link javax.sql.DataSource#getConnection()} method. * If the data source implements {@link javax.sql.XADataSource} the methods * {@link javax.sql.XADataSource#getXAConnection()} and {@link javax.sql.XADataSource#getXAConnection(String,String)} * will be invoked. * @param ds the {@link javax.sql.DataSource} to be used for creating connections to be pooled. */ void setDataSource(Object ds); /** * Returns a datasource, if one exists that is being used to create connections. * This method will return null if the pool is using a {@link java.sql.Driver} * @return the {@link javax.sql.DataSource} to be used for creating connections to be pooled or null if a Driver is used. */ Object getDataSource(); /** * Configure the connection pool to use a DataSource according to {@link PoolConfiguration#setDataSource(Object)} * But instead of injecting the object, specify the JNDI location. * After a successful JNDI look, the {@link PoolConfiguration#getDataSource()} will not return null. * @param jndiDS -the JNDI string @TODO specify the rules here. */ void setDataSourceJNDI(String jndiDS); /** * Returns the JNDI string configured for data source usage. * @return the JNDI string or null if not set */ String getDataSourceJNDI(); /** * Returns true if the call {@link DataSource#getConnection(String, String) getConnection(username,password)} is * allowed. This is used for when the pool is used by an application accessing multiple schemas. * There is a performance impact turning this option on. * @return true if {@link DataSource#getConnection(String, String) getConnection(username,password)} is honored, false if it is ignored. */ boolean isAlternateUsernameAllowed(); /** * Set to true if the call {@link DataSource#getConnection(String, String) getConnection(username,password)} is * allowed and honored.. This is used for when the pool is used by an application accessing multiple schemas. * There is a performance impact turning this option on, even when not used due to username checks. * @param alternateUsernameAllowed - set true if {@link DataSource#getConnection(String, String) getConnection(username,password)} is honored, * false if it is to be ignored. */ void setAlternateUsernameAllowed(boolean alternateUsernameAllowed); /** * Set to true if you want the connection pool to commit any pending transaction when a connection is returned. * The default value is false, as this could result in committing data. * This parameter is only looked at if the {@link #getDefaultAutoCommit()} returns false * @param commitOnReturn set to true if the pool should call {@link java.sql.Connection#commit()} when a connection is returned to the pool. * Default is false */ void setCommitOnReturn(boolean commitOnReturn); /** * @see PoolConfiguration#setCommitOnReturn(boolean) * @return true if the pool should commit when a connection is returned to it */ boolean getCommitOnReturn(); /** * Set to true if you want the connection pool to rollback any pending transaction when a connection is returned. * The default value is false, as this could result in committing data. * This parameter is only looked at if the {@link #getDefaultAutoCommit()} returns false * @param rollbackOnReturn set to true if the pool should call {@link java.sql.Connection#rollback()} when a connection is returned to the pool. * Default is false */ void setRollbackOnReturn(boolean rollbackOnReturn); /** * @see PoolConfiguration#setRollbackOnReturn(boolean) * @return true if the pool should rollback when a connection is returned to it */ boolean getRollbackOnReturn(); /** * If set to true, the connection will be wrapped with facade that will disallow the connection to be used after * {@link java.sql.Connection#close()} is called. If set to true, after {@link java.sql.Connection#close()} all calls except * {@link java.sql.Connection#close()} and {@link java.sql.Connection#isClosed()} will throw an exception. * @param useDisposableConnectionFacade true to use a facade */ void setUseDisposableConnectionFacade(boolean useDisposableConnectionFacade); /** * Returns true if this connection pool is configured to use a connection facade to prevent re-use of connection after * {@link java.sql.Connection#close()} has been invoked * @return true if {@link java.sql.Connection#close()} has been invoked. */ boolean getUseDisposableConnectionFacade(); /** * Set to true if you wish that errors from validation should be logged as error messages. * @param logValidationErrors set to true to log validation errors */ void setLogValidationErrors(boolean logValidationErrors); /** * Returns true if errors that happen during validation will be logged * @return true if errors that happen during validation will be logged */ boolean getLogValidationErrors(); /** * Returns true if the pool is configured to propagate interrupt state of a thread. * A thread waiting for a connection, can have its wait interrupted, and by default * will clear the interrupt flag and throw a {@link PoolExhaustedException} * @return true if the pool is configured to propagate and not clear the thread interrupt state */ boolean getPropagateInterruptState(); /** * Configure the pool to propagate interrupt state for interrupted threads waiting for a connection * A thread waiting for a connection, can have its wait interrupted, and by default * will clear the interrupt flag and throw a {@link PoolExhaustedException} * If set to true, this behavior will change, while the {@link PoolExhaustedException} is still thrown, the threads interrupted state is still set. * @param propagateInterruptState - set to true to not clear, but propagate, a threads interrupted state. */ void setPropagateInterruptState(boolean propagateInterruptState); /** * Set to true if you want to ignore error of connection creation while initializing the pool. * Set to false if you want to fail the initialization of the pool by throwing exception. * @param ignoreExceptionOnPreLoad set to true if you want to ignore error of connection creation while initializing the pool. */ void setIgnoreExceptionOnPreLoad(boolean ignoreExceptionOnPreLoad); /** * @return true to ignore exceptions * @see PoolConfiguration#setIgnoreExceptionOnPreLoad(boolean) */ boolean isIgnoreExceptionOnPreLoad(); /** * Set this to true if you wish to wrap statements in order to enable equals() and hashCode() * methods to be called on the closed statements if any statement proxy is set. * @param useStatementFacade set to true to wrap statements */ void setUseStatementFacade(boolean useStatementFacade); /** * Returns true if this connection pool is configured to wrap statements in order * to enable equals() and hashCode() methods to be called on the closed statements if any * statement proxy is set. * @return true if the statements are wrapped */ boolean getUseStatementFacade(); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy