2
* Licensed to the Apache Software Foundation (ASF) under one or more
3
* contributor license agreements. See the NOTICE file distributed with
4
* this work for additional information regarding copyright ownership.
5
* The ASF licenses this file to You under the Apache License, Version 2.0
6
* (the "License"); you may not use this file except in compliance with
7
* the License. You may obtain a copy of the License at
9
* http://www.apache.org/licenses/LICENSE-2.0
11
* Unless required by applicable law or agreed to in writing, software
12
* distributed under the License is distributed on an "AS IS" BASIS,
13
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
* See the License for the specific language governing permissions and
15
* limitations under the License.
17
package org.apache.tomcat.jdbc.pool;
19
import java.util.Properties;
21
import org.apache.tomcat.jdbc.pool.PoolProperties.InterceptorDefinition;
24
* A list of properties that are configurable for a connection pool.
25
* The {@link DataSource} object also implements this interface so that it can be easily configured through
26
* an IoC container without having to specify a secondary object with a setter method.
31
public interface PoolConfiguration {
34
* JMX prefix for interceptors that register themselves with JMX
36
public static final String PKG_PREFIX = "org.apache.tomcat.jdbc.pool.interceptor.";
39
* Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are
40
* above the percentage defined by abandonWhenPercentageFull.
41
* The value should be between 0-100.
42
* The default value is 0, which implies that connections are eligible for
43
* closure as soon as removeAbandonedTimeout has been reached.
44
* @param percentage a value between 0 and 100 to indicate when connections that have been abandoned/timed out are considered abandoned
46
public void setAbandonWhenPercentageFull(int percentage);
49
* Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are
50
* above the percentage defined by abandonWhenPercentageFull.
51
* The value should be between 0-100.
52
* The default value is 0, which implies that connections are eligible for
53
* closure as soon as removeAbandonedTimeout has been reached.
54
* @return percentage - a value between 0 and 100 to indicate when connections that have been abandoned/timed out are considered abandoned
56
public int getAbandonWhenPercentageFull();
59
* Returns true if a fair queue is being used by the connection pool
60
* @return true if a fair waiting queue is being used
62
public boolean isFairQueue();
65
* Set to true if you wish that calls to getConnection
66
* should be treated fairly in a true FIFO fashion.
67
* This uses the {@link FairBlockingQueue} implementation for the list of the idle connections.
68
* The default value is true.
69
* This flag is required when you want to use asynchronous connection retrieval.
72
public void setFairQueue(boolean fairQueue);
75
* Property not used. Access is always allowed.
76
* Access can be achieved by calling unwrap on the pooled connection. see {@link javax.sql.DataSource} interface
77
* or call getConnection through reflection or cast the object as {@link javax.sql.PooledConnection}
80
public boolean isAccessToUnderlyingConnectionAllowed();
84
* @param accessToUnderlyingConnectionAllowed parameter ignored
86
public void setAccessToUnderlyingConnectionAllowed(boolean accessToUnderlyingConnectionAllowed);
89
* The connection properties that will be sent to the JDBC driver when establishing new connections.
90
* Format of the string is [propertyName=property;] <br/>
91
* NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here.
92
* The default value is null.
94
public String getConnectionProperties();
97
* The properties that will be passed into {@link java.sql.Driver#connect(String, Properties)} method.
98
* Username and password do not need to be stored here, they will be passed into the properties right before the connection is established.
99
* @param connectionProperties properties - Format of the string is [propertyName=property;]*
100
* Example: prop1=value1;prop2=value2
102
public void setConnectionProperties(String connectionProperties);
105
* Returns the database properties that are passed into the {@link java.sql.Driver#connect(String, Properties)} method.
106
* @return database properties that are passed into the {@link java.sql.Driver#connect(String, Properties)} method.
108
public Properties getDbProperties();
111
* Overrides the database properties passed into the {@link java.sql.Driver#connect(String, Properties)} method.
112
* @param dbProperties
114
public void setDbProperties(Properties dbProperties);
117
* The default auto-commit state of connections created by this pool.
118
* 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.)
119
* @return the default auto commit setting, null is Driver default.
121
public Boolean isDefaultAutoCommit();
124
* The default auto-commit state of connections created by this pool.
125
* 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.)
126
* @return the default auto commit setting, null is Driver default.
128
public Boolean getDefaultAutoCommit();
131
* The default auto-commit state of connections created by this pool.
132
* 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.)
133
* @param defaultAutoCommit default auto commit setting, null is Driver default.
135
public void setDefaultAutoCommit(Boolean defaultAutoCommit);
138
* If non null, during connection creation the method {@link java.sql.Connection#setCatalog(String)} will be called with the set value.
139
* @return the default catalog, null if not set and accepting the driver default.
141
public String getDefaultCatalog();
144
* If non null, during connection creation the method {@link java.sql.Connection#setCatalog(String)} will be called with the set value.
145
* @param defaultCatalog null if not set and accepting the driver default.
147
public void setDefaultCatalog(String defaultCatalog);
150
* If non null, during connection creation the method {@link java.sql.Connection#setReadOnly(boolean)} will be called with the set value.
151
* @return null if not set and accepting the driver default otherwise the read only value
153
public Boolean isDefaultReadOnly();
156
* If non null, during connection creation the method {@link java.sql.Connection#setReadOnly(boolean)} will be called with the set value.
157
* @return null if not set and accepting the driver default otherwise the read only value
159
public Boolean getDefaultReadOnly();
162
* If non null, during connection creation the method {@link java.sql.Connection#setReadOnly(boolean)} will be called with the set value.
163
* @param defaultReadOnly null if not set and accepting the driver default.
165
public void setDefaultReadOnly(Boolean defaultReadOnly);
169
* Returns the default transaction isolation level. If set to {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION} the method
170
* {@link java.sql.Connection#setTransactionIsolation(int)} will not be called during connection creation.
171
* @return driver transaction isolation level, or -1 {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION} if not set.
173
public int getDefaultTransactionIsolation();
176
* If set to {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION} the method
177
* {@link java.sql.Connection#setTransactionIsolation(int)} will not be called during connection creation. Otherwise the method
178
* will be called with the isolation level set by this property.
179
* @param defaultTransactionIsolation a value of {@link java.sql.Connection#TRANSACTION_NONE}, {@link java.sql.Connection#TRANSACTION_READ_COMMITTED},
180
* {@link java.sql.Connection#TRANSACTION_READ_UNCOMMITTED}, {@link java.sql.Connection#TRANSACTION_REPEATABLE_READ},
181
* {@link java.sql.Connection#TRANSACTION_SERIALIZABLE} or {@link DataSourceFactory#UNKNOWN_TRANSACTIONISOLATION}
182
* The last value will not be set on the connection.
184
public void setDefaultTransactionIsolation(int defaultTransactionIsolation);
187
* 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
188
* @return fully qualified JDBC driver name.
190
public String getDriverClassName();
193
* 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
194
* @param driverClassName a fully qualified Java class name of a {@link java.sql.Driver} implementation.
196
public void setDriverClassName(String driverClassName);
199
* Returns the number of connections that will be established when the connection pool is started.
200
* Default value is 10
201
* @return number of connections to be started when pool is started
203
public int getInitialSize();
206
* Set the number of connections that will be established when the connection pool is started.
207
* Default value is 10.
208
* If this value exceeds {@link #setMaxActive(int)} it will automatically be lowered.
209
* @param initialSize the number of connections to be established.
212
public void setInitialSize(int initialSize);
215
* boolean flag to set if stack traces should be logged for application code which abandoned a Connection.
216
* Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated.
217
* The default value is false.
218
* @return true if the connection pool logs stack traces when connections are borrowed from the pool.
220
public boolean isLogAbandoned();
223
* boolean flag to set if stack traces should be logged for application code which abandoned a Connection.
224
* Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated.
225
* The default value is false.
226
* @param logAbandoned set to true if stack traces should be recorded when {@link DataSource#getConnection()} is called.
228
public void setLogAbandoned(boolean logAbandoned);
231
* The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100
232
* @return the maximum number of connections used by this pool
234
public int getMaxActive();
237
* The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100
238
* @param maxActive hard limit for number of managed connections by this pool
240
public void setMaxActive(int maxActive);
244
* The maximum number of connections that should be kept in the idle pool if {@link #isPoolSweeperEnabled()} returns false.
245
* If the If {@link #isPoolSweeperEnabled()} returns true, then the idle pool can grow up to {@link #getMaxActive}
246
* and will be shrunk according to {@link #getMinEvictableIdleTimeMillis()} setting.
247
* Default value is maxActive:100
248
* @return the maximum number of idle connections.
250
public int getMaxIdle();
253
* The maximum number of connections that should be kept in the idle pool if {@link #isPoolSweeperEnabled()} returns false.
254
* If the If {@link #isPoolSweeperEnabled()} returns true, then the idle pool can grow up to {@link #getMaxActive}
255
* and will be shrunk according to {@link #getMinEvictableIdleTimeMillis()} setting.
256
* Default value is maxActive:100
257
* @param maxIdle the maximum size of the idle pool
259
public void setMaxIdle(int maxIdle);
262
* The maximum number of milliseconds that the pool will wait (when there are no available connections and the
263
* {@link #getMaxActive} has been reached) for a connection to be returned
264
* before throwing an exception. Default value is 30000 (30 seconds)
265
* @return the number of milliseconds to wait for a connection to become available if the pool is maxed out.
267
public int getMaxWait();
270
* The maximum number of milliseconds that the pool will wait (when there are no available connections and the
271
* {@link #getMaxActive} has been reached) for a connection to be returned
272
* before throwing an exception. Default value is 30000 (30 seconds)
273
* @param maxWait the maximum number of milliseconds to wait.
275
public void setMaxWait(int maxWait);
278
* The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.
279
* The default value is 60000 (60 seconds).
280
* @return the minimum amount of idle time in milliseconds before a connection is considered idle and eligible for eviction.
282
public int getMinEvictableIdleTimeMillis();
285
* The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.
286
* The default value is 60000 (60 seconds).
287
* @param minEvictableIdleTimeMillis the number of milliseconds a connection must be idle to be eligible for eviction.
289
public void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis);
292
* The minimum number of established connections that should be kept in the pool at all times.
293
* The connection pool can shrink below this number if validation queries fail and connections get closed.
294
* Default value is derived from {@link #getInitialSize()} (also see {@link #setTestWhileIdle(boolean)}
295
* The idle pool will not shrink below this value during an eviction run, hence the number of actual connections
296
* can be between {@link #getMinIdle()} and somewhere between {@link #getMaxIdle()} and {@link #getMaxActive()}
297
* @return the minimum number of idle or established connections
299
public int getMinIdle();
302
* The minimum number of established connections that should be kept in the pool at all times.
303
* The connection pool can shrink below this number if validation queries fail and connections get closed.
304
* Default value is derived from {@link #getInitialSize()} (also see {@link #setTestWhileIdle(boolean)}
305
* The idle pool will not shrink below this value during an eviction run, hence the number of actual connections
306
* can be between {@link #getMinIdle()} and somewhere between {@link #getMaxIdle()} and {@link #getMaxActive()}
308
* @param minIdle the minimum number of idle or established connections
310
public void setMinIdle(int minIdle);
313
* Returns the name of the connection pool. By default a JVM unique random name is assigned.
314
* @return the name of the pool, should be unique in a JVM
316
public String getName();
319
* Sets the name of the connection pool
320
* @param name the name of the pool, should be unique in a runtime JVM
322
public void setName(String name);
326
* @return unknown value
328
public int getNumTestsPerEvictionRun();
332
* @param numTestsPerEvictionRun parameter ignored.
334
public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun);
337
* Returns the password used when establishing connections to the database.
338
* @return the password in string format
340
public String getPassword();
343
* Sets the password to establish the connection with.
344
* The password will be included as a database property with the name 'password'.
346
* @see #getDbProperties()
348
public void setPassword(String password);
354
public String getPoolName();
357
* Returns the username used to establish the connection with
358
* @return the username used to establish the connection with
360
public String getUsername();
363
* Sets the username used to establish the connection with
364
* It will also be a property called 'user' in the database properties.
366
* @see #getDbProperties()
368
public void setUsername(String username);
372
* boolean flag to remove abandoned connections if they exceed the removeAbandonedTimout.
373
* If set to true a connection is considered abandoned and eligible for removal if it has
374
* been in use longer than the {@link #getRemoveAbandonedTimeout()} and the condition for
375
* {@link #getAbandonWhenPercentageFull()} is met.
376
* Setting this to true can recover db connections from applications that fail to close a connection.
377
* See also {@link #isLogAbandoned()} The default value is false.
378
* @return true if abandoned connections can be closed and expelled out of the pool
380
public boolean isRemoveAbandoned();
383
* boolean flag to remove abandoned connections if they exceed the removeAbandonedTimout.
384
* If set to true a connection is considered abandoned and eligible for removal if it has
385
* been in use longer than the {@link #getRemoveAbandonedTimeout()} and the condition for
386
* {@link #getAbandonWhenPercentageFull()} is met.
387
* Setting this to true can recover db connections from applications that fail to close a connection.
388
* See also {@link #isLogAbandoned()} The default value is false.
389
* @param removeAbandoned set to true if abandoned connections can be closed and expelled out of the pool
391
public void setRemoveAbandoned(boolean removeAbandoned);
394
* The time in seconds before a connection can be considered abandoned.
395
* The timer can be reset upon queries using an interceptor.
396
* @param removeAbandonedTimeout the time in seconds before a used connection can be considered abandoned
397
* @see org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer
399
public void setRemoveAbandonedTimeout(int removeAbandonedTimeout);
402
* The time in seconds before a connection can be considered abandoned.
403
* The timer can be reset upon queries using an interceptor.
404
* @see org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer
405
* @return the time in seconds before a used connection can be considered abandoned
407
public int getRemoveAbandonedTimeout();
410
* The indication of whether objects will be validated before being borrowed from the pool.
411
* If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.
412
* NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
413
* Default value is false
414
* In order to have a more efficient validation, see {@link #setValidationInterval(long)}
415
* @return true if the connection is to be validated upon borrowing a connection from the pool
416
* @see #getValidationInterval()
418
public boolean isTestOnBorrow();
421
* The indication of whether objects will be validated before being borrowed from the pool.
422
* If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.
423
* NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
424
* Default value is false
425
* In order to have a more efficient validation, see {@link #setValidationInterval(long)}
426
* @param testOnBorrow set to true if validation should take place before a connection is handed out to the application
427
* @see #getValidationInterval()
429
public void setTestOnBorrow(boolean testOnBorrow);
432
* The indication of whether objects will be validated after being returned to the pool.
433
* If the object fails to validate, it will be dropped from the pool.
434
* NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
435
* Default value is false
436
* In order to have a more efficient validation, see {@link #setValidationInterval(long)}
437
* @return true if validation should take place after a connection is returned to the pool
438
* @see #getValidationInterval()
440
public boolean isTestOnReturn();
443
* The indication of whether objects will be validated after being returned to the pool.
444
* If the object fails to validate, it will be dropped from the pool.
445
* NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
446
* Default value is false
447
* In order to have a more efficient validation, see {@link #setValidationInterval(long)}
448
* @param testOnReturn true if validation should take place after a connection is returned to the pool
449
* @see #getValidationInterval()
451
public void setTestOnReturn(boolean testOnReturn);
455
* Set to true if query validation should take place while the connection is idle.
456
* @return true if validation should take place during idle checks
457
* @see #setTimeBetweenEvictionRunsMillis(int)
459
public boolean isTestWhileIdle();
462
* Set to true if query validation should take place while the connection is idle.
463
* @param testWhileIdle true if validation should take place during idle checks
464
* @see #setTimeBetweenEvictionRunsMillis(int)
466
public void setTestWhileIdle(boolean testWhileIdle);
469
* The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner
470
* and idle pool resizing. This value should not be set under 1 second.
471
* It dictates how often we check for idle, abandoned connections, and how often we validate idle connection and resize the idle pool.
472
* The default value is 5000 (5 seconds)
473
* @return the sleep time in between validations in milliseconds
475
public int getTimeBetweenEvictionRunsMillis();
478
* The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner
479
* and idle pool resizing. This value should not be set under 1 second.
480
* It dictates how often we check for idle, abandoned connections, and how often we validate idle connection and resize the idle pool.
481
* The default value is 5000 (5 seconds)
482
* @param timeBetweenEvictionRunsMillis the sleep time in between validations in milliseconds
484
public void setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis);
487
* The URL used to connect to the database
488
* @return the configured URL for this connection pool
489
* @see java.sql.Driver#connect(String, Properties)
491
public String getUrl();
494
* Sets the URL used to connect to the database
495
* @param url the configured URL for this connection pool
496
* @see java.sql.Driver#connect(String, Properties)
498
public void setUrl(String url);
501
* The SQL query that will be used to validate connections from this
502
* pool before returning them to the caller or pool.
503
* If specified, this query does not have to return any data,
504
* it just can't throw a SQLException.
505
* The default value is null.
506
* Example values are SELECT 1(mysql),
507
* select 1 from dual(oracle),
508
* SELECT 1(MS Sql Server)
509
* @return the query used for validation or null if no validation is performed
511
public String getValidationQuery();
514
* The SQL query that will be used to validate connections from this
515
* pool before returning them to the caller or pool.
516
* If specified, this query does not have to return any data,
517
* it just can't throw a SQLException.
518
* The default value is null.
519
* Example values are SELECT 1(mysql),
520
* select 1 from dual(oracle),
521
* SELECT 1(MS Sql Server)
522
* @param validationQuery the query used for validation or null if no validation is performed
524
public void setValidationQuery(String validationQuery);
527
* Return the name of the optional validator class - may be null.
529
* @return the name of the optional validator class - may be null
531
public String getValidatorClassName();
534
* Set the name for an optional validator class which will be used in place of test queries. If set to
535
* null, standard validation will be used.
537
* @param className the name of the optional validator class
539
public void setValidatorClassName(String className);
542
* @return the optional validator object - may be null
544
public Validator getValidator();
547
* Sets the validator object
548
* If this is a non null object, it will be used as a validator instead of the validationQuery
549
* If this is null, remove the usage of the validator.
551
public void setValidator(Validator validator);
554
* avoid excess validation, only run validation at most at this frequency - time in milliseconds.
555
* If a connection is due for validation, but has been validated previously
556
* within this interval, it will not be validated again.
557
* The default value is 30000 (30 seconds).
558
* @return the validation interval in milliseconds
560
public long getValidationInterval();
563
* avoid excess validation, only run validation at most at this frequency - time in milliseconds.
564
* If a connection is due for validation, but has been validated previously
565
* within this interval, it will not be validated again.
566
* The default value is 30000 (30 seconds).
567
* @param validationInterval the validation interval in milliseconds
569
public void setValidationInterval(long validationInterval);
572
* A custom query to be run when a connection is first created. The default value is null.
573
* This query only runs once per connection, and that is when a new connection is established to the database.
574
* If this value is non null, it will replace the validation query during connection creation.
575
* @return the init SQL used to run against the DB or null if not set
577
public String getInitSQL();
580
* A custom query to be run when a connection is first created. The default value is null.
581
* This query only runs once per connection, and that is when a new connection is established to the database.
582
* If this value is non null, it will replace the validation query during connection creation.
583
* @param initSQL the init SQL used to run against the DB or null if no query should be executed
585
public void setInitSQL(String initSQL);
588
* Returns true if we should run the validation query when connecting to the database for the first time on a connection.
589
* Normally this is always set to false, unless one wants to use the validationQuery as an init query.
590
* @return true if we should run the validation query upon connect
592
public boolean isTestOnConnect();
595
* Set to true if we should run the validation query when connecting to the database for the first time on a connection.
596
* Normally this is always set to false, unless one wants to use the validationQuery as an init query.
597
* Setting an {@link #setInitSQL(String)} will override this setting, as the init SQL will be used instead of the validation query
598
* @param testOnConnect set to true if we should run the validation query upon connect
600
public void setTestOnConnect(boolean testOnConnect);
603
* A semicolon separated list of classnames extending {@link org.apache.tomcat.jdbc.pool.JdbcInterceptor} class.
604
* These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object.
605
* Example interceptors are {@link org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer StatementFinalizer} to close all
606
* used statements during the session.
607
* {@link org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer ResetAbandonedTimer} resets the timer upon every operation
608
* on the connection or a statement.
609
* {@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.
610
* The default value is null.
611
* @return the interceptors that are used for connections.
612
* Example format: 'ConnectionState(useEquals=true,fast=yes);ResetAbandonedTimer'
614
public String getJdbcInterceptors();
617
* A semicolon separated list of classnames extending {@link org.apache.tomcat.jdbc.pool.JdbcInterceptor} class.
618
* These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object.
619
* Example interceptors are {@link org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer StatementFinalizer} to close all
620
* used statements during the session.
621
* {@link org.apache.tomcat.jdbc.pool.interceptor.ResetAbandonedTimer ResetAbandonedTimer} resets the timer upon every operation
622
* on the connection or a statement.
623
* {@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.
624
* The default value is null.
625
* @param jdbcInterceptors the interceptors that are used for connections.
626
* Example format: 'ConnectionState(useEquals=true,fast=yes);ResetAbandonedTimer'
628
public void setJdbcInterceptors(String jdbcInterceptors);
631
* Returns the {@link #getJdbcInterceptors()} as an array of objects with properties and the classes.
632
* @return an array of interceptors that have been configured
634
public InterceptorDefinition[] getJdbcInterceptorsAsArray();
638
* If set to true, the connection pool creates a {@link org.apache.tomcat.jdbc.pool.jmx.ConnectionPoolMBean} object
639
* that can be registered with JMX to receive notifications and state about the pool.
640
* The ConnectionPool object doesn't register itself, as there is no way to keep a static non changing ObjectName across JVM restarts.
641
* @return true if the mbean object will be created upon startup.
643
public boolean isJmxEnabled();
646
* If set to true, the connection pool creates a {@link org.apache.tomcat.jdbc.pool.jmx.ConnectionPoolMBean} object
647
* that can be registered with JMX to receive notifications and state about the pool.
648
* The ConnectionPool object doesn't register itself, as there is no way to keep a static non changing ObjectName across JVM restarts.
649
* @param jmxEnabled set to to if the mbean object should be created upon startup.
651
public void setJmxEnabled(boolean jmxEnabled);
654
* Returns true if the pool sweeper is enabled for the connection pool.
655
* The pool sweeper is enabled if any settings that require async intervention in the pool are turned on
657
boolean result = getTimeBetweenEvictionRunsMillis()>0;
658
result = result && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0);
659
result = result || (isTestWhileIdle() && getValidationQuery()!=null);
663
* @return true if a background thread is or will be enabled for this pool
665
public boolean isPoolSweeperEnabled();
668
* Set to true if you wish the <code>ProxyConnection</code> class to use <code>String.equals</code> instead of
669
* <code>==</code> when comparing method names.
670
* This property does not apply to added interceptors as those are configured individually.
671
* The default value is <code>false</code>.
672
* @return true if pool uses {@link String#equals(Object)} instead of == when comparing method names on {@link java.sql.Connection} methods
674
public boolean isUseEquals();
677
* Set to true if you wish the <code>ProxyConnection</code> class to use <code>String.equals</code> instead of
678
* <code>==</code> when comparing method names.
679
* This property does not apply to added interceptors as those are configured individually.
680
* The default value is <code>false</code>.
681
* @param useEquals set to true if the pool should use {@link String#equals(Object)} instead of ==
682
* when comparing method names on {@link java.sql.Connection} methods
684
public void setUseEquals(boolean useEquals);
687
* Time in milliseconds to keep this connection alive even when used.
688
* When a connection is returned to the pool, the pool will check to see if the
689
* ((now - time-when-connected) > maxAge) has been reached, and if so,
690
* it closes the connection rather than returning it to the pool.
691
* The default value is 0, which implies that connections will be left open and no
692
* age check will be done upon returning the connection to the pool.
693
* This is a useful setting for database sessions that leak memory as it ensures that the session
694
* will have a finite life span.
695
* @return the time in milliseconds a connection will be open for when used
697
public long getMaxAge();
700
* Time in milliseconds to keep this connection alive even when used.
701
* When a connection is returned to the pool, the pool will check to see if the
702
* ((now - time-when-connected) > maxAge) has been reached, and if so,
703
* it closes the connection rather than returning it to the pool.
704
* The default value is 0, which implies that connections will be left open and no
705
* age check will be done upon returning the connection to the pool.
706
* This is a useful setting for database sessions that leak memory as it ensures that the session
707
* will have a finite life span.
708
* @param maxAge the time in milliseconds a connection will be open for when used
710
public void setMaxAge(long maxAge);
713
* Return true if a lock should be used when operations are performed on the connection object.
714
* Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking
715
* such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting.
716
* @return true if a lock is used.
718
public boolean getUseLock();
721
* Set to true if a lock should be used when operations are performed on the connection object.
722
* Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking
723
* such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting.
724
* @param useLock set to true if a lock should be used on connection operations
726
public void setUseLock(boolean useLock);
729
* Similar to {@link #setRemoveAbandonedTimeout(int)} but instead of treating the connection
730
* as abandoned, and potentially closing the connection, this simply logs the warning if
731
* {@link #isLogAbandoned()} returns true. If this value is equal or less than 0, no suspect
732
* checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and
733
* the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets
734
* logged and a JMX notification gets sent once.
735
* @param seconds - the amount of time in seconds that has to pass before a connection is marked suspect.
737
public void setSuspectTimeout(int seconds);
740
* Returns the time in seconds to pass before a connection is marked an abanoned suspect.
741
* Any value lesser than or equal to 0 means the check is disabled.
742
* @return Returns the time in seconds to pass before a connection is marked an abanoned suspect.
744
public int getSuspectTimeout();
747
* Injects a datasource that will be used to retrieve/create connections.
748
* If a data source is set, the {@link PoolConfiguration#getUrl()} and {@link PoolConfiguration#getDriverClassName()} methods are ignored
749
* and not used by the pool. If the {@link PoolConfiguration#getUsername()} and {@link PoolConfiguration#getPassword()}
750
* values are set, the method {@link javax.sql.DataSource#getConnection(String, String)} method will be called instead of the
751
* {@link javax.sql.DataSource#getConnection()} method.
752
* If the data source implements {@link javax.sql.XADataSource} the methods
753
* {@link javax.sql.XADataSource#getXAConnection()} and {@link javax.sql.XADataSource#getXAConnection(String,String)}
755
* @param ds the {@link javax.sql.DataSource} to be used for creating connections to be pooled.
757
public void setDataSource(Object ds);
760
* Returns a datasource, if one exists that is being used to create connections.
761
* This method will return null if the pool is using a {@link java.sql.Driver}
762
* @return the {@link javax.sql.DataSource} to be used for creating connections to be pooled or null if a Driver is used.
764
public Object getDataSource();
767
* Configure the connection pool to use a DataSource according to {@link PoolConfiguration#setDataSource(Object)}
768
* But instead of injecting the object, specify the JNDI location.
769
* After a successful JNDI look, the {@link PoolConfiguration#getDataSource()} will not return null.
770
* @param jndiDS -the JNDI string @TODO specify the rules here.
772
public void setDataSourceJNDI(String jndiDS);
775
* Returns the JNDI string configured for data source usage.
776
* @return the JNDI string or null if not set
778
public String getDataSourceJNDI();
781
* Returns true if the call {@link DataSource#getConnection(String, String) getConnection(username,password)} is
782
* allowed. This is used for when the pool is used by an application accessing multiple schemas.
783
* There is a performance impact turning this option on.
784
* @return true if {@link DataSource#getConnection(String, String) getConnection(username,password)} is honored, false if it is ignored.
786
public boolean isAlternateUsernameAllowed();
789
* Set to true if the call {@link DataSource#getConnection(String, String) getConnection(username,password)} is
790
* allowed and honored.. This is used for when the pool is used by an application accessing multiple schemas.
791
* There is a performance impact turning this option on, even when not used due to username checks.
792
* @param alternateUsernameAllowed - set true if {@link DataSource#getConnection(String, String) getConnection(username,password)} is honored,
793
* false if it is to be ignored.
795
public void setAlternateUsernameAllowed(boolean alternateUsernameAllowed);
b'\\ No newline at end of file'
added
removed
modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java
