HHH-16646 add some nice convenience methods to Configuration

documentation/src/main/asciidoc/introduction/Configuration.adoc

@@ -239,8 +239,14 @@ SessionFactory sessionFactory =
         new HibernatePersistenceConfiguration("Bookshop")
             .managedClass(Book.class)
             .managedClass(Author.class)
-            // Set properties
-            ...
+            // PostgreSQL
+            .jdbcUrl("jdbc:postgresql://localhost/example")
+            // Credentials
+            .jdbcCredentials(user, password)
+            // Automatic schema export
+            .schemaToolingAction(Action.SPEC_ACTION_DROP_AND_CREATE)
+            // SQL statement logging
+            .showSql(true, true, true)
             // Create a new SessionFactory
             .createEntityManagerFactory();
 ----

documentation/src/main/asciidoc/introduction/Introduction.adoc

@@ -272,24 +272,19 @@ package org.hibernate.example;
 import org.hibernate.jpa.HibernatePersistenceConfiguration;
 
 import static java.lang.System.out;
-import static jakarta.persistence.PersistenceConfiguration.*;
-import static org.hibernate.cfg.JdbcSettings.*;
 
 public class Main {
     public static void main(String[] args) {
         var sessionFactory =
                 new HibernatePersistenceConfiguration("Bookshelf")
                         .managedClass(Book.class)
                         // use H2 in-memory database
-                        .property(JDBC_URL, "jdbc:h2:mem:db1")
-                        .property(JDBC_USER, "sa")
-                        .property(JDBC_PASSWORD, "")
+                        .jdbcUrl("jdbc:h2:mem:db1")
+                        .jdbcCredentials("sa", "")
                         // use Agroal connection pool
                         .property("hibernate.agroal.maxSize", 20)
                         // display SQL in console
-                        .property(SHOW_SQL, true)
-                        .property(FORMAT_SQL, true)
-                        .property(HIGHLIGHT_SQL, true)
+                        .showSql(true, true, true)
                         .createEntityManagerFactory();
 
         // export the inferred database schema

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

@@ -13,6 +13,7 @@
 import java.util.Map;
 import java.util.Properties;
 
+import jakarta.persistence.PersistenceUnitTransactionType;
 import org.hibernate.CustomEntityDirtinessStrategy;
 import org.hibernate.EntityNameResolver;
 import org.hibernate.HibernateException;
@@ -55,6 +56,7 @@
 import org.hibernate.query.sqm.function.SqmFunctionDescriptor;
 import org.hibernate.resource.jdbc.spi.StatementInspector;
 import org.hibernate.service.ServiceRegistry;
+import org.hibernate.tool.schema.Action;
 import org.hibernate.type.BasicType;
 import org.hibernate.type.SerializationException;
 import org.hibernate.usertype.UserType;
@@ -441,6 +443,75 @@ public Configuration configure(File configFile) throws HibernateException {
 		return this;
 	}
 
+	// New typed property setters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+	/**
+	 * Set {@value AvailableSettings#SHOW_SQL}, {@value AvailableSettings#FORMAT_SQL},
+	 * and {@value AvailableSettings#HIGHLIGHT_SQL}.
+	 *
+	 * @param showSql should SQL be logged to console?
+	 * @param formatSql should logged SQL be formatted
+	 * @param highlightSql should logged SQL be highlighted with pretty colors
+	 */
+	public Configuration showSql(boolean showSql, boolean formatSql, boolean highlightSql) {
+		setProperty( AvailableSettings.SHOW_SQL, Boolean.toString(showSql) );
+		setProperty( AvailableSettings.FORMAT_SQL, Boolean.toString(formatSql) );
+		setProperty( AvailableSettings.HIGHLIGHT_SQL, Boolean.toString(highlightSql) );
+		return this;
+	}
+
+	/**
+	 * Set {@value AvailableSettings#HBM2DDL_AUTO}.
+	 *
+	 * @param action the {@link Action}
+	 */
+	public Configuration setSchemaExportAction(Action action) {
+		setProperty( AvailableSettings.HBM2DDL_AUTO, action.getExternalHbm2ddlName() );
+		return this;
+	}
+
+	/**
+	 * Set {@value AvailableSettings#USER} and {@value AvailableSettings#PASS}.
+	 *
+	 * @param user the user id
+	 * @param pass the password
+	 */
+	public Configuration setCredentials(String user, String pass) {
+		setProperty( AvailableSettings.USER, user );
+		setProperty( AvailableSettings.PASS, pass );
+		return this;
+	}
+
+	/**
+	 * Set {@value AvailableSettings#URL}.
+	 *
+	 * @param url the JDBC URL
+	 */
+	public Configuration setJdbcUrl(String url) {
+		setProperty( AvailableSettings.URL, url );
+		return this;
+	}
+
+	/**
+	 * Set {@value AvailableSettings#DATASOURCE}.
+	 *
+	 * @param jndiName the JNDI name of the datasource
+	 */
+	public Configuration setDatasource(String jndiName) {
+		setProperty( AvailableSettings.DATASOURCE, jndiName );
+		return this;
+	}
+
+	/**
+	 * Set {@value AvailableSettings#JAKARTA_TRANSACTION_TYPE}.
+	 *
+	 * @param transactionType the {@link PersistenceUnitTransactionType}
+	 */
+	public Configuration setTransactionType(PersistenceUnitTransactionType transactionType) {
+		setProperty( AvailableSettings.JAKARTA_TRANSACTION_TYPE, transactionType.toString() );
+		return this;
+	}
+
 	// MetadataSources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 	/**
@@ -694,6 +765,20 @@ public Configuration addAnnotatedClass(Class<?> annotatedClass) {
 		return this;
 	}
 
+	/**
+	 * Read metadata from the annotations associated with the given classes.
+	 *
+	 * @param annotatedClasses The classes containing annotations
+	 *
+	 * @return this (for method chaining)
+	 */
+	public Configuration addAnnotatedClasses(Class... annotatedClasses) {
+		for (Class annotatedClass : annotatedClasses) {
+			addAnnotatedClass( annotatedClass );
+		}
+		return this;
+	}
+
 	/**
 	 * Read package-level metadata.
 	 *
@@ -708,6 +793,22 @@ public Configuration addPackage(String packageName) throws MappingException {
 		return this;
 	}
 
+	/**
+	 * Read package-level metadata.
+	 *
+	 * @param packageNames java package names
+	 *
+	 * @return this (for method chaining)
+	 *
+	 * @throws MappingException in case there is an error in the mapping data
+	 */
+	public Configuration addPackages(String... packageNames) throws MappingException {
+		for (String packageName : packageNames) {
+			addPackage( packageName );
+		}
+		return this;
+	}
+
 	/**
 	 * Read all {@code .hbm.xml} mappings from a {@code .jar} file.
 	 * <p>
@@ -1167,18 +1268,22 @@ public Map<String, NamedProcedureCallDefinition> getNamedProcedureCallMap() {
 	}
 
 	/**
-	 * Adds the incoming properties to the internal properties structure, as
-	 * long as the internal structure does not already contain an entry for
-	 * the given key.
+	 * Adds the incoming properties to the internal properties structure,
+	 * as long as the internal structure does <em>not</em> already contain
+	 * an entry for the given key. If a given property is already set in
+	 * this {@code Configuration}, ignore the setting specified in the
+	 * argument {@link Properties} object.
+	 *
+	 * @apiNote You're probably looking for {@link #addProperties(Properties)}.
 	 *
 	 * @param properties The properties to merge
 	 *
 	 * @return {@code this} for method chaining
 	 */
 	public Configuration mergeProperties(Properties properties) {
-		for ( Map.Entry<Object,Object> entry : properties.entrySet() ) {
-			if ( !properties.containsKey( entry.getKey() ) ) {
-				properties.setProperty( (String) entry.getKey(), (String) entry.getValue() );
+		for ( String property : properties.stringPropertyNames() ) {
+			if ( !this.properties.containsKey( property ) ) {
+				this.properties.setProperty( property, properties.getProperty( property ) );
 			}
 		}
 		return this;

hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceConfiguration.java

@@ -11,6 +11,7 @@
 
 import org.hibernate.SessionFactory;
 import org.hibernate.cache.spi.access.AccessType;
+import org.hibernate.cfg.AvailableSettings;
 import org.hibernate.cfg.CacheSettings;
 import org.hibernate.cfg.JdbcSettings;
 import org.hibernate.cfg.JpaComplianceSettings;
@@ -31,6 +32,12 @@
  * Hibernate extension to the Jakarta Persistence {@link PersistenceConfiguration}
  * contract.
  *
+ * @apiNote The specification explicitly encourages implementors to extend
+ *          {@link PersistenceConfiguration} to accommodate vendor-specific
+ *          extensions in a more typesafe way. Of course, programs which
+ *          desire configuration logic to be portable between JPA providers
+ *          should use {@code PersistenceConfiguration} directly.
+ *
  * @author Steve Ebersole
  *
  * @since 7.0
@@ -48,13 +55,17 @@ public HibernatePersistenceConfiguration(String name) {
 		super( name );
 	}
 
+	/**
+	 * Create a new {@link SessionFactory} based on this configuration.
+	 */
 	@Override
 	public SessionFactory createEntityManagerFactory() {
 		return (SessionFactory) super.createEntityManagerFactory();
 	}
 
 	/**
-	 * Name of the JDBC driver to use for non-Datasource connection
+	 * JDBC driver class name for non-{@link javax.sql.DataSource DataSource}
+	 * connection.
 	 *
 	 * @see #JDBC_DRIVER
 	 */
@@ -64,7 +75,7 @@ public HibernatePersistenceConfiguration jdbcDriver(String driverName) {
 	}
 
 	/**
-	 * URL to use for non-Datasource JDBC connection
+	 * JDBC URL of non-{@link javax.sql.DataSource DataSource} JDBC connection.
 	 *
 	 * @see #JDBC_URL
 	 */
@@ -74,7 +85,7 @@ public HibernatePersistenceConfiguration jdbcUrl(String url) {
 	}
 
 	/**
-	 * User-name to use for non-Datasource JDBC connection
+	 * Username for non-{@link javax.sql.DataSource DataSource} JDBC connection.
 	 *
 	 * @see #JDBC_USER
 	 * @see #jdbcPassword
@@ -85,7 +96,7 @@ public HibernatePersistenceConfiguration jdbcUsername(String username) {
 	}
 
 	/**
-	 * User-name to use for non-Datasource JDBC connection
+	 * Password for non-{@link javax.sql.DataSource DataSource} JDBC connection.
 	 *
 	 * @see #JDBC_PASSWORD
 	 * @see #jdbcUsername
@@ -96,7 +107,39 @@ public HibernatePersistenceConfiguration jdbcPassword(String password) {
 	}
 
 	/**
-	 * Defines whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
+	 * Username and password for non-{@link javax.sql.DataSource DataSource}
+	 * JDBC connection.
+	 *
+	 * @see #JDBC_USER
+	 * @see #JDBC_PASSWORD
+	 * @see #jdbcUsername
+	 * @see #jdbcPassword
+	 */
+	public HibernatePersistenceConfiguration jdbcCredentials(String username, String password) {
+		jdbcUsername( username );
+		jdbcPassword( password );
+		return this;
+	}
+
+	/**
+	 * Enables SQL logging to the console.
+	 * <p>
+	 * Sets {@value AvailableSettings#SHOW_SQL}, {@value AvailableSettings#FORMAT_SQL},
+	 * and {@value AvailableSettings#HIGHLIGHT_SQL}.
+	 *
+	 * @param showSql should SQL be logged to console?
+	 * @param formatSql should logged SQL be formatted
+	 * @param highlightSql should logged SQL be highlighted with pretty colors
+	 */
+	public HibernatePersistenceConfiguration showSql(boolean showSql, boolean formatSql, boolean highlightSql) {
+		property( JdbcSettings.SHOW_SQL, showSql );
+		property( JdbcSettings.FORMAT_SQL, formatSql );
+		property( JdbcSettings.HIGHLIGHT_SQL, highlightSql );
+		return this;
+	}
+
+	/**
+	 * Specifies whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
 	 * all aspects of {@linkplain jakarta.persistence.Query} handling.
 	 *
 	 * @see JpaComplianceSettings#JPA_QUERY_COMPLIANCE
@@ -107,7 +150,7 @@ public HibernatePersistenceConfiguration queryCompliance(boolean enabled) {
 	}
 
 	/**
-	 * Defines whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
+	 * Specifies whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
 	 * all aspects of transaction handling.
 	 *
 	 * @see JpaComplianceSettings#JPA_TRANSACTION_COMPLIANCE
@@ -118,7 +161,7 @@ public HibernatePersistenceConfiguration transactionCompliance(boolean enabled)
 	}
 
 	/**
-	 * Defines whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
+	 * Specifies whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
 	 * handling around calls to {@linkplain EntityManager#close()},
 	 * {@linkplain EntityManager#isOpen()},
 	 * {@linkplain EntityManagerFactory#close()} and
@@ -132,7 +175,7 @@ public HibernatePersistenceConfiguration closedCompliance(boolean enabled) {
 	}
 
 	/**
-	 * Defines whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
+	 * Specifies whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
 	 * handling of proxies.
 	 *
 	 * @see JpaComplianceSettings#JPA_PROXY_COMPLIANCE
@@ -143,7 +186,7 @@ public HibernatePersistenceConfiguration proxyCompliance(boolean enabled) {
 	}
 
 	/**
-	 * Defines whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
+	 * Specifies whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
 	 * handling of proxies.
 	 *
 	 * @see JpaComplianceSettings#JPA_PROXY_COMPLIANCE
@@ -154,7 +197,7 @@ public HibernatePersistenceConfiguration cachingCompliance(boolean enabled) {
 	}
 
 	/**
-	 * Defines whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
+	 * Specifies whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
 	 * in terms of collecting all named value generators globally, regardless of location.
 	 *
 	 * @see JpaComplianceSettings#JPA_ID_GENERATOR_GLOBAL_SCOPE_COMPLIANCE
@@ -165,7 +208,7 @@ public HibernatePersistenceConfiguration globalGeneratorCompliance(boolean enabl
 	}
 
 	/**
-	 * Defines whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
+	 * Specifies whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
 	 * the interpretation of {@link jakarta.persistence.OrderBy}.
 	 *
 	 * @see JpaComplianceSettings#JPA_ORDER_BY_MAPPING_COMPLIANCE
@@ -176,7 +219,7 @@ public HibernatePersistenceConfiguration orderByMappingCompliance(boolean enable
 	}
 
 	/**
-	 * Defines whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
+	 * Specifies whether Hibernate will strictly adhere to compliance with Jakarta Persistence for
 	 * the allowed type of identifier value passed to
 	 * {@link jakarta.persistence.EntityManager#getReference} and
 	 * {@link jakarta.persistence.EntityManager#find}
@@ -189,7 +232,7 @@ public HibernatePersistenceConfiguration loadByIdCompliance(boolean enabled) {
 	}
 
 	/**
-	 * Enable/disable Hibernate's caching support
+	 * Enable or disable the second-level and query caches.
 	 */
 	public HibernatePersistenceConfiguration caching(CachingType type) {
 		assert Objects.nonNull( type );