Skip to content

Commit da52284

Browse files
sebersolesebersole
committed
HHH-17157 - Some improvements to the metamodel generator documentation
1 parent 8127428 commit da52284

File tree

4 files changed

+72
-61
lines changed

4 files changed

+72
-61
lines changed

‎documentation/src/main/asciidoc/userguide/chapters/tooling/gradle.adoc

Lines changed: 1 addition & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ It also exposes the following method forms:
6060
==== Static Metamodel Generation
6161

6262
Static metamodel generation can be incorporated into Gradle builds via the
63-
annotation processor provided by the `hibernate-jpamodelgen` artifact. Applying
63+
annotation processor provided by the `org.hibernate.orm:hibernate-jpamodelgen` artifact. Applying
6464
an annotation processor in Gradle is super easy -
6565

6666

@@ -70,40 +70,3 @@ dependencies {
7070
annotationProcessor "org.hibernate.orm:hibernate-jpamodelgen:${hibernateVersion}"
7171
}
7272
----
73-
74-
When the build does not need bytecode enhancement support, this is a perfectly valid solution.
75-
76-
The plugin supports simpler configuration of the generator using the registered
77-
`jpaMetamodel` extension:
78-
79-
80-
[source,gradle]
81-
----
82-
hibernate {
83-
jpaMetamodel {
84-
applyGeneratedAnnotation false
85-
suppress 'raw'
86-
generationOutputDirectory "${buildDir}/generated/sources/modelgen"
87-
compileOutputDirectory "${buildDir}/classes/java/modelgen"
88-
}
89-
}
90-
----
91-
92-
The extension is of type `JpaMetamodelGenerationSpec`, which exposes the following configuration properties:
93-
94-
applyGeneratedAnnotation:: Should the `javax.annotation.processing.Generated` annotation be added to the
95-
generated classes. Defaults to `true`.
96-
suppressions:: Suppressions to add to the generated classes. Defaults to `['raw', 'deprecation']`
97-
generationOutputDirectory:: Directory where the generated metamodel classes should be created. Defaults
98-
to `${buildDir}/generated/sources/jpaMetamodel`
99-
[[tooling-gradle-modelgen-compile-output]]
100-
compileOutputDirectory:: Directory where the classes compiled from the generated metamodel classes should be
101-
created. Defaults to `${buildDir}/classes/java/jpaMetamodel`.
102-
103-
It also exposes the following method forms:
104-
105-
* applyGeneratedAnnotation(boolean)
106-
* suppress(String)
107-
* generationOutputDirectory(Object)
108-
* compileOutputDirectory(Object)
109-

‎documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@ include::extras/maven-example.pom[]
2323
[[tooling-maven-modelgen]]
2424
==== Static Metamodel Generation
2525

26-
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).
26+
Static metamodel generation should be integrated into a maven project through the annotation processor
27+
paths of the maven compiler plugin.
2728

2829
.Integrate the metamodel generator
2930
====

‎documentation/src/main/asciidoc/userguide/chapters/tooling/modelgen.adoc

Lines changed: 35 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -6,31 +6,30 @@
66
:example-dir-metamodelgen-generated: {testing-project-dir}/target/generated/sources/annotationProcessor/java/main/org/hibernate/testing/orm/domain/userguide
77
:core-project-dir: {root-project-dir}/hibernate-core
88
:toolingTestsDir: {core-project-dir}/src/test/java/org/hibernate/orm/test/tooling
9-
10-
Jakarta Persistence defines a typesafe Criteria API which allows `Criteria` queries to be constructed in a
11-
strongly-typed manner, utilizing so-called static metamodel classes. For developers, it is important that
12-
the task of the metamodel generation can be automated. Hibernate Static Metamodel Generator is an annotation
13-
processor based on https://jcp.org/en/jsr/detail?id=269[JSR_269] with the task of creating Jakarta Persistence
14-
static metamodel classes.
15-
16-
See <<criteria>> for discussion of Jakarta Persistence criteria queries.
17-
18-
The Hibernate Static Metamodel Generator is defined by the published `org.hibernate.orm:hibernate-jpamodelgen`
19-
artifact. As it is defined as an
20-
https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-082C33A5-CBCA-471A-845E-E77F79B7B049[annotation processor],
21-
it is usable anytime `javac` is used. See the tool-specific discussions (<<tooling-gradle-modelgen,Gradle>>, <<tooling-maven-modelgen,Maven>>
22-
and <<tooling-ant,Ant>>) for details on integrating the generator into those environments.
23-
24-
NOTE:: The fully qualified name of the processor class is `org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor`.
25-
26-
[TIP]
9+
:ann-proc: https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-082C33A5-CBCA-471A-845E-E77F79B7B049__GUID-3FA757C8-B67B-46BC-AEF9-7C3FFB126A93
10+
:ann-proc-path: https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__GUID-214E175F-0F06-4CDC-B511-5BA469955F5A
11+
:ann-proc-options: https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__GUID-6CC814A4-8A29-434A-B7E1-DF8234784E7C
12+
:intg-guide: https://docs.jboss.org/hibernate/orm/6.3/introduction/html_single/Hibernate_Introduction.html#generator
13+
14+
Jakarta Persistence defines a typesafe Criteria API which allows <<criteria,`Criteria`>>
15+
queries to be constructed in a strongly-typed manner, utilizing so-called static metamodel
16+
classes. The Hibernate Static Metamodel Generator, available via the published
17+
`org.hibernate.orm:hibernate-jpamodelgen` artifact, is an link:{ann-proc}[annotation processor]
18+
used to generate these static metamodel classes.
19+
20+
[NOTE]
2721
====
28-
The `javac` option _-proc:only_ instructs the compiler to just run the annotation processing.
29-
You can also disable annotation processing by specifying _-proc:none_.
22+
The Hibernate Static Metamodel Generator has many additional capabilities beyond static metamodel
23+
class generation. See the link:{intg-guide}[Introduction Guide] for a complete discussion of its
24+
capabilities. The rest of the discussion here is limited to the Jakarta Persistence static metamodel.
3025
31-
Run `'javac -help'` to see which other annotation processor relevant options can be specified.
26+
The generator is expected to be run using the `javac` link:{ann-proc-path}[-processorpath] option.
27+
See the tool-specific discussions (<<tooling-gradle-modelgen,Gradle>>, <<tooling-maven-modelgen,Maven>>
28+
and <<tooling-ant,Ant>>) for details on integrating the generator into those environments.
3229
====
3330

