2 * ============LICENSE_START=======================================================
4 * ================================================================================
5 * Copyright (C) 2016 - 2017 AT&T
6 * ================================================================================
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 * ============LICENSE_END=========================================================
22 * Licensed to the Apache Software Foundation (ASF) under one or more
23 * contributor license agreements. See the NOTICE file distributed with
24 * this work for additional information regarding copyright ownership.
25 * The ASF licenses this file to You under the Apache License, Version 2.0
26 * (the "License"); you may not use this file except in compliance with
27 * the License. You may obtain a copy of the License at
29 * http://www.apache.org/licenses/LICENSE-2.0
31 * Unless required by applicable law or agreed to in writing, software
32 * distributed under the License is distributed on an "AS IS" BASIS,
33 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
34 * See the License for the specific language governing permissions and
35 * limitations under the License.
37 package org.apache.tomcat.jdbc.pool;
39 import java.util.Properties;
41 import org.apache.tomcat.jdbc.pool.PoolProperties.InterceptorDefinition;
44 * A list of properties that are configurable for a connection pool.
45 * The {@link DataSource} object also implements this interface so that it can be easily configured through
46 * an IoC container without having to specify a secondary object with a setter method.
50 public interface PoolConfiguration {
53 * JMX prefix for interceptors that register themselves with JMX
55 public static final String PKG_PREFIX = "org.apache.tomcat.jdbc.pool.interceptor.";
58 * Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are
59 * above the percentage defined by abandonWhenPercentageFull.
60 * The value should be between 0-100.
61 * The default value is 0, which implies that connections are eligible for
62 * closure as soon as removeAbandonedTimeout has been reached.
63 * @param percentage a value between 0 and 100 to indicate when connections that have been abandoned/timed out are considered abandoned
65 public void setAbandonWhenPercentageFull(int percentage);
68 * Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are
69 * above the percentage defined by abandonWhenPercentageFull.
70 * The value should be between 0-100.
71 * The default value is 0, which implies that connections are eligible for
72 * closure as soon as removeAbandonedTimeout has been reached.
73 * @return percentage - a value between 0 and 100 to indicate when connections that have been abandoned/timed out are considered abandoned
75 public int getAbandonWhenPercentageFull();
78 * Returns <code>true</code> if a fair queue is being used by the connection pool
79 * @return <code>true</code> if a fair waiting queue is being used
81 public boolean isFairQueue();
84 * Set to true if you wish that calls to getConnection
85 * should be treated fairly in a true FIFO fashion.
86 * This uses the {@link FairBlockingQueue} implementation for the list of the idle connections.
87 * The default value is true.
88 * This flag is required when you want to use asynchronous connection retrieval.
89 * @param fairQueue <code>true</code> to use a fair queue
91 public void setFairQueue(boolean fairQueue);
94 * Property not used. Access is always allowed.
95 * Access can be achieved by calling unwrap on the pooled connection. see {@link javax.sql.DataSource} interface
96 * or call getConnection through reflection or cast the object as {@link javax.sql.PooledConnection}
97 * @return <code>true</code>
99 public boolean isAccessToUnderlyingConnectionAllowed();
103 * @param accessToUnderlyingConnectionAllowed parameter ignored
105 public void setAccessToUnderlyingConnectionAllowed(boolean accessToUnderlyingConnectionAllowed);
108 * The connection properties that will be sent to the JDBC driver when establishing new connections.
109 * Format of the string is [propertyName=property;] <br>
110 * NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here.
111 * The default value is null.
112 * @return the connection properties
114 public String getConnectionProperties();
117 * The properties that will be passed into {@link java.sql.Driver#connect(String, Properties)} method.
118 * Username and password do not need to be stored here, they will be passed into the properties right before the connection is established.
119 * @param connectionProperties properties - Format of the string is [propertyName=property;]*
120 * Example: prop1=value1;prop2=value2
122 public void setConnectionProperties(String connectionProperties);
125 * Returns the database properties that are passed into the {@link java.sql.Driver#connect(String, Properties)} method.
126 * @return database properties that are passed into the {@link java.sql.Driver#connect(String, Properties)} method.
128 public Properties getDbProperties();
131 * Overrides the database properties passed into the {@link java.sql.Driver#connect(String, Properties)} method.
132 * @param dbProperties The database properties
134 public void setDbProperties(Properties dbProperties);
137 * The default auto-commit state of connections created by this pool.
138 * 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.)
139 * @return the default auto commit setting, null is Driver default.
141 public Boolean isDefaultAutoCommit();
144 * The default auto-commit state of connections created by this pool.
145 * 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.)
146 * @return the default auto commit setting, null is Driver default.
148 public Boolean getDefaultAutoCommit();
151 * The default auto-commit state of connections created by this pool.
152 * 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.)
153 * @param defaultAutoCommit default auto commit setting, null is Driver default.
155 public void setDefaultAutoCommit(Boolean defaultAutoCommit);
158 * If non null, during connection creation the method {@link java.sql.Connection#setCatalog(String)} will be called with the set value.
159 * @return the default catalog, null if not set and accepting the driver default.
161 public String getDefaultCatalog();
164 * If non null, during connection creation the method {@link java.sql.Connection#setCatalog(String)} will be called with the set value.
165 * @param defaultCatalog null if not set and accepting the driver default.
167 public void setDefaultCatalog(String defaultCatalog);
170 * If non null, during connection creation the method {@link java.sql.Connection#setReadOnly(boolean)} will be called with the set value.
171 * @return null if not set and accepting the driver default otherwise the read only value
173 public Boolean isDefaultReadOnly();
176 * If non null, during connection creation the method {@link java.sql.Connection#setReadOnly(boolean)} will be called with the set value.
177 * @return null if not set and accepting the driver default otherwise the read only value
179 public Boolean getDefaultReadOnly();
182 * If non null, during connection creation the method {@link java.sql.Connection#setReadOnly(boolean)} will be called with the set value.
183 * @param defaultReadOnly null if not set and accepting the driver default.
185 public void setDefaultReadOnly(Boolean defaultReadOnly);
189 * Returns the default transaction isolation level. If set to {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION} the method
190 * {@link java.sql.Connection#setTransactionIsolation(int)} will not be called during connection creation.
191 * @return driver transaction isolation level, or -1 {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION} if not set.
193 public int getDefaultTransactionIsolation();
196 * If set to {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION} the method
197 * {@link java.sql.Connection#setTransactionIsolation(int)} will not be called during connection creation. Otherwise the method
198 * will be called with the isolation level set by this property.
199 * @param defaultTransactionIsolation a value of {@link java.sql.Connection#TRANSACTION_NONE}, {@link java.sql.Connection#TRANSACTION_READ_COMMITTED},
200 * {@link java.sql.Connection#TRANSACTION_READ_UNCOMMITTED}, {@link java.sql.Connection#TRANSACTION_REPEATABLE_READ},
201 * {@link java.sql.Connection#TRANSACTION_SERIALIZABLE} or {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION}
202 * The last value will not be set on the connection.
204 public void setDefaultTransactionIsolation(int defaultTransactionIsolation);
207 * 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
208 * @return fully qualified JDBC driver name.
210 public String getDriverClassName();
213 * 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
214 * @param driverClassName a fully qualified Java class name of a {@link java.sql.Driver} implementation.
216 public void setDriverClassName(String driverClassName);
219 * Returns the number of connections that will be established when the connection pool is started.
220 * Default value is 10
221 * @return number of connections to be started when pool is started
223 public int getInitialSize();
226 * Set the number of connections that will be established when the connection pool is started.
227 * Default value is 10.
228 * If this value exceeds {@link #setMaxActive(int)} it will automatically be lowered.
229 * @param initialSize the number of connections to be established.
232 public void setInitialSize(int initialSize);
235 * boolean flag to set if stack traces should be logged for application code which abandoned a Connection.
236 * Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated.
237 * The default value is false.
238 * @return true if the connection pool logs stack traces when connections are borrowed from the pool.
240 public boolean isLogAbandoned();
243 * boolean flag to set if stack traces should be logged for application code which abandoned a Connection.
244 * Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated.
245 * The default value is false.
246 * @param logAbandoned set to true if stack traces should be recorded when {@link DataSource#getConnection()} is called.
248 public void setLogAbandoned(boolean logAbandoned);
251 * The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100
252 * @return the maximum number of connections used by this pool
254 public int getMaxActive();
257 * The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100
258 * @param maxActive hard limit for number of managed connections by this pool
260 public void setMaxActive(int maxActive);
264 * The maximum number of connections that should be kept in the idle pool if {@link #isPoolSweeperEnabled()} returns false.
265 * If the If {@link #isPoolSweeperEnabled()} returns true, then the idle pool can grow up to {@link #getMaxActive}
266 * and will be shrunk according to {@link #getMinEvictableIdleTimeMillis()} setting.
267 * Default value is maxActive:100
268 * @return the maximum number of idle connections.
270 public int getMaxIdle();
273 * The maximum number of connections that should be kept in the idle pool if {@link #isPoolSweeperEnabled()} returns false.
274 * If the If {@link #isPoolSweeperEnabled()} returns true, then the idle pool can grow up to {@link #getMaxActive}
275 * and will be shrunk according to {@link #getMinEvictableIdleTimeMillis()} setting.
276 * Default value is maxActive:100
277 * @param maxIdle the maximum size of the idle pool
279 public void setMaxIdle(int maxIdle);
282 * The maximum number of milliseconds that the pool will wait (when there are no available connections and the
283 * {@link #getMaxActive} has been reached) for a connection to be returned
284 * before throwing an exception. Default value is 30000 (30 seconds)
285 * @return the number of milliseconds to wait for a connection to become available if the pool is maxed out.
287 public int getMaxWait();
290 * The maximum number of milliseconds that the pool will wait (when there are no available connections and the
291 * {@link #getMaxActive} has been reached) for a connection to be returned
292 * before throwing an exception. Default value is 30000 (30 seconds)
293 * @param maxWait the maximum number of milliseconds to wait.
295 public void setMaxWait(int maxWait);
298 * The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.
299 * The default value is 60000 (60 seconds).
300 * @return the minimum amount of idle time in milliseconds before a connection is considered idle and eligible for eviction.
302 public int getMinEvictableIdleTimeMillis();
305 * The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.
306 * The default value is 60000 (60 seconds).
307 * @param minEvictableIdleTimeMillis the number of milliseconds a connection must be idle to be eligible for eviction.
309 public void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis);
312 * The minimum number of established connections that should be kept in the pool at all times.
313 * The connection pool can shrink below this number if validation queries fail and connections get closed.
314 * Default value is derived from {@link #getInitialSize()} (also see {@link #setTestWhileIdle(boolean)}
315 * The idle pool will not shrink below this value during an eviction run, hence the number of actual connections
316 * can be between {@link #getMinIdle()} and somewhere between {@link #getMaxIdle()} and {@link #getMaxActive()}
317 * @return the minimum number of idle or established connections
319 public int getMinIdle();
322 * The minimum number of established connections that should be kept in the pool at all times.
323 * The connection pool can shrink below this number if validation queries fail and connections get closed.
324 * Default value is derived from {@link #getInitialSize()} (also see {@link #setTestWhileIdle(boolean)}
325 * The idle pool will not shrink below this value during an eviction run, hence the number of actual connections
326 * can be between {@link #getMinIdle()} and somewhere between {@link #getMaxIdle()} and {@link #getMaxActive()}
328 * @param minIdle the minimum number of idle or established connections
330 public void setMinIdle(int minIdle);
333 * Returns the name of the connection pool. By default a JVM unique random name is assigned.
334 * @return the name of the pool, should be unique in a JVM
336 public String getName();
339 * Sets the name of the connection pool
340 * @param name the name of the pool, should be unique in a runtime JVM
342 public void setName(String name);
346 * @return unknown value
348 public int getNumTestsPerEvictionRun();
352 * @param numTestsPerEvictionRun parameter ignored.
354 public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun);
357 * Returns the password used when establishing connections to the database.
358 * @return the password in string format
360 public String getPassword();
363 * Sets the password to establish the connection with.
364 * The password will be included as a database property with the name 'password'.
365 * @param password The password
366 * @see #getDbProperties()
368 public void setPassword(String password);
372 * @return the pool name
374 public String getPoolName();
377 * Returns the username used to establish the connection with
378 * @return the username used to establish the connection with
380 public String getUsername();
383 * Sets the username used to establish the connection with
384 * It will also be a property called 'user' in the database properties.
385 * @param username The user name
386 * @see #getDbProperties()
388 public void setUsername(String username);
392 * boolean flag to remove abandoned connections if they exceed the removeAbandonedTimout.
393 * If set to true a connection is considered abandoned and eligible for removal if it has
394 * been in use longer than the {@link #getRemoveAbandonedTimeout()} and the condition for
395 * {@link #getAbandonWhenPercentageFull()} is met.
396 * Setting this to true can recover db connections from applications that fail to close a connection.
397 * See also {@link #isLogAbandoned()} The default value is false.
398 * @return true if abandoned connections can be closed and expelled out of the pool
400 public boolean isRemoveAbandoned();
403 * boolean flag to remove abandoned connections if they exceed the removeAbandonedTimout.
404 * If set to true a connection is considered abandoned and eligible for removal if it has
405 * been in use longer than the {@link #getRemoveAbandonedTimeout()} and the condition for
406 * {@link #getAbandonWhenPercentageFull()} is met.
407 * Setting this to true can recover db connections from applications that fail to close a connection.
408 * See also {@link #isLogAbandoned()} The default value is false.
409 * @param removeAbandoned set to true if abandoned connections can be closed and expelled out of the pool
411 public void setRemoveAbandoned(boolean removeAbandoned);
414 * The time in seconds before a connection can be considered abandoned.
415 * The timer can be reset upon queries using an interceptor.
416 * @param removeAbandonedTimeout the time in seconds before a used connection can be considered abandoned
417 * @see org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer
419 public void setRemoveAbandonedTimeout(int removeAbandonedTimeout);
422 * The time in seconds before a connection can be considered abandoned.
423 * The timer can be reset upon queries using an interceptor.
424 * @see org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer
425 * @return the time in seconds before a used connection can be considered abandoned
427 public int getRemoveAbandonedTimeout();
430 * The indication of whether objects will be validated before being borrowed from the pool.
431 * If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.
432 * NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
433 * Default value is false
434 * In order to have a more efficient validation, see {@link #setValidationInterval(long)}
435 * @return true if the connection is to be validated upon borrowing a connection from the pool
436 * @see #getValidationInterval()
438 public boolean isTestOnBorrow();
441 * The indication of whether objects will be validated before being borrowed from the pool.
442 * If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.
443 * NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
444 * Default value is false
445 * In order to have a more efficient validation, see {@link #setValidationInterval(long)}
446 * @param testOnBorrow set to true if validation should take place before a connection is handed out to the application
447 * @see #getValidationInterval()
449 public void setTestOnBorrow(boolean testOnBorrow);
452 * The indication of whether objects will be validated after being returned to the pool.
453 * If the object fails to validate, it will be dropped from the pool.
454 * NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
455 * Default value is false
456 * In order to have a more efficient validation, see {@link #setValidationInterval(long)}
457 * @return true if validation should take place after a connection is returned to the pool
458 * @see #getValidationInterval()
460 public boolean isTestOnReturn();
463 * The indication of whether objects will be validated after being returned to the pool.
464 * If the object fails to validate, it will be dropped from the pool.
465 * NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
466 * Default value is false
467 * In order to have a more efficient validation, see {@link #setValidationInterval(long)}
468 * @param testOnReturn true if validation should take place after a connection is returned to the pool
469 * @see #getValidationInterval()
471 public void setTestOnReturn(boolean testOnReturn);
475 * Set to true if query validation should take place while the connection is idle.
476 * @return true if validation should take place during idle checks
477 * @see #setTimeBetweenEvictionRunsMillis(int)
479 public boolean isTestWhileIdle();
482 * Set to true if query validation should take place while the connection is idle.
483 * @param testWhileIdle true if validation should take place during idle checks
484 * @see #setTimeBetweenEvictionRunsMillis(int)
486 public void setTestWhileIdle(boolean testWhileIdle);
489 * The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner
490 * and idle pool resizing. This value should not be set under 1 second.
491 * It dictates how often we check for idle, abandoned connections, and how often we validate idle connection and resize the idle pool.
492 * The default value is 5000 (5 seconds)
493 * @return the sleep time in between validations in milliseconds
495 public int getTimeBetweenEvictionRunsMillis();
498 * The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner
499 * and idle pool resizing. This value should not be set under 1 second.
500 * It dictates how often we check for idle, abandoned connections, and how often we validate idle connection and resize the idle pool.
501 * The default value is 5000 (5 seconds)
502 * @param timeBetweenEvictionRunsMillis the sleep time in between validations in milliseconds
504 public void setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis);
507 * The URL used to connect to the database
508 * @return the configured URL for this connection pool
509 * @see java.sql.Driver#connect(String, Properties)
511 public String getUrl();
514 * Sets the URL used to connect to the database
515 * @param url the configured URL for this connection pool
516 * @see java.sql.Driver#connect(String, Properties)
518 public void setUrl(String url);
521 * The SQL query that will be used to validate connections from this
522 * pool before returning them to the caller or pool.
523 * If specified, this query does not have to return any data,
524 * it just can't throw a SQLException.
525 * The default value is null.
526 * Example values are SELECT 1(mysql),
527 * select 1 from dual(oracle),
528 * SELECT 1(MS Sql Server)
529 * @return the query used for validation or null if no validation is performed
531 public String getValidationQuery();
534 * The SQL query that will be used to validate connections from this
535 * pool before returning them to the caller or pool.
536 * If specified, this query does not have to return any data,
537 * it just can't throw a SQLException.
538 * The default value is null.
539 * Example values are SELECT 1(mysql),
540 * select 1 from dual(oracle),
541 * SELECT 1(MS Sql Server)
542 * @param validationQuery the query used for validation or null if no validation is performed
544 public void setValidationQuery(String validationQuery);
547 * The timeout in seconds before a connection validation queries fail.
548 * A value less than or equal to zero will disable this feature. Defaults to -1.
549 * @return the timeout value in seconds
551 public int getValidationQueryTimeout();
554 * The timeout in seconds before a connection validation queries fail.
555 * A value less than or equal to zero will disable this feature. Defaults to -1.
556 * @param validationQueryTimeout The timeout value
558 public void setValidationQueryTimeout(int validationQueryTimeout);
561 * Return the name of the optional validator class - may be null.
563 * @return the name of the optional validator class - may be null
565 public String getValidatorClassName();
568 * Set the name for an optional validator class which will be used in place of test queries. If set to
569 * null, standard validation will be used.
571 * @param className the name of the optional validator class
573 public void setValidatorClassName(String className);
576 * @return the optional validator object - may be null
578 public Validator getValidator();
581 * Sets the validator object
582 * If this is a non null object, it will be used as a validator instead of the validationQuery
583 * If this is null, remove the usage of the validator.
584 * @param validator The validator object
586 public void setValidator(Validator validator);
589 * avoid excess validation, only run validation at most at this frequency - time in milliseconds.
590 * If a connection is due for validation, but has been validated previously
591 * within this interval, it will not be validated again.
592 * The default value is 3000 (3 seconds).
593 * @return the validation interval in milliseconds
595 public long getValidationInterval();
598 * avoid excess validation, only run validation at most at this frequency - time in milliseconds.
599 * If a connection is due for validation, but has been validated previously
600 * within this interval, it will not be validated again.
601 * The default value is 3000 (3 seconds).
602 * @param validationInterval the validation interval in milliseconds
604 public void setValidationInterval(long validationInterval);
607 * A custom query to be run when a connection is first created. The default value is null.
608 * This query only runs once per connection, and that is when a new connection is established to the database.
609 * If this value is non null, it will replace the validation query during connection creation.
610 * @return the init SQL used to run against the DB or null if not set
612 public String getInitSQL();
615 * A custom query to be run when a connection is first created. The default value is null.
616 * This query only runs once per connection, and that is when a new connection is established to the database.
617 * If this value is non null, it will replace the validation query during connection creation.
618 * @param initSQL the init SQL used to run against the DB or null if no query should be executed
620 public void setInitSQL(String initSQL);
623 * Returns true if we should run the validation query when connecting to the database for the first time on a connection.
624 * Normally this is always set to false, unless one wants to use the validationQuery as an init query.
625 * @return true if we should run the validation query upon connect
627 public boolean isTestOnConnect();
630 * Set to true if we should run the validation query when connecting to the database for the first time on a connection.
631 * Normally this is always set to false, unless one wants to use the validationQuery as an init query.
632 * Setting an {@link #setInitSQL(String)} will override this setting, as the init SQL will be used instead of the validation query
633 * @param testOnConnect set to true if we should run the validation query upon connect
635 public void setTestOnConnect(boolean testOnConnect);
638 * A semicolon separated list of classnames extending {@link org.apache.tomcat.jdbc.pool.JdbcInterceptor} class.
639 * These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object.
640 * Example interceptors are {@link org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer StatementFinalizer} to close all
641 * used statements during the session.
642 * {@link org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer ResetAbandonedTimer} resets the timer upon every operation
643 * on the connection or a statement.
644 * {@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.
645 * The default value is null.
646 * @return the interceptors that are used for connections.
647 * Example format: 'ConnectionState(useEquals=true,fast=yes);ResetAbandonedTimer'
649 public String getJdbcInterceptors();
652 * A semicolon separated list of classnames extending {@link org.apache.tomcat.jdbc.pool.JdbcInterceptor} class.
653 * These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object.
654 * Example interceptors are {@link org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer StatementFinalizer} to close all
655 * used statements during the session.
656 * {@link org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer ResetAbandonedTimer} resets the timer upon every operation
657 * on the connection or a statement.
658 * {@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.
659 * The default value is null.
660 * @param jdbcInterceptors the interceptors that are used for connections.
661 * Example format: 'ConnectionState(useEquals=true,fast=yes);ResetAbandonedTimer'
663 public void setJdbcInterceptors(String jdbcInterceptors);
666 * Returns the {@link #getJdbcInterceptors()} as an array of objects with properties and the classes.
667 * @return an array of interceptors that have been configured
669 public InterceptorDefinition[] getJdbcInterceptorsAsArray();
673 * If set to true, the connection pool creates a {@link org.apache.tomcat.jdbc.pool.jmx.ConnectionPoolMBean} object
674 * that can be registered with JMX to receive notifications and state about the pool.
675 * The ConnectionPool object doesn't register itself, as there is no way to keep a static non changing ObjectName across JVM restarts.
676 * @return true if the mbean object will be created upon startup.
678 public boolean isJmxEnabled();
681 * If set to true, the connection pool creates a {@link org.apache.tomcat.jdbc.pool.jmx.ConnectionPoolMBean} object
682 * that can be registered with JMX to receive notifications and state about the pool.
683 * The ConnectionPool object doesn't register itself, as there is no way to keep a static non changing ObjectName across JVM restarts.
684 * @param jmxEnabled set to to if the mbean object should be created upon startup.
686 public void setJmxEnabled(boolean jmxEnabled);
689 * Returns true if the pool sweeper is enabled for the connection pool.
690 * The pool sweeper is enabled if any settings that require async intervention in the pool are turned on
692 boolean result = getTimeBetweenEvictionRunsMillis()>0;
693 result = result && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0);
694 result = result || (isTestWhileIdle() && getValidationQuery()!=null);
698 * @return true if a background thread is or will be enabled for this pool
700 public boolean isPoolSweeperEnabled();
703 * Set to true if you wish the <code>ProxyConnection</code> class to use <code>String.equals</code> instead of
704 * <code>==</code> when comparing method names.
705 * This property does not apply to added interceptors as those are configured individually.
706 * The default value is <code>false</code>.
707 * @return true if pool uses {@link String#equals(Object)} instead of == when comparing method names on {@link java.sql.Connection} methods
709 public boolean isUseEquals();
712 * Set to true if you wish the <code>ProxyConnection</code> class to use <code>String.equals</code> instead of
713 * <code>==</code> when comparing method names.
714 * This property does not apply to added interceptors as those are configured individually.
715 * The default value is <code>false</code>.
716 * @param useEquals set to true if the pool should use {@link String#equals(Object)} instead of ==
717 * when comparing method names on {@link java.sql.Connection} methods
719 public void setUseEquals(boolean useEquals);
722 * Time in milliseconds to keep this connection alive even when used.
723 * When a connection is returned to the pool, the pool will check to see if the
724 * ((now - time-when-connected) > maxAge) has been reached, and if so,
725 * it closes the connection rather than returning it to the pool.
726 * The default value is 0, which implies that connections will be left open and no
727 * age check will be done upon returning the connection to the pool.
728 * This is a useful setting for database sessions that leak memory as it ensures that the session
729 * will have a finite life span.
730 * @return the time in milliseconds a connection will be open for when used
732 public long getMaxAge();
735 * Time in milliseconds to keep this connection alive even when used.
736 * When a connection is returned to the pool, the pool will check to see if the
737 * ((now - time-when-connected) > maxAge) has been reached, and if so,
738 * it closes the connection rather than returning it to the pool.
739 * The default value is 0, which implies that connections will be left open and no
740 * age check will be done upon returning the connection to the pool.
741 * This is a useful setting for database sessions that leak memory as it ensures that the session
742 * will have a finite life span.
743 * @param maxAge the time in milliseconds a connection will be open for when used
745 public void setMaxAge(long maxAge);
748 * Return true if a lock should be used when operations are performed on the connection object.
749 * Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking
750 * such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting.
751 * @return true if a lock is used.
753 public boolean getUseLock();
756 * Set to true if a lock should be used when operations are performed on the connection object.
757 * Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking
758 * such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting.
759 * @param useLock set to true if a lock should be used on connection operations
761 public void setUseLock(boolean useLock);
764 * Similar to {@link #setRemoveAbandonedTimeout(int)} but instead of treating the connection
765 * as abandoned, and potentially closing the connection, this simply logs the warning if
766 * {@link #isLogAbandoned()} returns true. If this value is equal or less than 0, no suspect
767 * checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and
768 * the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets
769 * logged and a JMX notification gets sent once.
770 * @param seconds - the amount of time in seconds that has to pass before a connection is marked suspect.
772 public void setSuspectTimeout(int seconds);
775 * Returns the time in seconds to pass before a connection is marked an abandoned suspect.
776 * Any value lesser than or equal to 0 means the check is disabled.
777 * @return Returns the time in seconds to pass before a connection is marked an abandoned suspect.
779 public int getSuspectTimeout();
782 * Injects a datasource that will be used to retrieve/create connections.
783 * If a data source is set, the {@link PoolConfiguration#getUrl()} and {@link PoolConfiguration#getDriverClassName()} methods are ignored
784 * and not used by the pool. If the {@link PoolConfiguration#getUsername()} and {@link PoolConfiguration#getPassword()}
785 * values are set, the method {@link javax.sql.DataSource#getConnection(String, String)} method will be called instead of the
786 * {@link javax.sql.DataSource#getConnection()} method.
787 * If the data source implements {@link javax.sql.XADataSource} the methods
788 * {@link javax.sql.XADataSource#getXAConnection()} and {@link javax.sql.XADataSource#getXAConnection(String,String)}
790 * @param ds the {@link javax.sql.DataSource} to be used for creating connections to be pooled.
792 public void setDataSource(Object ds);
795 * Returns a datasource, if one exists that is being used to create connections.
796 * This method will return null if the pool is using a {@link java.sql.Driver}
797 * @return the {@link javax.sql.DataSource} to be used for creating connections to be pooled or null if a Driver is used.
799 public Object getDataSource();
802 * Configure the connection pool to use a DataSource according to {@link PoolConfiguration#setDataSource(Object)}
803 * But instead of injecting the object, specify the JNDI location.
804 * After a successful JNDI look, the {@link PoolConfiguration#getDataSource()} will not return null.
805 * @param jndiDS -the JNDI string @TODO specify the rules here.
807 public void setDataSourceJNDI(String jndiDS);
810 * Returns the JNDI string configured for data source usage.
811 * @return the JNDI string or null if not set
813 public String getDataSourceJNDI();
816 * Returns true if the call {@link DataSource#getConnection(String, String) getConnection(username,password)} is
817 * allowed. This is used for when the pool is used by an application accessing multiple schemas.
818 * There is a performance impact turning this option on.
819 * @return true if {@link DataSource#getConnection(String, String) getConnection(username,password)} is honored, false if it is ignored.
821 public boolean isAlternateUsernameAllowed();
824 * Set to true if the call {@link DataSource#getConnection(String, String) getConnection(username,password)} is
825 * allowed and honored.. This is used for when the pool is used by an application accessing multiple schemas.
826 * There is a performance impact turning this option on, even when not used due to username checks.
827 * @param alternateUsernameAllowed - set true if {@link DataSource#getConnection(String, String) getConnection(username,password)} is honored,
828 * false if it is to be ignored.
830 public void setAlternateUsernameAllowed(boolean alternateUsernameAllowed);
832 * Set to true if you want the connection pool to commit any pending transaction when a connection is returned.
833 * The default value is false, as this could result in committing data.
834 * This parameter is only looked at if the {@link #getDefaultAutoCommit()} returns false
835 * @param commitOnReturn set to true if the pool should call {@link java.sql.Connection#commit()} when a connection is returned to the pool.
838 public void setCommitOnReturn(boolean commitOnReturn);
841 * @see PoolConfiguration#setCommitOnReturn(boolean)
842 * @return <code>true</code> if the pool should commit when a connection is returned to it
844 public boolean getCommitOnReturn();
847 * Set to true if you want the connection pool to rollback any pending transaction when a connection is returned.
848 * The default value is false, as this could result in committing data.
849 * This parameter is only looked at if the {@link #getDefaultAutoCommit()} returns false
850 * @param rollbackOnReturn set to true if the pool should call {@link java.sql.Connection#rollback()} when a connection is returned to the pool.
853 public void setRollbackOnReturn(boolean rollbackOnReturn);
856 * @see PoolConfiguration#setRollbackOnReturn(boolean)
857 * @return <code>true</code> if the pool should rollback when a connection is returned to it
859 public boolean getRollbackOnReturn();
862 * If set to <code>true</code>, the connection will be wrapped with facade that will disallow the connection to be used after
863 * {@link java.sql.Connection#close()} is called. If set to <code>true</code>, after {@link java.sql.Connection#close()} all calls except
864 * {@link java.sql.Connection#close()} and {@link java.sql.Connection#isClosed()} will throw an exception.
865 * @param useDisposableConnectionFacade <code>true</code> to use a facade
867 public void setUseDisposableConnectionFacade(boolean useDisposableConnectionFacade);
869 * Returns <code>true</code> if this connection pool is configured to use a connection facade to prevent re-use of connection after
870 * {@link java.sql.Connection#close()} has been invoked
871 * @return <code>true</code> if {@link java.sql.Connection#close()} has been invoked.
873 public boolean getUseDisposableConnectionFacade();
876 * Set to true if you wish that errors from validation should be logged as error messages.
877 * @param logValidationErrors set to true to log validation errors
879 public void setLogValidationErrors(boolean logValidationErrors);
882 * Returns true if errors that happen during validation will be logged
883 * @return true if errors that happen during validation will be logged
885 public boolean getLogValidationErrors();
888 * Returns true if the pool is configured to propagate interrupt state of a thread.
889 * A thread waiting for a connection, can have its wait interrupted, and by default
890 * will clear the interrupt flag and throw a {@link PoolExhaustedException}
891 * @return true if the pool is configured to propagate and not clear the thread interrupt state
893 public boolean getPropagateInterruptState();
896 * Configure the pool to propagate interrupt state for interrupted threads waiting for a connection
897 * A thread waiting for a connection, can have its wait interrupted, and by default
898 * will clear the interrupt flag and throw a {@link PoolExhaustedException}
899 * If set to true, this behavior will change, while the {@link PoolExhaustedException} is still thrown, the threads interrupted state is still set.
900 * @param propagateInterruptState - set to true to not clear, but propagate, a threads interrupted state.
902 public void setPropagateInterruptState(boolean propagateInterruptState);
905 * Set to true if you want to ignore error of connection creation while initializing the pool.
906 * Set to false if you want to fail the initialization of the pool by throwing exception.
907 * @param ignoreExceptionOnPreLoad set to true if you want to ignore error of connection creation while initializing the pool.
909 public void setIgnoreExceptionOnPreLoad(boolean ignoreExceptionOnPreLoad);
912 * @return <code>true</code> to ignore exceptions
913 * @see PoolConfiguration#setIgnoreExceptionOnPreLoad(boolean)
915 public boolean isIgnoreExceptionOnPreLoad();