diff --git a/documentation/src/main/asciidoc/introduction/Configuration.adoc b/documentation/src/main/asciidoc/introduction/Configuration.adoc index 2f5df9845fdf..3479293aaf62 100644 --- a/documentation/src/main/asciidoc/introduction/Configuration.adoc +++ b/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(); ---- diff --git a/documentation/src/main/asciidoc/introduction/Introduction.adoc b/documentation/src/main/asciidoc/introduction/Introduction.adoc index e2c1721885e3..5295262ce5d0 100644 --- a/documentation/src/main/asciidoc/introduction/Introduction.adoc +++ b/documentation/src/main/asciidoc/introduction/Introduction.adoc @@ -272,8 +272,6 @@ 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) { @@ -281,15 +279,12 @@ public class Main { 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 diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java b/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java index 34e97c252ec3..ff5932da184c 100644 --- a/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java +++ b/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. *

@@ -1167,18 +1268,22 @@ public Map 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 not 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 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; diff --git a/hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceConfiguration.java b/hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceConfiguration.java index 13ce41f00d0d..682fe2a71e4c 100644 --- a/hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceConfiguration.java +++ b/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. + *

+ * 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 );