HHH-18327 Add Agroal and HikariCP settings constants

HHH-18327 fix incorrect Agroal property names

HHH-18327 extend new connection pool settings in JdbcSettings

HHH-18327 use new HikariCPSettings constant in HikariConfigurationUtil

HHH-18327 add HikariCP settings constants

HHH-18327 improve wording

HHH-18327 use new AgroalSettings constant in AgroalConnectionProvider

additionally add AgroalSettings to javadoc and fix invalid see tag

hibernate-agroal/src/main/java/org/hibernate/agroal/internal/AgroalConnectionProvider.java

@@ -14,6 +14,7 @@ import io.agroal.api.configuration.supplier.AgroalPropertiesReader;
 import io.agroal.api.security.NamePrincipal;
 import io.agroal.api.security.SimplePassword;
 import org.hibernate.HibernateException;
+import org.hibernate.cfg.AgroalSettings;
 import org.hibernate.cfg.AvailableSettings;
 import org.hibernate.engine.jdbc.connections.internal.ConnectionProviderInitiator;
 import org.hibernate.engine.jdbc.connections.spi.ConnectionProvider;
@@ -43,15 +44,17 @@ import java.util.function.Function;
  *     hibernate.connection.isolation
  * </pre>
  *
- * Other configuration options are available, using the <pre>hibernate.agroal</pre> prefix ( @see AgroalPropertiesReader )
+ * Other configuration options are available, using the {@code hibernate.agroal} prefix
  *
