documentation updates for H7

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

@@ -4,16 +4,19 @@
 We would love to make this section short.
 Unfortunately, there are several distinct ways to configure and bootstrap Hibernate, and we're going to have to describe at least two of them in detail.
 
-The four basic ways to obtain an instance of Hibernate are shown in the following table:
+The five basic ways to obtain an instance of Hibernate are shown in the following table:
 
 [%breakable,cols="50,50",number=0]
 |===
 
 | Using the standard JPA-defined XML, and the operation `Persistence.createEntityManagerFactory()`
 | Usually chosen when portability between JPA implementations is important.
 
-| Using the link:{doc-javadoc-url}org/hibernate/cfg/Configuration.html[`Configuration`] class to construct a `SessionFactory`
-| When portability between JPA implementations is not important, this option is quicker, adds some flexibility and saves a typecast.
+| Using the standard JPA-defined  `PersistenceConfiguration` class
+| Usually chosen when portability between JPA implementations is important, but programmatic control is desired.
+
+| Using link:{doc-javadoc-url}org/hibernate/jpa/HibernatePersistenceConfiguration.html[`HibernatePersistenceConfiguration`] or the older link:{doc-javadoc-url}org/hibernate/cfg/Configuration.html[`Configuration`] class to construct a `SessionFactory`
+| When portability between JPA implementations is not important, this option adds some convenience and saves a typecast.
 
 | Using the more complex APIs defined in link:{doc-javadoc-url}org/hibernate/boot/package-summary.html[`org.hibernate.boot`]
 | Used primarily by framework integrators, this option is outside the scope of this document.
@@ -102,7 +105,7 @@ or `org.slf4j:slf4j-jdk14`
 | A JDBC connection pool, for example, {agroal}[Agroal] |
 `org.hibernate.orm:hibernate-agroal` +
 and `io.agroal:agroal-pool`
-| The {generator}[Hibernate Metamodel Generator], especially if you're using the JPA criteria query API | `org.hibernate.orm:hibernate-processor`
+| The {generator}[Hibernate Processor], especially if you're using Jakarta Data or the JPA criteria query API | `org.hibernate.orm:hibernate-processor`
 | The {query-validator}[Query Validator], for compile-time checking of HQL | `org.hibernate:query-validator`
 | {validator}[Hibernate Validator], an implementation of {bean-validation}[Bean Validation] |
 `org.hibernate.validator:hibernate-validator` +
@@ -202,49 +205,62 @@ EntityManagerFactory entityManagerFactory =
 ----
 
 [[configuration-api]]
-=== Configuration using Hibernate API
+=== Programmatic configuration using JPA API
 
-Alternatively, the venerable class link:{doc-javadoc-url}org/hibernate/cfg/Configuration.html[`Configuration`] allows an instance of Hibernate to be configured in Java code.
+The new `PersistenceConfiguration` class allows full programmatic control over creation of the `EntityManagerFactory`.
 
 [source,java]
 ----
-SessionFactory sessionFactory =
-        new Configuration()
-            .addAnnotatedClass(Book.class)
-            .addAnnotatedClass(Author.class)
+EntityManagerFactory entityManagerFactory =
+        new PersistenceConfiguration("Bookshop")
+            .managedClass(Book.class)
+            .managedClass(Author.class)
             // PostgreSQL
-            .setProperty(AvailableSettings.JAKARTA_JDBC_URL, "jdbc:postgresql://localhost/example")
+            .property(PersistenceConfiguration.JDBC_URL, "jdbc:postgresql://localhost/example")
             // Credentials
-            .setProperty(AvailableSettings.JAKARTA_JDBC_USER, user)
-            .setProperty(AvailableSettings.JAKARTA_JDBC_PASSWORD, password)
+            .property(PersistenceConfiguration.JDBC_USER, user)
+            .property(PersistenceConfiguration.JDBC_PASSWORD, password)
             // Automatic schema export
-            .setProperty(AvailableSettings.JAKARTA_HBM2DDL_DATABASE_ACTION,
-                         Action.SPEC_ACTION_DROP_AND_CREATE)
+            .property(PersistenceConfiguration.SCHEMAGEN_DATABASE_ACTION,
+                    Action.SPEC_ACTION_DROP_AND_CREATE)
             // SQL statement logging
-            .setProperty(AvailableSettings.SHOW_SQL, true)
-            .setProperty(AvailableSettings.FORMAT_SQL, true)
-            .setProperty(AvailableSettings.HIGHLIGHT_SQL, true)
+            .property(JdbcSettings.SHOW_SQL, true)
+            .property(JdbcSettings.FORMAT_SQL, true)
+            .property(JdbcSettings.HIGHLIGHT_SQL, true)
+            // Create a new EntityManagerFactory
+            .createEntityManagerFactory();
+----
+
+The specification gives JPA implementors like Hibernate explicit permission to extend this class, and so Hibernate offers the link:{doc-javadoc-url}org/hibernate/jpa/HibernatePersistenceConfiguration.html[`HibernatePersistenceConfiguration`], which lets us obtain a `SessionFactory` without any need for a cast.
+
+[source,java]
+----
+SessionFactory sessionFactory =
+        new HibernatePersistenceConfiguration("Bookshop")
+            .managedClass(Book.class)
+            .managedClass(Author.class)
+            // Set properties
+            ...
             // Create a new SessionFactory
