Skip to content

Commit c2150ff

Browse files
committed
HHH-11186 - Add examples for all Hibernate annotations
Document @subselect and @synchronize annotations
1 parent f164223 commit c2150ff

File tree

3 files changed

+341
-10
lines changed

3 files changed

+341
-10
lines changed

documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1222,7 +1222,7 @@ See the <<chapters/query/native/Native.adoc#sql-custom-crud-example, Custom CRUD
12221222

12231223
The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Subselect.html[`@Subselect`] annotation is used to specify an immutable and read-only entity using a custom SQL `SELECT` statement.
12241224

1225-
//TODO: Add example
1225+
See the <<chapters/domain/entity.adoc#entity-sql-query-mapping, Mapping the entity to a SQL query>> section for more info.
12261226

12271227
[[annotations-hibernate-synchronize]]
12281228
==== `@Synchronize`
@@ -1233,23 +1233,22 @@ With this information in place, Hibernate will properly trigger an entity flush
12331233

12341234
Therefore, the `@Synchronize` annotation prevents the derived entity from returning stale data when executing entity queries against the `@Subselect` entity.
12351235

1236-
//TODO: Add example
1236+
See the <<chapters/domain/entity.adoc#entity-sql-query-mapping, Mapping the entity to a SQL query>> section for more info.
12371237

12381238
[[annotations-hibernate-table]]
12391239
==== `@Table`
12401240

12411241
The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Table.html[`@Table`] annotation is used to specify additional information to a JPA <<annotations-hibernate-table>> annotation, like custom `INSERT`, `UPDATE` or `DELETE` statements or a specific https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/FetchMode.html[`FetchMode`].
12421242

1243-
//TODO: Add example
1243+
See the <<chapters/query/native/Native.adoc#sql-custom-crud-secondary-table-example, `@SecondaryTable` mapping>> section for more info about Hibernate-specific `@Table` mapping.
12441244

12451245
[[annotations-hibernate-tables]]
12461246
==== `@Tables`
12471247

12481248
The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Tables.html[`@Tables`] annotation is used to group multiple <<annotations-hibernate-table>> annotations.
12491249

12501250
[[annotations-hibernate-target]]
1251-
==== `@Target`
1252-
1251+
==== `@Target`Se
12531252
The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Target.html[`@Target`] annotation is used to specify an explicit target implementation when the current annotated association is using an interface type.
12541253

12551254
See the <<chapters/domain/basic_types.adoc#mapping-Target,`@Target` mapping>> section for more info.

documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
[[entity]]
22
=== Entity types
3-
:sourcedir: ../../../../../test/java/org/hibernate/userguide/locking
3+
:sourcedir-locking: ../../../../../test/java/org/hibernate/userguide/locking
4+
:sourcedir-mapping: ../../../../../test/java/org/hibernate/userguide/mapping/basic
45
:extrasdir: extras
56

67
.Usage of the word _entity_
@@ -335,7 +336,7 @@ There are 4 available OptimisticLockTypes:
335336
====
336337
[source,java]
337338
----
338-
include::{sourcedir}/OptimisticLockTypeAllTest.java[tag=locking-optimistic-lock-type-all-example,indent=0]
339+
include::{sourcedir-locking}/OptimisticLockTypeAllTest.java[tag=locking-optimistic-lock-type-all-example,indent=0]
339340
----
340341
====
341342

@@ -346,7 +347,7 @@ When you need to modify the `Person` entity above:
346347
====
347348
[source,java]
348349
----
349-
include::{sourcedir}/OptimisticLockTypeAllTest.java[tag=locking-optimistic-lock-type-all-update-example,indent=0]
350+
include::{sourcedir-locking}/OptimisticLockTypeAllTest.java[tag=locking-optimistic-lock-type-all-update-example,indent=0]
350351
----
351352
352353
[source,SQL]
@@ -376,7 +377,7 @@ since the entity was loaded in the currently running Persistence Context.
376377
====
377378
[source,java]
378379
----
379-
include::{sourcedir}/OptimisticLockTypeDirtyTest.java[tag=locking-optimistic-lock-type-dirty-example,indent=0]
380+
include::{sourcedir-locking}/OptimisticLockTypeDirtyTest.java[tag=locking-optimistic-lock-type-dirty-example,indent=0]
380381
----
381382
====
382383

@@ -387,7 +388,7 @@ When you need to modify the `Person` entity above:
387388
====
388389
[source,java]
389390
----
390-
include::{sourcedir}/OptimisticLockTypeDirtyTest.java[tag=locking-optimistic-lock-type-dirty-update-example,indent=0]
391+
include::{sourcedir-locking}/OptimisticLockTypeDirtyTest.java[tag=locking-optimistic-lock-type-dirty-update-example,indent=0]
391392
----
392393
393394
[source,SQL]
@@ -408,3 +409,49 @@ When using `OptimisticLockType.DIRTY`, you should also use `@DynamicUpdate` beca
408409
and also the `@SelectBeforeUpdate` annotation so that detached entities are properly handled by the
409410
https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/Session.html#update-java.lang.Object-[`Session#update(entity)`] operation.
410411
====
412+
413+
[[entity-sql-query-mapping]]
414+
==== Mapping the entity to a SQL query
415+
416+
You can map an entity to a SQL query using the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Subselect.html[`@Subselect`] annotation.
417+
418+
[[mapping-Subselect-example]]
419+
.`@Subselect` entity mapping
420+
====
421+
[source,java]
422+
----
423+
include::{sourcedir-mapping}/SubselectTest.java[tag=mapping-Subselect-example,indent=0]
424+
----
425+
====
426+
427+
In the example above, the `Account` entity does not retain any balance since every account operation is registered as an `AccountTransaction`.
428+
To find the `Account` balance, we need to query the `AccountSummary` which shares the same identifier with the `Account` entity.
429+
430+
However, the `AccountSummary` is not mapped to a physical table, but to an SQL query.
431+
432+
So, if we have the following `AccountTransaction` record, the `AccountSummary` balance will mach the proper amount of money in this `Account`.
433+
434+
[[mapping-Subselect-entity-find-example]]
435+
.Finding a `@Subselect` entity
436+
====
437+
[source,java]
438+
----
439+
include::{sourcedir-mapping}/SubselectTest.java[tag=mapping-Subselect-entity-find-example,indent=0]
440+
----
441+
====
442+
443+
If we add a new `AccountTransaction` entity and refresh the `AccountSummary` entity, the balance is updated accordingly:
444+
445+
[[mapping-Subselect-refresh-find-example]]
446+
.Refreshing a `@Subselect` entity
447+
====
448+
[source,java]
449+
----
450+
include::{sourcedir-mapping}/SubselectTest.java[tag=mapping-Subselect-entity-refresh-example,indent=0]
451+
----
452+
====
453+
454+
The goala of the `@Synchronize` annotation in the `AccountSummary` entity mapping is to instruct Hibernate which database tables are needed by the
455+
underlying `@Subselect` SQL query. This way, when executing a HQL or JPQL which selects from the `AccountSummary` entity,
456+
Hibernate will trigger a Persistence Context flush if there are pending `Account`, `Client` or `AccountTransaction` entity state transitions.
457+

0 commit comments

Comments
 (0)