Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update the docs to reflect the new @SQL annotations

This commit is contained in:
Gavin 2023-04-09 19:32:59 +02:00
parent d34a0899a2
commit 511399c152
4 changed files with 29 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc
View File

@ -1406,18 +1406,18 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
See the <<chapters/domain/basic_types.adoc#mapping-database-generated-value-example,`@ValueGenerationType` mapping>> section for more info.
[[annotations-hibernate-where]]
==== `@Where`
==== `@SQLRestriction`
The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Where.html[`@Where`] annotation is used to specify a custom SQL `WHERE` clause used when fetching an entity or a collection.
The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/SQLRestriction.html[`@SQLRestriction`] annotation is used to specify a custom SQL `WHERE` clause used when fetching an entity or a collection.
See the <<chapters/pc/PersistenceContext.adoc#pc-where-example,`@Where` mapping>> section for more info.
See the <<chapters/pc/PersistenceContext.adoc#pc-where-example,`@SQLRestriction` mapping>> section for more info.
[[annotations-hibernate-wherejointable]]
==== `@WhereJoinTable`
==== `@SQLJoinTableRestriction`
The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/WhereJoinTable.html[`@WhereJoinTable`] annotation is used to specify a custom SQL `WHERE` clause used when fetching a join collection table.
The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/SQLJoinTableRestriction.html[`@SQLJoinTableRestriction`] annotation is used to specify a custom SQL `WHERE` clause used when fetching a join collection table.
See the <<chapters/pc/PersistenceContext.adoc#pc-where-join-table, `@WhereJoinTable` mapping>> section for more info.
See the <<chapters/pc/PersistenceContext.adoc#pc-where-join-table, `@SQLJoinTableRestriction` mapping>> section for more info.
[[annotations-hibernate-tenantid]]

32
documentation/src/main/asciidoc/userguide/chapters/pc/PersistenceContext.adoc
View File