-            .buildSessionFactory();
+            .createEntityManagerFactory();
 ----
 
-The `Configuration` class has survived almost unchanged since the very earliest (pre-1.0) versions of Hibernate, and so it doesn't look particularly modern.
-On the other hand, it's very easy to use, and exposes some options that `persistence.xml` doesn't support.
+Alternatively, the venerable class link:{doc-javadoc-url}org/hibernate/cfg/Configuration.html[`Configuration`] offers similar functionality.
 
 :native-bootstrap: {doc-user-guide-url}#bootstrap-native
 :boot: {doc-javadoc-url}/org/hibernate/boot/package-summary.html
 
 .Advanced configuration options
 ****
-Actually, the `Configuration` class is just a very simple facade for the more modern, much more powerful—but more complex—API defined in the package `org.hibernate.boot`.
+Actually, these APIs are very simple facades resting on the much more powerful--but also more complex--APIs defined in the package `org.hibernate.boot`.
 This API is useful if you have very advanced requirements, for example, if you're writing a framework or implementing a container.
 You'll find more information in the {native-bootstrap}[User Guide], and in the {boot}[package-level documentation] of `org.hibernate.boot`.
 ****
 
 [[configuration-properties]]
 === Configuration using Hibernate properties file
 
-If we're using the Hibernate `Configuration` API, but we don't want to put certain configuration properties directly in the Java code, we can specify them in a file named `hibernate.properties`, and place the file in the root classpath.
+If we're using programmatic configuration, but we don't want to put certain configuration properties directly in the Java code, we can specify them in a file named `hibernate.properties`, and place the file in the root classpath.
 
 [source,properties]
 ----
@@ -263,7 +279,9 @@ hibernate.highlight_sql=true
 [[basic-configuration-settings]]
 === Basic configuration settings
 
-The class link:{doc-javadoc-url}org/hibernate/cfg/AvailableSettings.html[`AvailableSettings`] enumerates all the configuration properties understood by Hibernate.
+The `PersistenceConfiguration` class declares `static final` constants holding the names of all configuration properties defined by the specification itself, for example, `JDBC_URL` holds the property name `"jakarta.persistence.jdbc.driver"`.
+
+Similarly, the class link:{doc-javadoc-url}org/hibernate/cfg/AvailableSettings.html[`AvailableSettings`] enumerates all the configuration properties understood by Hibernate.
 
 Of course, we're not going to cover every useful configuration setting in this chapter.
 Instead, we'll mention the ones you need to get started, and come back to some other important settings later, especially when we talk about performance tuning.
@@ -408,13 +426,7 @@ As we mentioned <<testing,earlier>>, it can also be useful to control schema exp
 The link:{doc-javadoc-url}org/hibernate/relational/SchemaManager.html[`SchemaManager`] API allows programmatic control over schema export:
 
 [source,java]
-sessionFactory.getSchemaManager().exportMappedObjects(true);
-
-JPA has a more limited and less ergonomic API:
-
-[source,java]
-Persistence.generateSchema("org.hibernate.example",
-                           Map.of(JAKARTA_HBM2DDL_DATABASE_ACTION, CREATE))
+sessionFactory.getSchemaManager().export(true);
 ====
 
 [[logging-generated-sql]]

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

@@ -497,7 +497,7 @@ The JPA specification defines a quite limited set of basic types:
 | Primitive wrappers | `java.lang` | `Boolean`, `Integer`, `Double`, etc
 | Strings | `java.lang` | `String`
 | Arbitrary-precision numeric types | `java.math` | `BigInteger`, `BigDecimal`
-| Date/time types | `java.time` | `LocalDate`, `LocalTime`, `LocalDateTime`, `OffsetDateTime`, `Instant`
+| Date/time types | `java.time` | `LocalDate`, `LocalTime`, `LocalDateTime`, `OffsetDateTime`, `Instant`, `Year`
 | Deprecated date/time types 💀 | `java.util` | `Date`, `Calendar`
 | Deprecated JDBC date/time types 💀 | `java.sql` | `Date`, `Time`, `Timestamp`
 | Binary and character arrays | | `byte[]`, `char[]`
@@ -600,7 +600,23 @@ Status status;
 
 ----
 
-In Hibernate 6, an `enum` annotated `@Enumerated(STRING)` is mapped to:
+The `@EnumeratedValue` annotation allows the column value to be customized:
+
+[source,java]
+----
+enum Resolution {
+    UNRESOLVED(0), FIXED(1), REJECTED(-1);
+
+    @EnumeratedValue // store the code, not the enum ordinal() value
+    final int code;
+
+    Resolution(int code) {
+         this.code = code;
+    }
+}
+----
+
+Since Hibernate 6, an `enum` annotated `@Enumerated(STRING)` is mapped to:
 
 - a `VARCHAR` column type with a `CHECK` constraint on most databases, or
 - an `ENUM` column type on MySQL.

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

@@ -6,7 +6,7 @@ include::{shared-attributes-dir}/filesystem-attributes.adoc[]
 include::{shared-attributes-dir}/renderer-attributes.adoc[]
 
 
-= An Introduction to Hibernate 6
+= An Introduction to Hibernate 7
 :title-logo-image: image:../../style/asciidoctor/images/org/hibernate/logo.png[]
 :toc:
 :toclevels: 3