diff options
Diffstat (limited to 'dblib/common/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java')
| -rw-r--r-- | dblib/common/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java | 917 |
1 files changed, 917 insertions, 0 deletions
diff --git a/dblib/common/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java b/dblib/common/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java new file mode 100644 index 0000000..42cf11d --- /dev/null +++ b/dblib/common/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java @@ -0,0 +1,917 @@ +/*- + * ============LICENSE_START======================================================= + * openecomp + * ================================================================================ + * Copyright (C) 2016 - 2017 AT&T + * ================================================================================ + * Licensed 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. + * ============LICENSE_END========================================================= + */ + +/* + * 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 + */ + public static final 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 + */ + public 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 + */ + public int getAbandonWhenPercentageFull(); + + /** + * Returns <code>true</code> if a fair queue is being used by the connection pool + * @return <code>true</code> if a fair waiting queue is being used + */ + public 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 <code>true</code> to use a fair queue + */ + public 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 <code>true</code> + */ + public boolean isAccessToUnderlyingConnectionAllowed(); + + /** + * No-op + * @param accessToUnderlyingConnectionAllowed parameter ignored + */ + public 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;] <br> + * 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 + */ + public 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 + */ + public 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. + */ + public Properties getDbProperties(); + + /** + * Overrides the database properties passed into the {@link java.sql.Driver#connect(String, Properties)} method. + * @param dbProperties The database properties + */ + public 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. + */ + public 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. + */ + public 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. + */ + public 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. + */ + public 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. + */ + public 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 + */ + public 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 + */ + public 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. + */ + public 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. + */ + public 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. + */ + public 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. + */ + public 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. + */ + public 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 + */ + public 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. + * + */ + public 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. + */ + public 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. + */ + public 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 + */ + public 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 + */ + public 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. + */ + public 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 + */ + public 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. + */ + public 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. + */ + public 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. + */ + public 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. + */ + public 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 + */ + public 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 + */ + public 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 + */ + public String getName(); + + /** + * Sets the name of the connection pool + * @param name the name of the pool, should be unique in a runtime JVM + */ + public void setName(String name); + + /** + * Property not used + * @return unknown value + */ + public int getNumTestsPerEvictionRun(); + + /** + * Property not used + * @param numTestsPerEvictionRun parameter ignored. + */ + public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun); + + /** + * Returns the password used when establishing connections to the database. + * @return the password in string format + */ + public 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() + */ + public void setPassword(String password); + + /** + * @see #getName() + * @return the pool name + */ + public String getPoolName(); + + /** + * Returns the username used to establish the connection with + * @return the username used to establish the connection with + */ + public 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() + */ + public void setUsername(String username); + + + /** + * boolean flag to remove abandoned connections if they exceed the removeAbandonedTimout. + * 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 + */ + public boolean isRemoveAbandoned(); + + /** + * boolean flag to remove abandoned connections if they exceed the removeAbandonedTimout. + * 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 + */ + public 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 + */ + public 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 + */ + public 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() + */ + public 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() + */ + public 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() + */ + public 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() + */ + public 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) + */ + public 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) + */ + public 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 + */ + public 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 + */ + public 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) + */ + public 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) + */ + public 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 a 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 + */ + public 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 a 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 + */ + public 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 + */ + public 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 + */ + public 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 + */ + public 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 + */ + public void setValidatorClassName(String className); + + /** + * @return the optional validator object - may be null + */ + public 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 + */ + public 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 + */ + public 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 + */ + public 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 + */ + public 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 + */ + public 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 + */ + public 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 + */ + public 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' + */ + public 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' + */ + public 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 + */ + public 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. + */ + public 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. + */ + public 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 + * <code> + boolean result = getTimeBetweenEvictionRunsMillis()>0; + result = result && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0); + result = result || (isTestWhileIdle() && getValidationQuery()!=null); + return result; + </code> + * + * @return true if a background thread is or will be enabled for this pool + */ + public boolean isPoolSweeperEnabled(); + + /** + * Set to true if you wish the <code>ProxyConnection</code> class to use <code>String.equals</code> instead of + * <code>==</code> when comparing method names. + * This property does not apply to added interceptors as those are configured individually. + * The default value is <code>false</code>. + * @return true if pool uses {@link String#equals(Object)} instead of == when comparing method names on {@link java.sql.Connection} methods + */ + public boolean isUseEquals(); + + /** + * Set to true if you wish the <code>ProxyConnection</code> class to use <code>String.equals</code> instead of + * <code>==</code> when comparing method names. + * This property does not apply to added interceptors as those are configured individually. + * The default value is <code>false</code>. + * @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 + */ + public void setUseEquals(boolean useEquals); + + /** + * Time in milliseconds to keep this connection alive even when used. + * When a connection is returned to the pool, the pool will check to see if the + * ((now - time-when-connected) > maxAge) has been reached, and if so, + * it closes the connection rather than returning it to the pool. + * The default value is 0, which implies that connections will be left open and no + * age check will be done upon returning the connection to the pool. + * 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 + */ + public long getMaxAge(); + + /** + * Time in milliseconds to keep this connection alive even when used. + * When a connection is returned to the pool, the pool will check to see if the + * ((now - time-when-connected) > maxAge) has been reached, and if so, + * it closes the connection rather than returning it to the pool. + * The default value is 0, which implies that connections will be left open and no + * age check will be done upon returning the connection to the pool. + * 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 + */ + public 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. + */ + public 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 + */ + public 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. + */ + public 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. + */ + public 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. + */ + public 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. + */ + public 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. + */ + public void setDataSourceJNDI(String jndiDS); + + /** + * Returns the JNDI string configured for data source usage. + * @return the JNDI string or null if not set + */ + public 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. + */ + public 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. + */ + public 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 + */ + public void setCommitOnReturn(boolean commitOnReturn); + + /** + * @see PoolConfiguration#setCommitOnReturn(boolean) + * @return <code>true</code> if the pool should commit when a connection is returned to it + */ + public 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 + */ + public void setRollbackOnReturn(boolean rollbackOnReturn); + + /** + * @see PoolConfiguration#setRollbackOnReturn(boolean) + * @return <code>true</code> if the pool should rollback when a connection is returned to it + */ + public boolean getRollbackOnReturn(); + + /** + * If set to <code>true</code>, 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 <code>true</code>, 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 <code>true</code> to use a facade + */ + public void setUseDisposableConnectionFacade(boolean useDisposableConnectionFacade); + /** + * Returns <code>true</code> 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 <code>true</code> if {@link java.sql.Connection#close()} has been invoked. + */ + public 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 + */ + public 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 + */ + public 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 + */ + public 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. + */ + public 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. + */ + public void setIgnoreExceptionOnPreLoad(boolean ignoreExceptionOnPreLoad); + + /** + * @return <code>true</code> to ignore exceptions + * @see PoolConfiguration#setIgnoreExceptionOnPreLoad(boolean) + */ + public boolean isIgnoreExceptionOnPreLoad(); + +} |