From ea2c360ebaf274ab2cf9ac9a23a8597dc5745f15 Mon Sep 17 00:00:00 2001 From: Christian Beikov Date: Fri, 10 Nov 2023 13:01:37 +0100 Subject: [PATCH] HHH-17410 Add documentation for count query creation --- .../userguide/Hibernate_User_Guide.adoc | 1 + .../query/criteria/CriteriaExtensions.adoc | 34 +++++++++++++++++++ .../query/{ => criteria}/CountQueryTests.java | 17 +++++----- 3 files changed, 44 insertions(+), 8 deletions(-) create mode 100644 documentation/src/main/asciidoc/userguide/chapters/query/criteria/CriteriaExtensions.adoc rename hibernate-core/src/test/java/org/hibernate/orm/test/query/{ => criteria}/CountQueryTests.java (97%) diff --git a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc index 0f6012da25..d814f19e06 100644 --- a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc +++ b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc @@ -32,6 +32,7 @@ include::chapters/events/Events.adoc[] include::chapters/query/hql/Query.adoc[] include::chapters/query/hql/QueryLanguage.adoc[] include::chapters/query/criteria/Criteria.adoc[] +include::chapters/query/criteria/CriteriaExtensions.adoc[] include::chapters/query/native/Native.adoc[] include::chapters/query/spatial/Spatial.adoc[] include::chapters/query/extensions/Vector.adoc[] diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/criteria/CriteriaExtensions.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/criteria/CriteriaExtensions.adoc new file mode 100644 index 0000000000..5c42a20511 --- /dev/null +++ b/documentation/src/main/asciidoc/userguide/chapters/query/criteria/CriteriaExtensions.adoc @@ -0,0 +1,34 @@ +[[criteria-extensions]] +== Criteria extensions +:root-project-dir: ../../../../../../../.. +:core-project-dir: {root-project-dir}/hibernate-core +:example-dir-criteria: {core-project-dir}/src/test/java/org/hibernate/orm/test/query/criteria + +Hibernate ORM provides extensions to the JPA Criteria API to allow making use of HQL features through the Criteria API. + +The `Session` interface gives access to the `org.hibernate.query.criteria.HibernateCriteriaBuilder`, +a subtype of `jakarta.persistence.criteria.CriteriaBuilder`, +through the `Session#getCriteriaBuilder()` method, which is the entry point to the extensions. + +The `HibernateCriteriaBuilder` interface offers additional methods, but also provides co-variant overridden methods, +which return subtypes of that the respective `jakarta.persistence.criteria.CriteriaBuilder` methods return types. +The subtypes are consistently named by prefixing `Jpa` i.e. `Expression` becomes `JpaExpression`. + +These subtypes provide additional methods and co-variant overrides to ease working with the extensions. + +[[criteria-extensions-count-query]] +=== Count query creation + +A very common requirement is the creation of a count query based on an existing query. +This can be done by using the `JpaCriteriaQuery#createCountQuery()` method. + +[[criteria-extensions-count-query-example]] +==== +[source, JAVA, indent=0] +---- +include::{example-dir-criteria}/CountQueryTests.java[tags=criteria-extensions-count-query-example] +---- +==== + +The resulting count query will wrap a copy of the original query as subquery in the from clause and select `count(*)`. + diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/query/CountQueryTests.java b/hibernate-core/src/test/java/org/hibernate/orm/test/query/criteria/CountQueryTests.java similarity index 97% rename from hibernate-core/src/test/java/org/hibernate/orm/test/query/CountQueryTests.java rename to hibernate-core/src/test/java/org/hibernate/orm/test/query/criteria/CountQueryTests.java index bb01efbb08..fe79235212 100644 --- a/hibernate-core/src/test/java/org/hibernate/orm/test/query/CountQueryTests.java +++ b/hibernate-core/src/test/java/org/hibernate/orm/test/query/criteria/CountQueryTests.java @@ -4,7 +4,7 @@ * 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.orm.test.query; +package org.hibernate.orm.test.query.criteria; import java.time.LocalDate; import java.util.List; @@ -129,21 +129,22 @@ public class CountQueryTests { public void testParameters(SessionFactoryScope scope) { scope.inTransaction( session -> { + //tag::criteria-extensions-count-query-example[] final HibernateCriteriaBuilder cb = session.getCriteriaBuilder(); final JpaCriteriaQuery cq = cb.createTupleQuery(); final JpaRoot root = cq.from( Contact.class ); - cq.multiselect( - root.get( "id" ), - root.get( "name" ) - ); final JpaParameterExpression parameter = cb.parameter( Contact.Gender.class ); + + cq.multiselect( root.get( "id" ), root.get( "name" ) ); cq.where( root.get( "gender" ).equalTo( parameter ) ); - final List resultList = session.createQuery( cq ) - .setParameter( parameter, Contact.Gender.FEMALE ) - .getResultList(); final Long count = session.createQuery( cq.createCountQuery() ) .setParameter( parameter, Contact.Gender.FEMALE ) .getSingleResult(); + //end::criteria-extensions-count-query-example[] + + final List resultList = session.createQuery( cq ) + .setParameter( parameter, Contact.Gender.FEMALE ) + .getResultList(); assertEquals( resultList.size(), count.intValue() ); } );