HHH-17157 - Some improvements to the metamodel generator documentation

Signed-off-by: Jan Schatteman <jschatte@redhat.com>
hibernate · Dec 1, 2023 · f78c802 · f78c802
1 parent 47bed74
commit f78c802
Show file tree

Hide file tree

Showing 6 changed files with 77 additions and 39 deletions.
diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/Query.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/hql/Query.adoc
@@ -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]]

diff --git a/...mentation/src/main/asciidoc/userguide/chapters/tooling/extras/maven-example-metamodel.pom b/...mentation/src/main/asciidoc/userguide/chapters/tooling/extras/maven-example-metamodel.pom
@@ -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>
diff --git a/documentation/src/main/asciidoc/userguide/chapters/tooling/gradle.adoc b/documentation/src/main/asciidoc/userguide/chapters/tooling/gradle.adoc
@@ -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]
 ----

diff --git a/documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc b/documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc
@@ -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[]
+----
+====
diff --git a/documentation/src/main/asciidoc/userguide/chapters/tooling/modelgen.adoc b/documentation/src/main/asciidoc/userguide/chapters/tooling/modelgen.adoc
@@ -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`.

diff --git a/migration-guide.adoc b/migration-guide.adoc
@@ -377,3 +377,11 @@ MyEntity proxy = session.getReference( MyEntity.class, 1 );
 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].
+
+