Finish up back porting documentation stuff to make Gradle backports easier
This commit is contained in:
Christian Beikov
parent
92d9844518
commit
1e3dbdb4e6
|
|
@ -4,7 +4,7 @@
|
|||
:doctype: book
|
||||
:pdf-fontsdir: ../pdf/fonts
|
||||
:docsBase: https://docs.jboss.org/hibernate/orm
|
||||
:versionDocBase: {docsBase}/6.3
|
||||
:versionDocBase: {docsBase}/6.2
|
||||
:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
|
||||
|
||||
= An introduction to Hibernate 6
|
||||
|
|
|
|||
|
|
@ -551,101 +551,6 @@ Indeed, for many years, the lack of compile-time checking for HQL queries and co
|
|||
|
||||
Fortunately, there's now a solution to both problems: as an incubating feature of Hibernate 6.3, we now offer the possibility to have the Metamodel Generator fill in the implementation of such query methods for you.
|
||||
|
||||
[[generated-query-methods]]
|
||||
=== Generated query methods
|
||||
|
||||
The Metamodel Generator is a standard part of JPA.
|
||||
// It's an annotation processor that produces a statically-typed metamodel of the entity classes in a Java program.
|
||||
We've actually already seen its handiwork in the code examples <<main-jpa,above>>: it's the author of the class `Book_` which contains the static metamodel of the <<book,entity class>> `Book`.
|
||||
|
||||
[[metamodel-generator]]
|
||||
.The Metamodel Generator
|
||||
****
|
||||
|
||||
:generator: https://hibernate.org/orm/tooling/
|
||||
:generator-guide: {userGuideBase}#tooling-modelgen
|
||||
|
||||
Hibernate's {generator}[Metamodel Generator] is an annotation processor that produces what JPA calls a _static metamodel_.
|
||||
That is, it produces a typed model of the persistent classes in our program, giving us a type-safe way to refer to their attributes in Java code.
|
||||
In particular, it lets us specify <<entity-graph,entity graphs>> and <<criteria-queries,criteria queries>> in a completely type-safe way.
|
||||
|
||||
Now, you don't have to use the Metamodel Generator with Hibernate—the APIs we just mentioned also accept plain strings—but we find that it works well with Gradle and integrates well with our IDE, and the advantage in typesafety is compelling.
|
||||
|
||||
We've already seen how to set up the annotation processor in the <<hello-hibernate,Gradle build>> we saw earlier.
|
||||
// You can find more information in the {generator-guide}[User Guide].
|
||||
****
|
||||
|
||||
_Query method generation_ is a new feature of Hibernate's implementation of the Metamodel Generator, an extension to the functionality defined by the JPA specification.
|
||||
Let's see how it works.
|
||||
|
||||
In an interface or abstract class, write down the "signature" of the query as a function, and specify the HQL or SQL query string itself using a `@HQL` or `@SQL` annotation:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
interface Queries {
|
||||
@HQL("from Book where title like :title order by title offset :start fetch first :max rows only")
|
||||
List<Book> findBooksByTitleWithPagination(String title, int max, int start);
|
||||
}
|
||||
----
|
||||
|
||||
The Metamodel Generator verifies that:
|
||||
|
||||
- the parameters of this method match the parameters of the HQL or SQL query,
|
||||
- the query is syntactically legal and semantically well-typed, that is, that the entities, attributes, and functions referenced in the query actually exist and have compatible types.
|
||||
|
||||
The `@CheckHQL` annotation which instructs Hibernate to validate named queries is not necessary for query methods.
|
||||
|
||||
[TIP]
|
||||
====
|
||||
:query-validator: https://github.com/hibernate/query-validator/
|
||||
|
||||
Don't like putting queries in annotations?
|
||||
No problem.
|
||||
If we set up the {query-validator}[Query Validator], we get validation of queries passed as strings directly to the Hibernate session.
|
||||
====
|
||||
|
||||
A query method with a similar signature and return type is generated in the corresponding static metamodel class `Queries_`.
|
||||
We can call the generated query method like this:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
List<Book> books =
|
||||
Queries_.findBooksByTitleWithPagination(entityManager, titlePattern,
|
||||
RESULTS_PER_PAGE, page*RESULTS_PER_PAGE);
|
||||
----
|
||||
|
||||
A query method doesn't need to return `List`.
|
||||
It might return a single `Book`.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@HQL("from Book where isbn = :isbn")
|
||||
Book findBookByIsbn(String isbn);
|
||||
----
|
||||
|
||||
It might even return `TypedQuery` or `SelectionQuery`:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@HQL("from Book where title like :title")
|
||||
SelectionQuery<Book> findBooksByTitle(String title);
|
||||
----
|
||||
|
||||
This is extremely useful at times, since it allows the client to further manipulate the query:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
List<Book> books =
|
||||
Queries_.findBooksByTitle(entityManager, titlePattern)
|
||||
.setOrder(Order.asc(Book_.title)) // order the results
|
||||
.setPage(Page.page(RESULTS_PER_PAGE, page)) // return the given page of results
|
||||
.setFlushMode(FlushModeType.COMMIT) // don't flush session before query execution
|
||||
.setReadOnly(true) // load the entities in read-only mode
|
||||
.setCacheStoreMode(CacheStoreMode.BYPASS) // don't cache the results
|
||||
.setComment("Hello world!") // add a comment to the generated SQL
|
||||
.getResultList();
|
||||
----
|
||||
|
||||
Now that we have a rough picture of what our persistence logic might look like, it's natural to ask how we should test this code.
|
||||
|
||||
[[testing]]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
[[credits]]
|
||||
== Credits
|
||||
|
||||
The full list of contributors to Hibernate ORM can be found on the
|
||||
https://github.com/hibernate/hibernate-orm/graphs/contributors[GitHub repository].
|
||||
|
||||
The following contributors were involved in this documentation:
|
||||
|
||||
* Gavin King
|
||||
|
|
@ -4,7 +4,7 @@
|
|||
:doctype: book
|
||||
:pdf-fontsdir: ../pdf/fonts
|
||||
:docsBase: https://docs.jboss.org/hibernate/orm
|
||||
:versionDocBase: {docsBase}/6.3
|
||||
:versionDocBase: {docsBase}/6.2
|
||||
:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
|
||||
|
||||
:root-project-dir: ../../../../..
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ In Gradle we would have:
|
|||
|
||||
[source,groovy]
|
||||
----
|
||||
implementation 'org.hibernate.orm:hibernate-core:6.3.0.Final'
|
||||
implementation 'org.hibernate.orm:hibernate-core:6.2.0.Final'
|
||||
----
|
||||
|
||||
Or in Maven:
|
||||
|
|
@ -63,7 +63,7 @@ Or in Maven:
|
|||
<dependency>
|
||||
<groupId>org.hibernate.org</groupId>
|
||||
<artifactId>hibernate-core</artifactId>
|
||||
<version>6.3.0.Final</version>
|
||||
<version>6.2.0.Final</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
|
|
|
|||
|
|
@ -220,6 +220,11 @@ public interface DeprecationLogger extends BasicLogger {
|
|||
// "This is deprecated and will be removed in a future version. Every property mapping combination should have its own java class"
|
||||
// )
|
||||
// void deprecatedComponentMapping(String name);
|
||||
@LogMessage(level = WARN)
|
||||
@Message(value = "%s does not need to be specified explicitly using 'hibernate.dialect' "
|
||||
+ "(remove the property setting and it will be selected by default)",
|
||||
id = 90000025)
|
||||
void automaticDialect(String dialect);
|
||||
|
||||
@LogMessage(level = WARN)
|
||||
@Message(value = "%s has been deprecated",
|
||||
|
|
|
|||
|
|
@ -116,16 +116,6 @@ mappings as an alternative.
|
|||
</li>
|
||||
</ul>
|
||||
|
||||
<h3>Annotations driving compile-time tooling</h3>
|
||||
|
||||
<p>
|
||||
The annotations defined by {@link org.hibernate.annotations.processing} instruct the Metamodel
|
||||
Generator to {@linkplain org.hibernate.annotations.processing.CheckHQL validate HQL at compile
|
||||
time}, and to automatically generate the implementation of
|
||||
{@linkplain org.hibernate.annotations.processing.Find finder methods} and
|
||||
{@linkplain org.hibernate.annotations.processing.HQL query methods}.
|
||||
<p>
|
||||
|
||||
<h3>Bootstrapping Hibernate</h3>
|
||||
|
||||
<p>
|
||||
|
|
|
|||
|
|
@ -152,16 +152,6 @@ mappings as an alternative.
|
|||
to use a tiny handful of them.
|
||||
</p>
|
||||
|
||||
<h3>Annotations driving compile-time tooling</h3>
|
||||
|
||||
<p>
|
||||
The annotations defined by {@link org.hibernate.annotations.processing} instruct the Metamodel
|
||||
Generator to {@linkplain org.hibernate.annotations.processing.CheckHQL validate HQL at compile
|
||||
time}, and to automatically generate the implementation of
|
||||
{@linkplain org.hibernate.annotations.processing.Find finder methods} and
|
||||
{@linkplain org.hibernate.annotations.processing.HQL query methods}.
|
||||
<p>
|
||||
|
||||
<h3>Popular extension points</h3>
|
||||
|
||||
<p>
|
||||
|
|
|
|||
Loading…
Reference in New Issue