Merge branch 'o-main' into main-perf

Author: theigl

.github/hibernate-github-bot.yml

@@ -1,3 +1,4 @@
 ---
 jira:
   projectKey: "HHH"
+  insertLinksInPullRequests: true

docker_db.sh

@@ -320,7 +320,7 @@ mssql_2022() {
 sybase() {
     $CONTAINER_CLI rm -f sybase || true
     # Yup, that sucks, but on ubuntu we need to use -T11889 as per: https://github.com/DataGrip/docker-env/issues/12
-    $CONTAINER_CLI run -d -p 5000:5000 -p 5001:5001 --name sybase --entrypoint /bin/bash docker.io/nguoianphu/docker-sybase -c "source /opt/sybase/SYBASE.sh
+    $CONTAINER_CLI run -d -p 9000:5000 -p 9001:5001 --name sybase --entrypoint /bin/bash docker.io/nguoianphu/docker-sybase -c "source /opt/sybase/SYBASE.sh
 /opt/sybase/ASE-16_0/bin/dataserver \
 -d/opt/sybase/data/master.dat \
 -e/opt/sybase/ASE-16_0/install/MYSYBASE.log \

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

@@ -219,7 +219,7 @@ SessionFactory sessionFactory =
             .setProperty(AvailableSettings.JAKARTA_JDBC_PASSWORD, password)
             // Automatic schema export
             .setProperty(AvailableSettings.JAKARTA_HBM2DDL_DATABASE_ACTION,
-                         Action.CREATE.getExternalJpaName())
+                         Action.SPEC_ACTION_DROP_AND_CREATE)
             // SQL statement logging
             .setProperty(AvailableSettings.SHOW_SQL, TRUE.toString())
             .setProperty(AvailableSettings.FORMAT_SQL, TRUE.toString())

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

@@ -13,39 +13,25 @@ Gavin King and the Hibernate team
 :toc:
 :toclevels: 3
 
-<<<
-
 include::Preface.adoc[]
 
-<<<
-
 :numbered:
 
 include::Introduction.adoc[]
 
-<<<
-
 include::Configuration.adoc[]
 
-<<<
-
 include::Entities.adoc[]
 
-<<<
-
 include::Mapping.adoc[]
 
-<<<
-
 include::Interacting.adoc[]
 
-// include::../userguide/chapters/query/hql/Hibernate_Query_Language.adoc[]
+include::Generator.adoc[]
 
-<<<
+// include::../userguide/chapters/query/hql/Hibernate_Query_Language.adoc[]
 
 include::Tuning.adoc[]
 
-<<<
-
 include::Advanced.adoc[]
 

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

@@ -61,7 +61,7 @@ A persistence context—that is, a `Session` or `EntityManager`—absolutely pos
 If you accidentally leak a session across threads, you will suffer.
 ====
 
-.Container-managed peristence contexts
+.Container-managed persistence contexts
 ****
 In a container environment, the lifecycle of a persistence context scoped to the transaction will usually be managed for you.
 ****
@@ -279,7 +279,7 @@ But there's a way to set things up so that an operation will propagate to associ
 [[cascade]]
 === Cascading persistence operations
 
-It's quite often the case that the lifecycle of a _child_ entity is completely dependent on the lifeycle of some _parent_.
+It's quite often the case that the lifecycle of a _child_ entity is completely dependent on the lifecycle of some _parent_.
 This is especially common for many-to-one and one-to-one associations, though it's very rare for many-to-many associations.
 
 For example, it's quite common to make an `Order` and all its ``Item``s persistent in the same transaction, or to delete a `Project` and its ``Files``s at once.
@@ -652,14 +652,14 @@ Using the JPA-standard APIs, this would be a `CriteriaBuilder`, and we get it fr
 
 [source,java]
 ----
-CriteriaBuilder cb = entityManagerFactory.getCriteriaBuilder();
+CriteriaBuilder builder = entityManagerFactory.getCriteriaBuilder();
 ----
 
 But if we have a `SessionFactory`, we get something much better, a `HibernateCriteriaBuilder`:
 
 [source,java]
 ----
-HibernateCriteriaBuilder cb = sessionFactory.getCriteriaBuilder();
+HibernateCriteriaBuilder builder = sessionFactory.getCriteriaBuilder();
 ----
 
 The `HibernateCriteriaBuilder` extends `CriteriaBuilder` and adds many operations that JPQL doesn't have.
@@ -672,15 +672,15 @@ Either:
 
 [source,java]
 ----
-HibernateCriteriaBuilder cb =
+HibernateCriteriaBuilder builder =
         entityManagerFactory.unwrap(SessionFactory.class).getCriteriaBuilder();
 ----
 
 Or simply:
 
 [source,java]
 ----
-HibernateCriteriaBuilder cb =
+HibernateCriteriaBuilder builder =
         (HibernateCriteriaBuilder) entityManagerFactory.getCriteriaBuilder();
 ----
 ====
@@ -689,18 +689,18 @@ We're ready to create a criteria query.
 
 [source,java]
 ----
-CriteriaQuery<Book> query = cb.createQuery(Book.class);
+CriteriaQuery<Book> query = builder.createQuery(Book.class);
 Root<Book> book = query.from(Book.class);
-Predicate where = cb.conjunction();
+Predicate where = builder.conjunction();
 if (titlePattern != null) {
-    where = cb.and(where, cb.like(book.get(Book_.title), titlePattern));
+    where = builder.and(where, builder.like(book.get(Book_.title), titlePattern));
 }
 if (namePattern != null) {
     Join<Book,Author> author = book.join(Book_.author);
-    where = cb.and(where, cb.like(author.get(Author_.name), namePattern));
+    where = builder.and(where, builder.like(author.get(Author_.name), namePattern));
 }
 query.select(book).where(where)
-    .orderBy(cb.asc(book.get(Book_.title)));
+    .orderBy(builder.asc(book.get(Book_.title)));
 ----
 
 Here, as before, the classes `Book_` and `Author_` are generated by Hibernate's <<metamodel-generator,JPA Metamodel Generator>>.
@@ -739,9 +739,9 @@ Update, insert, and delete queries work similarly:
 
 [source,java]
 ----
-CriteriaDelete<Book> delete = cb.createCriteriaDelete(Book.class);
+CriteriaDelete<Book> delete = builder.createCriteriaDelete(Book.class);
 Root<Book> book = delete.from(Book.class);
-delete.where(cb.lt(cb.year(book.get(Book_.publicationDate)), 2000));
+delete.where(builder.lt(builder.year(book.get(Book_.publicationDate)), 2000));
 session.createMutationQuery(delete).executeUpdate();
 ----
 
@@ -750,15 +750,47 @@ session.createMutationQuery(delete).executeUpdate();
 It's even possible to transform a HQL query string to a criteria query, and modify the query programmatically before execution:
 [source,java]
 ----
-HibernateCriteriaBuilder cb = sessionFactory.getCriteriaBuilder();
-var query = cb.createQuery("from Book where year(publicationDate) > 2000", Book.class);
+HibernateCriteriaBuilder builder = sessionFactory.getCriteriaBuilder();
+var query = builder.createQuery("from Book where year(publicationDate) > 2000", Book.class);
 var root = (Root<Book>) query.getRootList().get(0);
-query.where(cb.like(root.get(Book_.title), cb.literal("Hibernate%")));
-query.orderBy(cb.asc(root.get(Book_.title)), cb.desc(root.get(Book_.isbn)));
+query.where(builder.like(root.get(Book_.title), builder.literal("Hibernate%")));
+query.orderBy(builder.asc(root.get(Book_.title)), builder.desc(root.get(Book_.isbn)));
 List<Book> matchingBooks = session.createSelectionQuery(query).getResultList();
 ----
 ====
 
+Do you find some of the code above a bit too verbose?
+We do.
+
+[[criteria-definition]]
+=== A more comfortable way to write criteria queries
+
+Actually, what makes the JPA criteria API less ergonomic that it should be is the need to call all operations of the `CriteriaBuilder` as instance methods, instead of having them as `static` functions.
+The reason it works this way is that each JPA providor has its own implementation of `CriteriaBuilder`.
+
+// [%unbreakable]
+// [TIP]
+// ====
+Hibernate 6.3 introduces the helper class `CriteriaDefinition` to reduce the verbosity of criteria queries.
+Our example looks like this:
+
+[source,java]
+----
+CriteriaQuery<Book> query =
+        new CriteriaDefinition(entityManagerFactory, Book.class) {{
+            select(book);
+            if (titlePattern != null) {
+                restrict(like(book.get(Book_.title), titlePattern));
+            }
+            if (namePattern != null) {
+                var author = book.join(Book_.author);
+                restrict(like(author.get(Author_.name), namePattern));
+            }
+            orderBy(asc(book.get(Book_.title)));
+        }};
+----
+// ====
+
 When all else fails, and sometimes even before that, we're left with the option of writing a query in SQL.
 
 [[native-queries]]
@@ -859,7 +891,7 @@ For example, this:
 List<Book> books =
         session.createSelectionQuery("from Book where title like ?1 order by title")
             .setParameter(1, titlePattern)
-            .setMaxResults(10)
+            .setMaxResults(MAX_RESULTS)
             .getResultList();
 ----
 
@@ -870,22 +902,32 @@ is simpler than:
 List<Book> books =
         session.createSelectionQuery("from Book where title like ?1 order by title fetch first ?2 rows only")
             .setParameter(1, titlePattern)
-            .setParameter(2, 10)
+            .setParameter(2, MAX_RESULTS)
+            .getResultList();
+----
+
+Hibernate's `SelectionQuery` has a slightly different way to paginate the query results:
+
+[source,java]
+----
+List<Book> books =
+        session.createSelectionQuery("from Book where title like ?1 order by title")
+            .setParameter(1, titlePattern)
+            .setPage(Page.first(MAX_RESULTS))
             .getResultList();
 ----
 
 A closely-related issue is ordering.
 It's quite common for pagination to be combined with the need to order query results by a field that's determined at runtime.
-So, as an alternative to the HQL `order by` clause, Hibernate's `SelectionQuery` interface offers the ability to specify that the query results should be ordered by one or more fields of the entity type returned by the query:
+So, as an alternative to the HQL `order by` clause, `SelectionQuery` offers the ability to specify that the query results should be ordered by one or more fields of the entity type returned by the query:
 
 [source,java]
 ----
 List<Book> books =
         session.createSelectionQuery("from Book where title like ?1")
             .setParameter(1, titlePattern)
-            .ascending(Book._title)
-            .ascending(Book._isbn)
-            .setMaxResults(10)
+            .setOrder(List.of(Order.asc(Book._title), Order.asc(Book._isbn)))
+            .setMaxResults(MAX_RESULTS)
             .getResultList();
 ----
 
@@ -898,9 +940,8 @@ Unfortunately, there's no way to do this using JPA's `TypedQuery` interface.
 
 | `setMaxResults()` | Set a limit on the number of results returned by a query | &#10004;
 | `setFirstResult()` | Set an offset on the results returned by a query | &#10004;
-| `ascending()` | Add a field to use to order the results | &#10006;
-| `descending()` | Add a field to use to order the results | &#10006;
-| `unordered()` | Clear any current ordering | &#10006;
+| `setPage()` | Set the limit and offset by specifying a `Page` object | &#10006;
+| `setOrder()` | Specify how the query results should be ordered | &#10006;
 |===
 
 [[projection-lists]]
@@ -951,13 +992,13 @@ Consider the following code:
 
 [source,java]
 ----
-var cb = sessionFactory.getCriteriaBuilder();
-var query = cb.createTupleQuery();
+var builder = sessionFactory.getCriteriaBuilder();
+var query = builder.createTupleQuery();
 var book = query.from(Book.class);
 var bookTitle = book.get(Book_.title);
 var bookIsbn = book.get(Book_.isbn);
 var bookPrice = book.get(Book_.price);
-query.select(cb.tuple(bookTitle, bookIsbn, bookPrice));
+query.select(builder.tuple(bookTitle, bookIsbn, bookPrice));
 var resultList = session.createSelectionQuery(query).getResultList();
 for (var result: resultList) {
     String title = result.get(bookTitle);
@@ -1032,9 +1073,10 @@ Note that the code which executes the named query is not aware of whether the qu
 
 It's nice to have our queries checked at startup time.
 It's even better to have them checked at compile time.
-Back in <<generated-query-methods>>, we mentioned that the {query-validator}[Query Validator] can do that for us.
-In fact, the Query Validator will even check HQL query strings that occur as arguments to `createQuery()` and friends.
-So if we use the Query Validator, there's not much advantage to the use of named queries.
+Back in <<generated-query-methods>>, we mentioned that the Metamodel Generator can do that for us, and we presented that as a reason to use `@NamedQuery`.
+
+But actually, Hibernate has a separate <<query-validator,Query Validator>> capable of performing compile-time validation of HQL query strings that occur as arguments to `createQuery()` and friends.
+If we use the Query Validator, there's not much advantage to the use of named queries.
 ====
 
 [[load-access]]