- All Known Subinterfaces:
DataSourceBuilder.Settings
- All Known Implementing Classes:
DataSourceConfig
Use settings() for getter access to read the configuration
set on the builder via DataSourceBuilder.Settings. That is, DataSourceBuilder has
the setters only and DataSourceBuilder.Settings has both the getters and
setters for the builder.
DataSourcePool pool = DataSourcePool.builder()
.name("test")
.url("jdbc:h2:mem:tests")
.username("sa")
.password("")
.build();
try (Connection connection = pool.getConnection()) {
// do something with the connection ...
}
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interfaceThe settings of the DataSourceBuilder. -
Method Summary
Modifier and TypeMethodDescriptionaddProperty(String key, boolean value) Add a driver property.addProperty(String key, int value) Add a driver property.addProperty(String key, String value) Add a driver property.default DataSourceBuilderalert(DataSourceAlert alert) Set the alert implementation to use.default DataSourceBuilderalsoIf(BooleanSupplier predicate, Consumer<DataSourceBuilder.Settings> apply) Conditionally apply configuration to the builder via a lambda.default DataSourceBuilderapplicationName(String applicationName) Set the ClientInfo ApplicationName property.apply(Consumer<DataSourceBuilder.Settings> apply) Apply configuration to the builder via a lambda.default DataSourceBuilderautoCommit(boolean autoCommit) Set to true to turn on autoCommit.build()Build and return the DataSourcePool.default DataSourceBuildercaptureStackTrace(boolean captureStackTrace) Set to true if a stack trace should be captured when obtaining a connection from the pool.Set the default database catalog to use.default DataSourceBuilderclientInfo(Properties clientInfo) Set the ClientInfo as properties.copy()Return a copy of the DataSourceBuilder.static DataSourceBuildercreate()Return a new builder of DataSourcePool.default DataSourceBuildercstmtCacheSize(int cstmtCacheSize) Set the size of the CallableStatement cache (per connection).default DataSourceBuildercustomProperties(Map<String, String> customProperties) Set custom properties for the jdbc driver connection.dataSource(DataSource dataSource) Set a DataSource that will be used to provide new connections.Set the driver class to use.default DataSourceBuilderSet the database driver className.Set the driver to use.booleanWhentrue, an exception is thrown when a dirty connection is closed.enforceCleanClose(boolean enforceCleanClose) When enabled, the datasource enforces a clean close.default DataSourceBuilderfailOnStart(boolean failOnStart) Set to false, if DataSource should not fail on start.static DataSourceBuilderfrom(Properties properties) Return a new builder loading from the given properties.static DataSourceBuilderfrom(Properties properties, String prefix) Return a new builder loading from the given properties using a given prefix.default DataSourceBuilderheartbeatFreqSecs(int heartbeatFreqSecs) Set the expected heartbeat frequency in seconds.heartbeatMaxPoolExhaustedCount(int count) Sets the coun how often the heartbeat has to detect pool exhaustion in succession.default DataSourceBuilderheartbeatSql(String heartbeatSql) Set a SQL statement used to test the database is accessible.default DataSourceBuilderheartbeatTimeoutSeconds(int heartbeatTimeoutSeconds) Set the heart beat timeout in seconds.default DataSourceBuilderinitDatabase(InitDatabase initDatabase) Set the InitDatabase to use with ownerUsername.default DataSourceBuilderinitDatabaseForPlatform(String platform) Set InitDatabase based on the database platform.initialConnections(int initialConnections) Set the number of initial connections to create when starting.default DataSourceBuilderSet custom init queries for each query.default DataSourceBuilderisolationLevel(int isolationLevel) Set the transaction isolation level.default DataSourceBuilderleakTimeMinutes(int leakTimeMinutes) Set the time in minutes after which a connection could be considered to have leaked.default DataSourceBuilderlistener(DataSourcePoolListener listener) Set the listener to use.load(Properties properties) Load the settings from the properties with no prefix on the property names.load(Properties properties, String prefix) Load the settings from the properties with the given prefix on the property names.loadSettings(Properties properties, String poolName) Load the settings from the properties with "datasource" prefix on the property names.default DataSourceBuildermaxAgeMinutes(int maxAgeMinutes) Set the maximum age a connection can be in minutes.default DataSourceBuildermaxConnections(int maxConnections) Set the maximum number of connections the pool can reach.default DataSourceBuildermaxInactiveTimeSecs(int maxInactiveTimeSecs) Set the time in seconds a connection can be idle after which it can be trimmed from the pool.default DataSourceBuildermaxStackTraceSize(int maxStackTraceSize) Set the max size for reporting stack traces on busy connections.default DataSourceBuilderminConnections(int minConnections) Set the minimum number of connections the pool should maintain.default DataSourceBuilderSet the data source pool name.default DataSourceBuilderoffline(boolean offline) Set to true if the DataSource should be started offline (without any connections).default DataSourceBuilderownerPassword(String ownerPassword) Set the database owner password (used to create connection for use with InitDatabase).default DataSourceBuilderownerUsername(String ownerUsername) Set the database owner username (used to create connection for use with InitDatabase).default DataSourceBuilderSet the database password.default DataSourceBuilderSet the database alternate password2.default DataSourceBuilderSet the database platform (for use with ownerUsername and InitDatabase.default DataSourceBuilderpoolListener(String poolListener) Set a pool listener.default DataSourceBuilderpstmtCacheSize(int pstmtCacheSize) Set the size of the PreparedStatement cache (per connection).default DataSourceBuilderreadOnly(boolean readOnly) Set to true to for read only.default DataSourceBuilderreadOnlyUrl(String readOnlyUrl) Set the connection URL to use for a matching read-only connection pool.default DataSourceBuilderSet the default database schema to use.setAlert(DataSourceAlert alert) Deprecated, for removal: This API element is subject to removal in a future version.setApplicationName(String applicationName) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toapplicationName(String)setAutoCommit(boolean autoCommit) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toautoCommit(boolean).setCaptureStackTrace(boolean captureStackTrace) Deprecated, for removal: This API element is subject to removal in a future version.- migrate tocaptureStackTrace(boolean).setClientInfo(Properties clientInfo) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toclientInfo(Properties).setCstmtCacheSize(int cstmtCacheSize) Deprecated.- migrate tocstmtCacheSize(int).setCustomProperties(Map<String, String> customProperties) Deprecated.- migrate tocustomProperties(Map).setDefaults(DataSourceBuilder other) Default the values for driver, url, username, password and minConnections from another builder if these properties not already been set.Deprecated, for removal: This API element is subject to removal in a future version.- migrate todriver(String).setFailOnStart(boolean failOnStart) Deprecated.- migrate tofailOnStart(boolean).setHeartbeatFreqSecs(int heartbeatFreqSecs) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toheartbeatFreqSecs(int).setHeartbeatSql(String heartbeatSql) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toheartbeatSql(String).setHeartbeatTimeoutSeconds(int heartbeatTimeoutSeconds) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toheartbeatTimeoutSeconds(int).setInitDatabase(InitDatabase initDatabase) Deprecated.- migrate toinitDatabase(InitDatabase).setInitDatabaseForPlatform(String platform) Deprecated.- migrate toinitDatabaseForPlatform(String).setInitSql(List<String> initSql) Deprecated.- migrate toinitSql(List).setIsolationLevel(int isolationLevel) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toisolationLevel(int).setLeakTimeMinutes(int leakTimeMinutes) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toleakTimeMinutes(int).setListener(DataSourcePoolListener listener) Deprecated, for removal: This API element is subject to removal in a future version.- migrate tolistener(DataSourcePoolListener).setMaxAgeMinutes(int maxAgeMinutes) Deprecated.- migrate tomaxAgeMinutes(int).setMaxConnections(int maxConnections) Deprecated, for removal: This API element is subject to removal in a future version.- migrate tomaxConnections(int).setMaxInactiveTimeSecs(int maxInactiveTimeSecs) Deprecated.- migrate tomaxInactiveTimeSecs(int).setMaxStackTraceSize(int maxStackTraceSize) Deprecated, for removal: This API element is subject to removal in a future version.- migrate tomaxStackTraceSize(int).setMinConnections(int minConnections) Deprecated, for removal: This API element is subject to removal in a future version.- migrate tominConnections(int).Deprecated, for removal: This API element is subject to removal in a future version.- migrate toname(String)setOffline(boolean offline) Deprecated.- migrate tooffline(boolean).setOwnerPassword(String ownerPassword) Deprecated.- migrate toownerPassword(String).setOwnerUsername(String ownerUsername) Deprecated.- migrate toownerUsername(String).setPassword(String password) Deprecated.- migrate topassword(String).setPassword2(String password2) Deprecated.- migrate topassword2(String).setPlatform(String platform) Deprecated.- migrate toplatform(String).setPoolListener(String poolListener) Deprecated.- migrate topoolListener(String).setPstmtCacheSize(int pstmtCacheSize) Deprecated.- migrate topstmtCacheSize(int).setReadOnly(boolean readOnly) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toreadOnly(boolean).setReadOnlyUrl(String readOnlyUrl) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toreadOnlyUrl(String).Deprecated, for removal: This API element is subject to removal in a future version.- migrate toschema(String).settings()Return the builder with access to the settings.setTrimPoolFreqSecs(int trimPoolFreqSecs) Deprecated.- migrate totrimPoolFreqSecs(int).Deprecated, for removal: This API element is subject to removal in a future version.- migrate tourl(String).setUsername(String username) Deprecated, for removal: This API element is subject to removal in a future version.- migrate tousername(String).setWaitTimeoutMillis(int waitTimeoutMillis) Deprecated.- migrate towaitTimeoutMillis(int).shutdownOnJvmExit(boolean shutdownOnJvmExit) When set true a JVM shutdown hook is registered that will shutdown the connection pool on JVM exit if it has not already been shutdown.default DataSourceBuildertrimPoolFreqSecs(int trimPoolFreqSecs) Set the minimum trim gap between pool trim checks.default DataSourceBuilderSet the connection URL.default DataSourceBuilderSet the database username.validateOnHeartbeat(boolean validateOnHeartbeat) Set whether the connection pool should be validated periodically.default DataSourceBuilderwaitTimeoutMillis(int waitTimeoutMillis) Set the time in millis to wait for a connection before timing out once the pool has reached its maximum size.
-
Method Details
-
create
Return a new builder of DataSourcePool. -
from
Return a new builder loading from the given properties.- Parameters:
properties- Configuration of the DataSourceBuilder via properties.
-
from
Return a new builder loading from the given properties using a given prefix.For example, using a prefix of "myDataSource" then the username property key would be "myDataSource.username".
- Parameters:
properties- Configuration of the DataSourceBuilder via properties.prefix- The key prefix when reading the properties
-
build
DataSourcePool build()Build and return the DataSourcePool.DataSourcePool pool = DataSourcePool.builder() .setName("test") .setUrl("jdbc:h2:mem:tests") .setUsername("sa") .setPassword("") .build(); -
settings
DataSourceBuilder.Settings settings()Return the builder with access to the settings. Provides getters/accessors to read the configured properties of this DataSourceBuilder. -
apply
Apply configuration to the builder via a lambda. -
alsoIf
default DataSourceBuilder alsoIf(BooleanSupplier predicate, Consumer<DataSourceBuilder.Settings> apply) Conditionally apply configuration to the builder via a lambda.- Parameters:
predicate- The condition to apply configuration when true.apply- The configuration apply function.
-
copy
DataSourceBuilder copy()Return a copy of the DataSourceBuilder. -
setDefaults
Default the values for driver, url, username, password and minConnections from another builder if these properties not already been set. -
setName
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toname(String) -
name
Set the data source pool name. -
dataSource
Set a DataSource that will be used to provide new connections.When provided, then it needs to implement
DataSource.getConnection()andDataSource.getConnection(String, String)returning new connections that will be pooled. -
setApplicationName
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toapplicationName(String) -
applicationName
Set the ClientInfo ApplicationName property.Refer to
Connection.setClientInfo(String, String).- Parameters:
applicationName- The ApplicationName property to set as clientInfo.
-
setClientInfo
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toclientInfo(Properties). -
clientInfo
Set the ClientInfo as properties.Refer to
Connection.setClientInfo(Properties)Note that for Postgres currently only the ApplicationName property is used.
- Parameters:
clientInfo- The client info properties to set on connections in the DataSource.
-
setReadOnlyUrl
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toreadOnlyUrl(String). -
readOnlyUrl
Set the connection URL to use for a matching read-only connection pool. -
setUrl
Deprecated, for removal: This API element is subject to removal in a future version.- migrate tourl(String). -
url
Set the connection URL. -
setUsername
Deprecated, for removal: This API element is subject to removal in a future version.- migrate tousername(String). -
username
Set the database username. -
setPassword
Deprecated.- migrate topassword(String). -
password
Set the database password. -
setPassword2
Deprecated.- migrate topassword2(String). -
password2
Set the database alternate password2. -
setSchema
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toschema(String). -
schema
Set the default database schema to use. -
catalog
Set the default database catalog to use. -
setDriver
Deprecated, for removal: This API element is subject to removal in a future version.- migrate todriver(String). -
driver
Set the database driver className. -
driver
Set the driver class to use. -
driver
Set the driver to use. -
isolationLevel
Set the transaction isolation level. -
setIsolationLevel
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toisolationLevel(int). -
autoCommit
Set to true to turn on autoCommit. -
setAutoCommit
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toautoCommit(boolean). -
readOnly
Set to true to for read only. -
setReadOnly
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toreadOnly(boolean). -
minConnections
Set the minimum number of connections the pool should maintain. Defaults to 2 when not set. -
setMinConnections
Deprecated, for removal: This API element is subject to removal in a future version.- migrate tominConnections(int). -
initialConnections
Set the number of initial connections to create when starting.When not set the initial number of connections will be min connections.
The benefit of setting an initial number of connections is for smoother deployment into an active production system where an application will get assigned production load.
-
maxConnections
Set the maximum number of connections the pool can reach. Defaults to 200 when not set. -
setMaxConnections
Deprecated, for removal: This API element is subject to removal in a future version.- migrate tomaxConnections(int). -
alert
Set the alert implementation to use. -
setAlert
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toalert(DataSourceAlert). -
listener
Set the listener to use. -
setListener
Deprecated, for removal: This API element is subject to removal in a future version.- migrate tolistener(DataSourcePoolListener). -
heartbeatSql
Set a SQL statement used to test the database is accessible.Note that if this is not set then it can get defaulted from the DatabasePlatform.
-
setHeartbeatSql
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toheartbeatSql(String). -
heartbeatFreqSecs
Set the expected heartbeat frequency in seconds. -
setHeartbeatFreqSecs
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toheartbeatFreqSecs(int). -
heartbeatTimeoutSeconds
Set the heart beat timeout in seconds. -
setHeartbeatTimeoutSeconds
@Deprecated(forRemoval=true) DataSourceBuilder setHeartbeatTimeoutSeconds(int heartbeatTimeoutSeconds) Deprecated, for removal: This API element is subject to removal in a future version.- migrate toheartbeatTimeoutSeconds(int). -
heartbeatMaxPoolExhaustedCount
Sets the coun how often the heartbeat has to detect pool exhaustion in succession. in succession before an error is raised and the pool will be reset.By default, this value must be multiplied with the sum of heartbeatfreq + waitTimeoutMillis to estimate the time, when the pool will be restarted, because all connections were leaked.
-
captureStackTrace
Set to true if a stack trace should be captured when obtaining a connection from the pool.This can be used to diagnose a suspected connection pool leak.
Obviously this has a performance overhead.
-
setCaptureStackTrace
Deprecated, for removal: This API element is subject to removal in a future version.- migrate tocaptureStackTrace(boolean). -
maxStackTraceSize
Set the max size for reporting stack traces on busy connections. -
setMaxStackTraceSize
Deprecated, for removal: This API element is subject to removal in a future version.- migrate tomaxStackTraceSize(int). -
leakTimeMinutes
Set the time in minutes after which a connection could be considered to have leaked. -
setLeakTimeMinutes
Deprecated, for removal: This API element is subject to removal in a future version.- migrate toleakTimeMinutes(int). -
pstmtCacheSize
Set the size of the PreparedStatement cache (per connection).Defaults to 100.
-
setPstmtCacheSize
Deprecated.- migrate topstmtCacheSize(int). -
cstmtCacheSize
Set the size of the CallableStatement cache (per connection). -
setCstmtCacheSize
Deprecated.- migrate tocstmtCacheSize(int). -
waitTimeoutMillis
Set the time in millis to wait for a connection before timing out once the pool has reached its maximum size.Defaults to 1000 millis (1 second).
-
setWaitTimeoutMillis
Deprecated.- migrate towaitTimeoutMillis(int). -
maxAgeMinutes
Set the maximum age a connection can be in minutes.Defaults to unlimited age, no connections are trimmed based on age.
-
setMaxAgeMinutes
Deprecated.- migrate tomaxAgeMinutes(int). -
maxInactiveTimeSecs
Set the time in seconds a connection can be idle after which it can be trimmed from the pool.This is so that the pool after a busy period can trend over time back towards the minimum connections.
-
setMaxInactiveTimeSecs
Deprecated.- migrate tomaxInactiveTimeSecs(int). -
trimPoolFreqSecs
Set the minimum trim gap between pool trim checks. -
setTrimPoolFreqSecs
Deprecated.- migrate totrimPoolFreqSecs(int). -
poolListener
Set a pool listener. -
setPoolListener
Deprecated.- migrate topoolListener(String). -
failOnStart
Set to false, if DataSource should not fail on start. (e.g. DataSource is not available) -
setFailOnStart
Deprecated.- migrate tofailOnStart(boolean). -
offline
Set to true if the DataSource should be started offline (without any connections). -
setOffline
Deprecated.- migrate tooffline(boolean). -
initSql
Set custom init queries for each query. -
setInitSql
Deprecated.- migrate toinitSql(List). -
customProperties
Set custom properties for the jdbc driver connection. -
setCustomProperties
Deprecated.- migrate tocustomProperties(Map). -
addProperty
Add a driver property.config.addProperty("useSSL", false); -
addProperty
Add a driver property.config.addProperty("useSSL", false); -
addProperty
Add a driver property.config.addProperty("useSSL", false); -
ownerUsername
Set the database owner username (used to create connection for use with InitDatabase). -
setOwnerUsername
Deprecated.- migrate toownerUsername(String). -
ownerPassword
Set the database owner password (used to create connection for use with InitDatabase). -
setOwnerPassword
Deprecated.- migrate toownerPassword(String). -
platform
Set the database platform (for use with ownerUsername and InitDatabase. -
setPlatform
Deprecated.- migrate toplatform(String). -
initDatabase
Set the InitDatabase to use with ownerUsername. -
setInitDatabase
Deprecated.- migrate toinitDatabase(InitDatabase). -
initDatabaseForPlatform
Set InitDatabase based on the database platform. -
setInitDatabaseForPlatform
Deprecated.- migrate toinitDatabaseForPlatform(String). -
shutdownOnJvmExit
When set true a JVM shutdown hook is registered that will shutdown the connection pool on JVM exit if it has not already been shutdown. -
validateOnHeartbeat
Set whether the connection pool should be validated periodically.This is enabled by default. Generally we only want to turn this off when using the pool with a Lambda function.
- Parameters:
validateOnHeartbeat- Use false to disable heartbeat validation.
-
load
Load the settings from the properties with no prefix on the property names.- Parameters:
properties- the properties to configure the dataSource
-
load
Load the settings from the properties with the given prefix on the property names.For example, using a prefix of "my-db" then the username property key would be "my-db.username".
- Parameters:
properties- the properties to configure the dataSourceprefix- the prefix of the property names.
-
loadSettings
Load the settings from the properties with "datasource" prefix on the property names.For example, if the poolName is "hr" then the username property key would be: "datasource.hr.username".
- Parameters:
properties- the properties to configure the dataSourcepoolName- the name of the specific dataSource pool (optional)
-
enforceCleanClose
When enabled, the datasource enforces a clean close. This means, if you close a possible dirty connection, that was not committed or rolled back, an exception is thrown.When disabled, the situation is logged as warning.
This option has no effect on readonly or autocommit connections.
Note: It is recommended to enable this option in tests/test systems to find possible programming errors. See https://github.com/ebean-orm/ebean-datasource/issues/116 for details.
-
enforceCleanClose
boolean enforceCleanClose()Whentrue, an exception is thrown when a dirty connection is closed.
-
alert(DataSourceAlert).