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

HHH-17157 - Some improvements to the metamodel generator documentation 

Signed-off-by: Jan Schatteman <jschatte@redhat.com>
This commit is contained in:
Jan Schatteman 2023-09-28 22:50:51 +02:00 committed by Steve Ebersole
parent 75f173a4a0
commit e24511f415
7 changed files with 78 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
documentation/src/main/asciidoc/introduction/Generator.adoc
View File

@ -38,6 +38,7 @@ Now, you still don't have to use the Metamodel Generator with Hibernate—the AP
[TIP]
====
We've already seen how to set up the annotation processor in the <<hello-hibernate,Gradle build>> we saw earlier.
For more details on how to integrate the Metamodel Generator, check out the {generator-guide}[Static Metamodel Generator] section in the User Guide.
====
Here's an example of the sort of code that's generated for an entity class, as mandated by the JPA specification:

11
documentation/src/main/asciidoc/userguide/chapters/query/hql/Query.adoc
View File

@ -364,17 +364,6 @@ include::{example-dir-query}/HQLTest.java[tags=hql-api-basic-usage-example]
A program may hook into the process of building the query results by providing a `org.hibernate.transform.ResultListTransformer` or `org.hibernate.transform.TupleTransformer`.
Hibernate provides several some built-in implementations of these interfaces, for example:
[[hql-api-result-transformers-example]]
.Using a `ResultListTransformer`
====
[source, JAVA, indent=0]
----
include::{example-dir-query}/SelectDistinctTest.java[tags=hql-distinct-entity-resulttransformer-example]
----
====
See the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/transform/ResultListTransformer.html[Javadocs] along with the built-in implementations for additional details.
//[[hql-api-parameters]]

27
documentation/src/main/asciidoc/userguide/chapters/tooling/extras/maven-example-metamodel.pom Normal file
View File

@ -0,0 +1,27 @@
<build>
<plugins>
[...]
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>...</version>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>org.hibernate.orm</groupId>
<artifactId>hibernate-jpamodelgen</artifactId>
<version>$currentHibernateVersion</version>
<!-- Optionally exclude transitive dependencies -->
<exclusions>
<exclusion>
<groupId>org.sample</groupId>
<artifactId>sample-dependency</artifactId>
</exclusion>
</exclusions>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
[...]
</plugins>
</build>

40
documentation/src/main/asciidoc/userguide/chapters/tooling/gradle.adoc
View File

@ -1,10 +1,14 @@
[[tooling-gradle]]
=== Gradle Plugin
=== Gradle
For integrating with https://gradle.org[Gradle], Hibernate provides the
https://plugins.gradle.org/plugin/org.hibernate.orm[org.hibernate.orm] plugin which
supports bytecode enhancement and static metamodel generation but not schema tooling.
Hibernate provides the ability to integrate both
<<tooling-gradle-enhancement,bytecode enhancement>> and <<tooling-gradle-modelgen,metamodel generation>> capabilities into Gradle builds.
[[tooling-gradle-enhancement]]
==== Bytecode Enhancement
Bytecode enhancement is incorporated into Gradle builds using Hibernate's
https://plugins.gradle.org/plugin/org.hibernate.orm[Gradle plugin].
To apply the plugin, use Gradle's `plugins {}` block:
[source,gradle]
@ -14,24 +18,18 @@ plugins {
}
----
Applying the plugin creates a `hibernate` extension (`HibernateOrmSpec`) to configure the plugin.
By default, when the plugin is applied, support for both bytecode enhancement and static metamodel
generation is enabled.
[source,gradle]
----
hibernate {
// for illustration, let's disable both
disableEnhancement
disableJpaMetamodel
...
}
----
[[tooling-gradle-enhancement]]
==== Bytecode Enhancement
Enhancement is configured through the `enhancement` extension.
Enhancement is configured through the `enhancement` extension:
NOTE: `hibernate {}` and `enhancement {}` are separate to allow for schema tooling capabilities to be added later.
[source,gradle]
----
@ -47,13 +45,9 @@ hibernate {
The extension is of type `EnhancementSpec` which exposes the following properties:
enableLazyInitialization:: Whether to incorporate lazy loading support into the enhanced bytecode. Defaults to `true`. This setting is deprecated for removal without a replacement.
enableDirtyTracking:: Whether to incorporate dirty tracking into the enhanced bytecode. Defaults to `true`. This setting is deprecated for removal without a replacement.
enableAssociationManagement:: Whether to add bidirectional association management into the enhanced bytecode
Which all default to false (disabled).
enableLazyInitialization:: Whether to incorporate lazy loading support into the enhanced bytecode. Defaults to `true`. This setting is deprecated for removal without a replacement. See <<BytecodeEnhancement-lazy-loading>>
enableDirtyTracking:: Whether to incorporate dirty tracking into the enhanced bytecode. Defaults to `true`. This setting is deprecated for removal without a replacement. See <<BytecodeEnhancement-dirty-tracking>>.
enableAssociationManagement:: Whether to add bidirectional association management into the enhanced bytecode. See <<BytecodeEnhancement-dirty-tracking-bidirectional>>.
It also exposes the following method forms:
@ -65,8 +59,10 @@ It also exposes the following method forms:
[[tooling-gradle-modelgen]]
==== Static Metamodel Generation
One approach to integrate Static Metamodel generation into a Gradle build is to
use Gradle's support for annotation processors -
Static metamodel generation can be incorporated into Gradle builds via the
annotation processor provided by the `hibernate-jpamodelgen` artifact. Applying
an annotation processor in Gradle is super easy -
[source,gradle]
----

24
documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc
View File

@ -1,16 +1,34 @@
[[tooling-maven]]
=== Maven Plugin
=== Maven
The following sections illustrate how both <<tooling-maven-enhancement,bytecode enhancement>> and <<tooling-maven-modelgen,metamodel generation>> capabilities can be integrated into Maven builds.
[[tooling-maven-enhancement]]
==== Bytecode Enhancement
Hibernate provides a https://maven.apache.org/[Maven] plugin capable of providing
build-time enhancement of the domain model as they are compiled as part of a Maven
build. See the section on the <<tooling-gradle>> for details
build. See the section on <<BytecodeEnhancement>> for details
on the configuration settings. By default, all enhancements are disabled.
.Apply the Maven plugin
.Apply the Bytecode Enhancement plugin
====
[source,xml]
----
include::extras/maven-example.pom[]
----
====
[[tooling-maven-modelgen]]
==== Static Metamodel Generation
The recommended way to integrate the metamodel generation into a maven project is through the annotation processor paths of the maven compiler plugin (roughly equivalent to how the generator is integrated in a gradle project).
.Integrate the metamodel generator
====
[source,xml]
----
include::extras/maven-example-metamodel.pom[]
----
====

4
documentation/src/main/asciidoc/userguide/chapters/tooling/modelgen.adoc
View File

@ -15,10 +15,10 @@ static metamodel classes.
See <<criteria>> for discussion of Jakarta Persistence criteria queries.
The Hibernate Static Metamodel Generator is defined by the published `org.hibernate.orm:metamodel-generator`
The Hibernate Static Metamodel Generator is defined by the published `org.hibernate.orm:hibernate-jpamodelgen`
artifact. As it is defined as an
https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-082C33A5-CBCA-471A-845E-E77F79B7B049[annotation processor],
it is usable anytime `javac` is used. See the tool-specific discussions (<<tooling-gradle,Gradle>>, <<tooling-maven,Maven>>
it is usable anytime `javac` is used. See the tool-specific discussions (<<tooling-gradle-modelgen,Gradle>>, <<tooling-maven-modelgen,Maven>>
and <<tooling-ant,Ant>>) for details on integrating the generator into those environments.
NOTE:: The fully qualified name of the processor class is `org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor`.

8
migration-guide.adoc
View File

@ -48,3 +48,11 @@ MyEntity myEntity = session.find(MyEntity.class, 2, LockMode.WRITE);
```
only the entity with id equals to 2 will be loaded but the proxy will not be initialized.
[[metamodel-generation]]
== Integrating Static Metamodel Generation
The integration of static metamodel generation in a project has changed; the recommended way to do this now is by harnessing the annotation processor classpath. This is true for both gradle and maven.
Check out the specific sections in the User Guide for a guideline on how to do this for {userGuideBase}#tooling-gradle-modelgen[Gradle] or {userGuideBase}#tooling-maven-modelgen[Maven].