HHH-17157 - Some improvements to the metamodel generator documentation
Signed-off-by: Jan Schatteman <jschatte@redhat.com>
This commit is contained in:
Jan Schatteman
Steve Ebersole
parent
75f173a4a0
commit
e24511f415
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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]]
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
@ -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]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -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[]
|
||||
----
|
||||
====
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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].
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue