Skip to content

Commit 7ed52db

Browse files
velovelo
committed
Add Hibernate tutorial and cross-references from JPA docs
Signed-off-by: Marvin Froeder <velo.br@gmail.com>
1 parent eaa9fa9 commit 7ed52db

2 files changed

Lines changed: 192 additions & 4 deletions

File tree

‎docs/tutorials/hibernate.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
layout: default
3+
title: Querying Hibernate
4+
parent: Tutorials
5+
nav_order: 6
6+
---
7+
8+
# Querying Hibernate
9+
10+
Querydsl provides Hibernate-specific extensions on top of the standard JPA
11+
support. For common features such as basic querying, joins, subqueries, and DML
12+
operations, see the [JPA tutorial]({{ site.baseurl }}/tutorials/jpa).
13+
14+
This page covers features exclusive to the Hibernate API.
15+
16+
## Maven Integration
17+
18+
The Hibernate integration uses the same `querydsl-jpa` artifact:
19+
20+
```xml
21+
<dependency>
22+
<groupId>{{ site.group_id }}</groupId>
23+
<artifactId>querydsl-jpa</artifactId>
24+
<version>{{ site.querydsl_version }}</version>
25+
</dependency>
26+
```
27+
28+
If your domain model uses Hibernate-specific annotations, configure the
29+
annotation processor with `HibernateAnnotationProcessor`:
30+
31+
```xml
32+
<plugin>
33+
<artifactId>maven-compiler-plugin</artifactId>
34+
<configuration>
35+
<generatedSourcesDirectory>target/generated-sources/java</generatedSourcesDirectory>
36+
</configuration>
37+
<dependencies>
38+
<dependency>
39+
<groupId>{{ site.group_id }}</groupId>
40+
<artifactId>querydsl-apt</artifactId>
41+
<version>{{ site.querydsl_version }}</version>
42+
<classifier>jpa</classifier>
43+
</dependency>
44+
<dependency>
45+
<groupId>jakarta.persistence</groupId>
46+
<artifactId>jakarta.persistence-api</artifactId>
47+
<version>3.1.0</version>
48+
</dependency>
49+
</dependencies>
50+
</plugin>
51+
```
52+
53+
For standard JPA annotations, `JPAAnnotationProcessor` works as well. See the
54+
[JPA tutorial]({{ site.baseurl }}/tutorials/jpa) for details.
55+
56+
## Creating Queries
57+
58+
Use `HibernateQuery` with a Hibernate `Session`:
59+
60+
```java
61+
HibernateQuery<?> query = new HibernateQuery<Void>(session);
62+
```
63+
64+
Or use `HibernateQueryFactory` as the recommended approach:
65+
66+
```java
67+
HibernateQueryFactory queryFactory = new HibernateQueryFactory(session);
68+
```
69+
70+
All standard JPQL query operations (`from`, `where`, `join`, `groupBy`,
71+
`orderBy`, etc.) work the same way as described in the
72+
[JPA tutorial]({{ site.baseurl }}/tutorials/jpa).
73+
74+
`HibernateQuery` also supports `StatelessSession`:
75+
76+
```java
77+
HibernateQuery<?> query = new HibernateQuery<Void>(statelessSession);
78+
```
79+
80+
## Hibernate-Specific Query Options
81+
82+
`HibernateQuery` provides several options not available on `JPAQuery`.
83+
84+
### Query Caching
85+
86+
```java
87+
List<Cat> cats = queryFactory.selectFrom(cat)
88+
.where(cat.name.startsWith("A"))
89+
.setCacheable(true)
90+
.setCacheRegion("catCache")
91+
.fetch();
92+
```
93+
94+
### Read-Only Mode
95+
96+
Entities loaded in read-only mode are never dirty-checked:
97+
98+
```java
99+
List<Cat> cats = queryFactory.selectFrom(cat)
100+
.setReadOnly(true)
101+
.fetch();
102+
```
103+
104+
### SQL Comments
105+
106+
```java
107+
List<Cat> cats = queryFactory.selectFrom(cat)
108+
.setComment("load cats by name")
109+
.fetch();
110+
```
111+
112+
### Lock Modes
113+
114+
```java
115+
List<Cat> cats = queryFactory.selectFrom(cat)
116+
.setLockMode(cat, LockMode.PESSIMISTIC_WRITE)
117+
.fetch();
118+
```
119+
120+
### Flush Mode
121+
122+
```java
123+
List<Cat> cats = queryFactory.selectFrom(cat)
124+
.setFlushMode(FlushMode.AUTO)
125+
.fetch();
126+
```
127+
128+
### Fetch Size and Timeout
129+
130+
```java
131+
List<Cat> cats = queryFactory.selectFrom(cat)
132+
.setFetchSize(50)
133+
.setTimeout(30)
134+
.fetch();
135+
```
136+
137+
### Scrollable Results
138+
139+
```java
140+
ScrollableResults results = queryFactory.selectFrom(cat)
141+
.createQuery()
142+
.scroll(ScrollMode.FORWARD_ONLY);
143+
```
144+
145+
## Exposing the Original Query
146+
147+
To access the underlying Hibernate `Query` directly:
148+
149+
```java
150+
Query hibernateQuery = queryFactory.selectFrom(cat).createQuery();
151+
List results = hibernateQuery.list();
152+
```
153+
154+
This returns a Hibernate `org.hibernate.query.Query` rather than a JPA
155+
`jakarta.persistence.Query`.
156+
157+
## Native SQL with Hibernate
158+
159+
Use `HibernateSQLQuery` to run native SQL through a Hibernate `Session`:
160+
161+
```java
162+
SQLTemplates templates = new H2Templates();
163+
HibernateSQLQuery<?> query = new HibernateSQLQuery<Void>(session, templates);
164+
List<String> names = query.select(cat.name).from(cat).fetch();
165+
```
166+
167+
See the [JPA tutorial]({{ site.baseurl }}/tutorials/jpa#using-native-sql-in-jpa-queries)
168+
for more details on native SQL query patterns.
169+
170+
## Comparison with JPAQuery
171+
172+
| Feature | JPAQuery | HibernateQuery |
173+
|---|---|---|
174+
| Underlying API | JPA EntityManager | Hibernate Session |
175+
| Query factory | `JPAQueryFactory` | `HibernateQueryFactory` |
176+
| Query caching | Not available | `setCacheable()`, `setCacheRegion()` |
177+
| Read-only mode | Not available | `setReadOnly()` |
178+
| SQL comments | Not available | `setComment()` |
179+
| Lock modes | JPA lock modes | Hibernate `LockMode` per path |
180+
| Flush mode | Not available | `setFlushMode()` |
181+
| Scrollable results | Not available | `scroll(ScrollMode)` |
182+
| StatelessSession | Not available | Supported |
183+
| Native SQL class | `JPASQLQuery` | `HibernateSQLQuery` |

‎docs/tutorials/jpa.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,9 @@ The `JPAAnnotationProcessor` finds domain types annotated with the
5656
`jakarta.persistence.Entity` annotation and generates query types for them.
5757

5858
If you use Hibernate annotations in your domain types, use the processor
59-
`com.querydsl.apt.hibernate.HibernateAnnotationProcessor` instead.
59+
`com.querydsl.apt.hibernate.HibernateAnnotationProcessor` instead. See the
60+
[Hibernate tutorial]({{ site.baseurl }}/tutorials/hibernate) for
61+
Hibernate-specific features such as query caching and read-only mode.
6062

6163
Run `mvn clean install` and your query types will be generated into
6264
`target/generated-sources/java`.
@@ -153,8 +155,9 @@ Both `JPAQuery` and `HibernateQuery` implement the `JPQLQuery` interface.
153155

154156
For the examples in this chapter, queries are created via a `JPAQueryFactory`
155157
instance. `JPAQueryFactory` should be the preferred option for obtaining
156-
`JPAQuery` instances. For the Hibernate API, `HibernateQueryFactory` can be
157-
used.
158+
`JPAQuery` instances. For the Hibernate API, `HibernateQueryFactory` can be used. For
159+
Hibernate-specific features, see the
160+
[Hibernate tutorial]({{ site.baseurl }}/tutorials/hibernate).
158161

159162
To retrieve the customer with the first name Bob:
160163

@@ -469,4 +472,6 @@ List<CatDTO> catDTOs = query.select(Projections.constructor(CatDTO.class, cat.id
469472
```
470473

471474
If you use the Hibernate API instead of the JPA API, use `HibernateSQLQuery`
472-
instead.
475+
instead. See the
476+
[Hibernate tutorial]({{ site.baseurl }}/tutorials/hibernate) for more
477+
details on `HibernateSQLQuery` and other Hibernate-specific features.

0 commit comments

Comments
 (0)