31+
[[tooling-modelgen-classes]]
32+
==== Metamodel classes
3433

3534
The structure of the metamodel classes is described in the Jakarta Persistence
3635
specification, but for completeness the definition is repeated in the following
@@ -108,3 +107,18 @@ include::{toolingTestsDir}/modelgen/ModelGenTests.java[tags=tooling-modelgen-usa
108107
----
109108
====
110109

110+
[[tooling-modelgen-options]]
111+
==== Generation Options
112+
113+
The Hibernate Static Metamodel Generator accepts a number of configuration options, which are specified as
114+
part of the `javac` execution using standard link:{ann-proc-options}[-A] options -
115+
116+
`-Adebug=[true|false]`:: Enables debug logging from the generator.
117+
`-AfullyAnnotationConfigured=[true|false]`:: Controls whether `orm.xml` mapping should be considered.
118+
`-ApersistenceXml=[path]`:: Specifies the path to the `persistence.xml` file.
119+
`-AormXml=[path]`:: Specifies the path to an `orm.xml` file.
120+
`-AlazyXmlParsing=[true|false]`:: Controls whether the processor should attempt to determine whether any `orm.xml` files have changed.
121+
`-AaddGeneratedAnnotation=[true|false]`:: Controls whether the processor should add `@jakarta.annotation.Generated` to the generated classes.
122+
`-addGenerationDate=[true|false]`:: Controls whether the processor should add `@jakarta.annotation.Generated#date`.
123+
`-addSuppressWarningsAnnotation=[true|false]`:: Controls whether the processor should add `@SuppressWarnings({"deprecation","rawtypes"})` to the generated classes.
124+

‎tooling/metamodel-generator/src/main/java/org/hibernate/jpamodelgen/JPAMetaModelEntityProcessor.java

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,13 +83,46 @@
8383
JPAMetaModelEntityProcessor.ADD_SUPPRESS_WARNINGS_ANNOTATION
8484
})
8585
public class JPAMetaModelEntityProcessor extends AbstractProcessor {
86+
/**
87+
* Debug logging from the processor
88+
*/
8689
public static final String DEBUG_OPTION = "debug";
90+
91+
/**
92+
* Path to a {@code persistence.xml} file
93+
*/
8794
public static final String PERSISTENCE_XML_OPTION = "persistenceXml";
95+
96+
/**
97+
* Path to an {@code orm.xml} file
98+
*/
8899
public static final String ORM_XML_OPTION = "ormXml";
100+
101+
/**
102+
* Controls whether the processor should consider XML files
103+
*/
89104
public static final String FULLY_ANNOTATION_CONFIGURED_OPTION = "fullyAnnotationConfigured";
105+
106+
/**
107+
* Controls whether the processor should only load XML files when there have been changes
108+
*/
90109
public static final String LAZY_XML_PARSING = "lazyXmlParsing";
91-
public static final String ADD_GENERATION_DATE = "addGenerationDate";
110+
111+
/**
112+
* Whether the {@code jakarta.annotation.Generated} annotation should be added to
113+
* the generated classes
114+
*/
92115
public static final String ADD_GENERATED_ANNOTATION = "addGeneratedAnnotation";
116+
117+
/**
118+
* Assuming that {@linkplain #ADD_GENERATED_ANNOTATION} is enabled, this option controls
119+
* whether {@code @Generated#date} should be populated.
120+
*/
121+
public static final String ADD_GENERATION_DATE = "addGenerationDate";
122+
123+
/**
124+
* Controls whether {@code @SuppressWarnings({"deprecation","rawtypes"})} should be added to the generated classes
125+
*/
93126
public static final String ADD_SUPPRESS_WARNINGS_ANNOTATION = "addSuppressWarningsAnnotation";
94127

95128
private static final boolean ALLOW_OTHER_PROCESSORS_TO_CLAIM_ANNOTATIONS = false;

0 commit comments

Comments
 (0)