+ * @see AgroalSettings
+ * @see AgroalPropertiesReader
  * @see AvailableSettings#CONNECTION_PROVIDER
  *
  * @author Luis Barreiro
  */
 public class AgroalConnectionProvider implements ConnectionProvider, Configurable, Stoppable {
 
-	public static final String CONFIG_PREFIX = "hibernate.agroal.";
+	public static final String CONFIG_PREFIX = AgroalSettings.AGROAL_CONFIG_PREFIX + ".";
 	private static final long serialVersionUID = 1L;
 	private static final Logger LOGGER = Logger.getLogger( AgroalConnectionProvider.class );
 	private AgroalDataSource agroalDataSource = null;

hibernate-core/src/main/java/org/hibernate/cfg/AgroalSettings.java

@@ -0,0 +1,132 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate.cfg;
+
+/**
+ * @author Thomas Wearmouth
+ */
+public interface AgroalSettings {
+
+	/**
+	 * A setting prefix used to indicate settings that target the {@code hibernate-agroal} integration.
+	 */
+	String AGROAL_CONFIG_PREFIX = "hibernate.agroal";
+
+	/**
+	 * The maximum size of the connection pool.
+	 * <p>
+	 * There is no default, this setting is mandatory.
+	 */
+	String AGROAL_MAX_SIZE = AGROAL_CONFIG_PREFIX + ".maxSize";
+
+	/**
+	 * The ninimum size of the connection pool.
+	 * <p>
+	 * The default is zero.
+	 */
+	String AGROAL_MIN_SIZE = AGROAL_CONFIG_PREFIX + ".minSize";
+
+	/**
+	 * Initial size of the connection pool.
+	 * <p>
+	 * The default is zero.
+	 */
+	String AGROAL_INITIAL_SIZE = AGROAL_CONFIG_PREFIX + ".initialSize";
+
+	/**
+	 * The maximum amount of time a connection can live, after which it is evicted.
+	 * <p>
+	 * The default is zero, resulting in no restriction on connection lifetime.
+	 * <p>
+	 * Parsed as a {@link java.time.Duration}.
+	 *
+	 * @see java.time.Duration#parse(CharSequence)
+	 */
+	String AGROAL_MAX_LIFETIME = AGROAL_CONFIG_PREFIX + ".maxLifetime";
+
+	/**
+	 * The maximum amount of time a connection can remain out of the pool, after
+	 * which it is reported as a leak.
+	 * <p>
+	 * The default is zero, resulting in no checks for connection leaks.
+	 * <p>
+	 * Parsed as a {@link java.time.Duration}.
+	 *
+	 * @see java.time.Duration#parse(CharSequence)
+	 */
+	String AGROAL_LEAK_TIMEOUT = AGROAL_CONFIG_PREFIX + ".leakTimeout";
+
+	/**
+	 * The maximum amount of time a connection can remain idle, after which it is evicted.
+	 * <p>
+	 * The default is zero, resulting in connections never being considered idle.
+	 * <p>
+	 * Parsed as a {@link java.time.Duration}.
+	 *
+	 * @see java.time.Duration#parse(CharSequence)
+	 */
+	String AGROAL_IDLE_TIMEOUT = AGROAL_CONFIG_PREFIX + ".reapTimeout";
+
+	/**
+	 * The maximum amount of time a thread can wait for a connection, after which an
+	 * exception is thrown instead.
+	 * <p>
+	 * The default is zero, resulting in threads waiting indefinitely.
+	 * <p>
+	 * Parsed as a {@link java.time.Duration}.
+	 *
+	 * @see java.time.Duration#parse(CharSequence)
+	 */
+	String AGROAL_ACQUISITION_TIMEOUT = AGROAL_CONFIG_PREFIX + ".acquisitionTimeout";
+
+	/**
+	 * Background validation is executed at intervals of this value.
+	 * <p>
+	 * The default is zero, resulting in background validation not being performed.
+	 * <p>
+	 * Parsed as a {@link java.time.Duration}.
+	 *
+	 * @see java.time.Duration#parse(CharSequence)
+	 */
+	String AGROAL_VALIDATION_TIMEOUT = AGROAL_CONFIG_PREFIX + ".validationTimeout";
+
+	/**
+	 * A foreground validation is executed if a connection has been idle in the pool
+	 * for longer than this value.
+	 * <p>
+	 * The default is zero, resulting in foreground validation not being performed.
+	 * <p>
+	 * Parsed as a {@link java.time.Duration}.
+	 *
+	 * @see java.time.Duration#parse(CharSequence)
+	 */
+	String AGROAL_IDLE_VALIDATION_TIMEOUT = AGROAL_CONFIG_PREFIX + ".idleValidation";
+
+	/**
+	 * An SQL command to be executed when a connection is created.
+	 */
+	String AGROAL_INITIAL_SQL = AGROAL_CONFIG_PREFIX + ".initialSQL";
+
+	/**
+	 * If {@code true}, connections will be flushed whenever they return to the pool.
+	 * <p>
+	 * The default is {@code false}.
+	 *
+	 * @since agroal-api 1.6
+	 */
+	String AGROAL_FLUSH_ON_CLOSE = AGROAL_CONFIG_PREFIX + ".flushOnClose";
+
+	/**
+	 * If {@code true}, connections will receive foreground validation on every acquisition
+	 * regardless of {@link AgroalSettings#AGROAL_IDLE_VALIDATION_TIMEOUT}.
+	 * <p>
+	 * The default is {@code false}.
+	 *
+	 * @since agroal-api 2.3
+	 */
+	String AGROAL_VALIDATE_ON_BORROW = AGROAL_CONFIG_PREFIX + ".validateOnBorrow";
+}

hibernate-core/src/main/java/org/hibernate/cfg/HikariCPSettings.java

@@ -0,0 +1,118 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate.cfg;
+
+/**
+ * @author Thomas Wearmouth
+ */
+public interface HikariCPSettings {
+
+	/**
+	 * A setting prefix used to indicate settings that target the {@code hibernate-hikaricp} integration.
+	 */
+	String HIKARI_CONFIG_PREFIX = "hibernate.hikari";
+
+	/**
+	 * The maximum size of the connection pool.
+	 * <p>
+	 * The default is 10.
+	 */
+	String HIKARI_MAX_SIZE = HIKARI_CONFIG_PREFIX + ".maximumPoolSize";
+
+	/**
+	 * The minimum number of idle connections to try and maintain in the pool.
+	 * <p>
+	 * The default is the same as {@link HikariCPSettings#HIKARI_MAX_SIZE}.
+	 */
+	String HIKARI_MIN_IDLE_SIZE = HIKARI_CONFIG_PREFIX + ".minimumIdle";
+
+	/**
+	 * The maximum amount of time a connection can live, after which it is evicted.
+	 * <p>
+	 * The default is 1800000 milliseconds (30 minutes).
+	 */
+	String HIKARI_MAX_LIFETIME = HIKARI_CONFIG_PREFIX + ".maxLifetime";
+
+	/**
+	 * The maximum amount of time a connection can remain out of the pool, after
+	 * which it is reported as a leak.
+	 * <p>
+	 * The default is 0 milliseconds, resulting in no checks for connection leaks.
+	 */
+	String HIKARI_LEAK_TIMEOUT = HIKARI_CONFIG_PREFIX + ".leakDetectionThreshold";
+
+	/**
+	 * The maximum amount of time a connection can remain idle, after which it is evicted.
+	 * <p>
+	 * The default is 600000 milliseconds (10 minutes).
+	 */
+	String HIKARI_IDLE_TIMEOUT = HIKARI_CONFIG_PREFIX + ".idleTimeout";
+
+	/**
+	 * The maximum amount of time a thread can wait for a connection, after which an
+	 * exception is thrown instead.
+	 * <p>
+	 * The default is 30000 milliseconds (30 seconds).
+	 */
+	String HIKARI_ACQUISITION_TIMEOUT = HIKARI_CONFIG_PREFIX + ".connectionTimeout";
+
+	/**
+	 * The maximum amount of time that a connection will be tested for aliveness. Must
+	 * be lower than {@link HikariCPSettings#HIKARI_ACQUISITION_TIMEOUT}.
+	 * <p>
+	 * The default is 5000 milliseconds (5 seconds).
+	 */
+	String HIKARI_VALIDATION_TIMEOUT = HIKARI_CONFIG_PREFIX + ".validationTimeout";
+
+	/**
+	 * The maximum amount of time the application thread can wait to attempt to acquire
+	 * an initial connection. Applied after {@link HikariCPSettings#HIKARI_ACQUISITION_TIMEOUT}.
+	 * <p>
+	 * The default is 1 millisecond.
+	 */
+	String HIKARI_INITIALIZATION_TIMEOUT = HIKARI_CONFIG_PREFIX + ".initializationFailTimeout";
+
+	/**
+	 * How often connections will attempt to be kept alive to prevent a timeout.
+	 * <p>
+	 * The default is 0 milliseconds, resulting in no keep-alive behaviour.
+	 */
+	String HIKARI_KEEPALIVE_TIME = HIKARI_CONFIG_PREFIX + ".keepaliveTime";
+
+	/**
+	 * An SQL command to be executed when a connection is created.
+	 */
+	String HIKARI_INITIAL_SQL = HIKARI_CONFIG_PREFIX + ".connectionInitSql";
+
+	/**
+	 * A user-defined name for the pool that appears in logging.
+	 * <p>
+	 * The default is auto-generated.
+	 */
+	String HIKARI_POOL_NAME = HIKARI_CONFIG_PREFIX + ".poolName";
+
+	/**
+	 * If {@code true}, connections obtained from the pool are in read-only mode
+	 * by default.
+	 * <p>
+	 * Some databases do not support read-only mode while some will provide query
+	 * optimizations when a connection is in read-only mode.
+	 * <p>
+	 * The default is {@code false}.
+	 */
+	String HIKARI_READ_ONLY = HIKARI_CONFIG_PREFIX + ".readOnly";
+
+	/**
+	 * If {@code true}, internal pool queries (such as keep-alives) will be isolated
+	 * in their own transaction.
+	 * <p>
+	 * Only applies if {@link AvailableSettings#AUTOCOMMIT} is disabled.
+	 * <p>
+	 * The default is {@code false}.
+	 */
+	String HIKARI_ISOLATE_INTERNAL_QUERIES = HIKARI_CONFIG_PREFIX + ".isolateInternalQueries";
+}

hibernate-core/src/main/java/org/hibernate/cfg/JdbcSettings.java

@@ -21,7 +21,7 @@ import org.hibernate.sql.ast.spi.ParameterMarkerStrategy;
  *
  * @author Steve Ebersole
  */
-public interface JdbcSettings extends C3p0Settings, ProxoolSettings {
+public interface JdbcSettings extends C3p0Settings, ProxoolSettings, AgroalSettings, HikariCPSettings {
 
 	/**
 	 * Specifies a JTA {@link javax.sql.DataSource} to use for Connections.

hibernate-hikaricp/src/main/java/org/hibernate/hikaricp/internal/HikariConfigurationUtil.java

@@ -11,6 +11,7 @@ import java.util.Map;
 import java.util.Properties;
 
 import org.hibernate.cfg.AvailableSettings;
+import org.hibernate.cfg.HikariCPSettings;
 import org.hibernate.cfg.JdbcSettings;
 import org.hibernate.engine.jdbc.connections.internal.ConnectionProviderInitiator;
 
@@ -26,7 +27,7 @@ import static org.hibernate.engine.jdbc.connections.internal.ConnectionProviderI
  * @author Brett Meyer
  */
 public class HikariConfigurationUtil {
-	public static final String CONFIG_PREFIX = "hibernate.hikari.";
+	public static final String CONFIG_PREFIX = HikariCPSettings.HIKARI_CONFIG_PREFIX + ".";
 
 	/**
 	 * Create/load a HikariConfig from Hibernate properties.