@ -345,18 +345,18 @@ Locking is discussed in a separate <<chapters/locking/Locking.adoc#locking,chapt
Hibernate offers two options if you want to filter entities or entity associations:
static (e.g. `@Where` and `@WhereJoinTable`):: which are defined at mapping time and
static (e.g. `@SQLRestriction` and `@SQLJoinTableRestriction`):: which are defined at mapping time and
cannot change at runtime.
dynamic (e.g. `@Filter` and `@FilterJoinTable`):: which are applied and configured at runtime.
[[pc-where]]
==== `@Where`
==== `@SQLRestriction`
Sometimes, you want to filter out entities or collections using custom SQL criteria.
This can be achieved using the `@Where` annotation, which can be applied to entities and collections.
This can be achieved using the `@SQLRestriction` annotation, which can be applied to entities and collections.
[[pc-where-example]]
.`@Where` mapping usage
.`@SQLRestriction` mapping usage
====
[source, JAVA, indent=0]
----
@ -367,7 +367,7 @@ include::{example-dir-pc}/WhereTest.java[tags=pc-where-example]
If the database contains the following entities:
[[pc-where-persistence-example]]
.Persisting and fetching entities with a `@Where` mapping
.Persisting and fetching entities with a `@SQLRestriction` mapping
====
[source, JAVA, indent=0]
----
@ -383,7 +383,7 @@ include::{extrasdir}/pc-where-persistence-example.sql[]
When executing an `Account` entity query, Hibernate is going to filter out all records that are not active.
[[pc-where-entity-query-example]]
.Query entities mapped with `@Where`
.Query entities mapped with `@SQLRestriction`
====
[source, JAVA, indent=0]
----
@ -396,10 +396,10 @@ include::{extrasdir}/pc-where-entity-query-example.sql[]
----
====
When fetching the `debitAccounts` or the `creditAccounts` collections, Hibernate is going to apply the `@Where` clause filtering criteria to the associated child entities.
When fetching the `debitAccounts` or the `creditAccounts` collections, Hibernate is going to apply the `@SQLRestriction` clause filtering criteria to the associated child entities.
[[pc-where-collection-query-example]]
.Traversing collections mapped with `@Where`
.Traversing collections mapped with `@SQLRestriction`
====
[source, JAVA, indent=0]
----
@ -413,12 +413,12 @@ include::{extrasdir}/pc-where-collection-query-example.sql[]
====
[[pc-where-join-table]]
==== `@WhereJoinTable`
==== `@SQLJoinTableRestriction`
Just like `@Where` annotation, `@WhereJoinTable` is used to filter out collections using a joined table (e.g. @ManyToMany association).
Just like `@SQLRestriction` annotation, `@SQLJoinTableRestriction` is used to filter out collections using a joined table (e.g. @ManyToMany association).
[[pc-where-join-table-example]]
.`@WhereJoinTable` mapping example
.`@SQLJoinTableRestriction` mapping example
====
[source, JAVA, indent=0]
----
@ -432,12 +432,12 @@ include::{extrasdir}/pc-where-join-table-example.sql[]
====
In the example above, the current week `Reader` entities are included in the `currentWeekReaders` collection
which uses the `@WhereJoinTable` annotation to filter the joined table rows according to the provided SQL clause.
which uses the `@SQLJoinTableRestriction` annotation to filter the joined table rows according to the provided SQL clause.
Considering that the following two `Book_Reader` entries are added into our system:
[[pc-where-join-table-persist-example]]
.`@WhereJoinTable` test data
.`@SQLJoinTableRestriction` test data
====
[source, JAVA, indent=0]
----
@ -448,7 +448,7 @@ include::{example-dir-pc}/WhereJoinTableTest.java[tags=pc-where-join-table-persi
When fetching the `currentWeekReaders` collection, Hibernate is going to find only one entry:
[[pc-where-join-table-fetch-example]]
.`@WhereJoinTable` fetch example
.`@SQLJoinTableRestriction` fetch example
====
[source, JAVA, indent=0]
----
@ -460,7 +460,7 @@ include::{example-dir-pc}/WhereJoinTableTest.java[tags=pc-where-join-table-fetch
==== `@Filter`
The `@Filter` annotation is another way to filter out entities or collections using custom SQL criteria.
Unlike the `@Where` annotation, `@Filter` allows you to parameterize the filter clause at runtime.
Unlike the `@SQLRestriction` annotation, `@Filter` allows you to parameterize the filter clause at runtime.
Now, considering we have the following `Account` entity:
@ -596,7 +596,7 @@ include::{extrasdir}/pc-filter-collection-query-example.sql[]
[NOTE]
====
The main advantage of `@Filter` over the `@Where` clause is that the filtering criteria can be customized at runtime.
The main advantage of `@Filter` over the `@SQLRestriction` clause is that the filtering criteria can be customized at runtime.
====
[WARNING]

6
documentation/src/main/asciidoc/userguide/chapters/query/native/Native.adoc
View File

@ -879,10 +879,10 @@ For columns, see <<chapters/domain/basic_types.adoc#mapping-column-read-and-writ
The following example shows how to define custom SQL operations using annotations.
`@SQLInsert`, `@SQLUpdate`, and `@SQLDelete` override the INSERT, UPDATE, DELETE statements of a given entity.
For the SELECT clause, a `@Loader` must be defined along with a `@NamedNativeQuery` used for loading the underlying table record.
Similarly, `@SQLSelect` specifies a custom SELECT query used for loading the underlying table record.
For collections, Hibernate allows defining a custom `@SQLDeleteAll` which is used for removing all child records associated with a given parent entity.
To filter collections, the `@Where` annotation allows customizing the underlying SQL WHERE clause.
To filter collections, the `@SQLRestriction` annotation allows customizing the underlying SQL WHERE clause.
[[sql-custom-crud-example]]
.Custom CRUD
@ -895,7 +895,7 @@ include::{doc-emeddable-example-dir}/CustomSQLTest.java[tags=sql-custom-crud-exa
In the example above, the entity is mapped so that entries are soft-deleted (the records are not removed from the database, but instead, a flag marks the row validity).
The `Person` entity benefits from custom INSERT, UPDATE, and DELETE statements which update the `valid` column accordingly.
The custom `@Loader` is used to retrieve only `Person` rows that are valid.
The custom `@SQLSelect` is used to retrieve only `Person` rows that are valid.
The same is done for the `phones` collection. The `@SQLDeleteAll` and the `SQLInsert` queries are used whenever the collection is modified.

17
hibernate-core/src/test/java/org/hibernate/orm/test/sql/CustomSQLTest.java
View File

@ -15,16 +15,14 @@ import jakarta.persistence.ElementCollection;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.NamedNativeQueries;
import jakarta.persistence.NamedNativeQuery;
import org.hibernate.Session;
import org.hibernate.annotations.Loader;
import org.hibernate.annotations.ResultCheckStyle;
import org.hibernate.annotations.SQLDelete;
import org.hibernate.annotations.SQLDeleteAll;
import org.hibernate.annotations.SQLInsert;
import org.hibernate.annotations.SQLRestriction;
import org.hibernate.annotations.SQLSelect;
import org.hibernate.annotations.SQLUpdate;
import org.hibernate.dialect.H2Dialect;
import org.hibernate.dialect.PostgreSQLDialect;
@ -119,16 +117,9 @@ public class CustomSQLTest extends BaseEntityManagerFunctionalTestCase {
@SQLDelete(
sql = "UPDATE person SET valid = false WHERE id = ? "
)
@Loader(namedQuery = "find_valid_person")
@NamedNativeQueries({
@NamedNativeQuery(
name = "find_valid_person",
query = "SELECT id, name " +
"FROM person " +
"WHERE id = ? and valid = true",
resultClass = Person.class
)
})
@SQLSelect(
sql ="SELECT id, name FROM person WHERE id = ? and valid = true"
)
public static class Person {
@Id