HHH-17157 - Some improvements to the metamodel generator documentation
This commit is contained in:
Steve Ebersole
Christian Beikov
parent
f78c802acb
commit
6b82346187
|
|
@ -60,7 +60,7 @@ It also exposes the following method forms:
|
|||
==== Static Metamodel Generation
|
||||
|
||||
Static metamodel generation can be incorporated into Gradle builds via the
|
||||
annotation processor provided by the `hibernate-jpamodelgen` artifact. Applying
|
||||
annotation processor provided by the `org.hibernate.orm:hibernate-jpamodelgen` artifact. Applying
|
||||
an annotation processor in Gradle is super easy -
|
||||
|
||||
|
||||
|
|
@ -70,40 +70,3 @@ dependencies {
|
|||
annotationProcessor "org.hibernate.orm:hibernate-jpamodelgen:${hibernateVersion}"
|
||||
}
|
||||
----
|
||||
|
||||
When the build does not need bytecode enhancement support, this is a perfectly valid solution.
|
||||
|
||||
The plugin supports simpler configuration of the generator using the registered
|
||||
`jpaMetamodel` extension:
|
||||
|
||||
|
||||
[source,gradle]
|
||||
----
|
||||
hibernate {
|
||||
jpaMetamodel {
|
||||
applyGeneratedAnnotation false
|
||||
suppress 'raw'
|
||||
generationOutputDirectory "${buildDir}/generated/sources/modelgen"
|
||||
compileOutputDirectory "${buildDir}/classes/java/modelgen"
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
The extension is of type `JpaMetamodelGenerationSpec`, which exposes the following configuration properties:
|
||||
|
||||
applyGeneratedAnnotation:: Should the `javax.annotation.processing.Generated` annotation be added to the
|
||||
generated classes. Defaults to `true`.
|
||||
suppressions:: Suppressions to add to the generated classes. Defaults to `['raw', 'deprecation']`
|
||||
generationOutputDirectory:: Directory where the generated metamodel classes should be created. Defaults
|
||||
to `${buildDir}/generated/sources/jpaMetamodel`
|
||||
[[tooling-gradle-modelgen-compile-output]]
|
||||
compileOutputDirectory:: Directory where the classes compiled from the generated metamodel classes should be
|
||||
created. Defaults to `${buildDir}/classes/java/jpaMetamodel`.
|
||||
|
||||
It also exposes the following method forms:
|
||||
|
||||
* applyGeneratedAnnotation(boolean)
|
||||
* suppress(String)
|
||||
* generationOutputDirectory(Object)
|
||||
* compileOutputDirectory(Object)
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,8 @@ 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).
|
||||
Static metamodel generation should be integrated into a maven project through the annotation processor
|
||||
paths of the maven compiler plugin.
|
||||
|
||||
.Integrate the metamodel generator
|
||||
====
|
||||
|
|
|
|||
|
|
@ -6,31 +6,30 @@
|
|||
:example-dir-metamodelgen-generated: {testing-project-dir}/target/generated/sources/annotationProcessor/java/main/org/hibernate/testing/orm/domain/userguide
|
||||
:core-project-dir: {root-project-dir}/hibernate-core
|
||||
:toolingTestsDir: {core-project-dir}/src/test/java/org/hibernate/orm/test/tooling
|
||||
: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
|
||||
: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
|
||||
: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
|
||||
:intg-guide: https://docs.jboss.org/hibernate/orm/6.3/introduction/html_single/Hibernate_Introduction.html#generator
|
||||
|
||||
Jakarta Persistence defines a typesafe Criteria API which allows `Criteria` queries to be constructed in a
|
||||
strongly-typed manner, utilizing so-called static metamodel classes. For developers, it is important that
|
||||
the task of the metamodel generation can be automated. Hibernate Static Metamodel Generator is an annotation
|
||||
processor based on https://jcp.org/en/jsr/detail?id=269[JSR_269] with the task of creating Jakarta Persistence
|
||||
static metamodel classes.
|
||||
Jakarta Persistence defines a typesafe Criteria API which allows <<criteria,`Criteria`>>
|
||||
queries to be constructed in a strongly-typed manner, utilizing so-called static metamodel
|
||||
classes. The Hibernate Static Metamodel Generator, available via the published
|
||||
`org.hibernate.orm:hibernate-jpamodelgen` artifact, is an link:{ann-proc}[annotation processor]
|
||||
used to generate these static metamodel classes.
|
||||
|
||||
See <<criteria>> for discussion of Jakarta Persistence criteria queries.
|
||||
[NOTE]
|
||||
====
|
||||
The Hibernate Static Metamodel Generator has many additional capabilities beyond static metamodel
|
||||
class generation. See the link:{intg-guide}[Introduction Guide] for a complete discussion of its
|
||||
capabilities. The rest of the discussion here is limited to the Jakarta Persistence static metamodel.
|
||||
|
||||
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-modelgen,Gradle>>, <<tooling-maven-modelgen,Maven>>
|
||||
The generator is expected to be run using the `javac` link:{ann-proc-path}[-processorpath] option.
|
||||
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`.
|
||||
|
||||
[TIP]
|
||||
====
|
||||
The `javac` option _-proc:only_ instructs the compiler to just run the annotation processing.
|
||||
You can also disable annotation processing by specifying _-proc:none_.
|
||||
|
||||
Run `'javac -help'` to see which other annotation processor relevant options can be specified.
|
||||
====
|
||||
|
||||
[[tooling-modelgen-classes]]
|
||||
==== Metamodel classes
|
||||
|
||||
The structure of the metamodel classes is described in the Jakarta Persistence
|
||||
specification, but for completeness the definition is repeated in the following
|
||||
|
|
@ -108,3 +107,18 @@ include::{toolingTestsDir}/modelgen/ModelGenTests.java[tags=tooling-modelgen-usa
|
|||
----
|
||||
====
|
||||
|
||||
[[tooling-modelgen-options]]
|
||||
==== Generation Options
|
||||
|
||||
The Hibernate Static Metamodel Generator accepts a number of configuration options, which are specified as
|
||||
part of the `javac` execution using standard link:{ann-proc-options}[-A] options -
|
||||
|
||||
`-Adebug=[true|false]`:: Enables debug logging from the generator.
|
||||
`-AfullyAnnotationConfigured=[true|false]`:: Controls whether `orm.xml` mapping should be considered.
|
||||
`-ApersistenceXml=[path]`:: Specifies the path to the `persistence.xml` file.
|
||||
`-AormXml=[path]`:: Specifies the path to an `orm.xml` file.
|
||||
`-AlazyXmlParsing=[true|false]`:: Controls whether the processor should attempt to determine whether any `orm.xml` files have changed.
|
||||
`-AaddGeneratedAnnotation=[true|false]`:: Controls whether the processor should add `@jakarta.annotation.Generated` to the generated classes.
|
||||
`-addGenerationDate=[true|false]`:: Controls whether the processor should add `@jakarta.annotation.Generated#date`.
|
||||
`-addSuppressWarningsAnnotation=[true|false]`:: Controls whether the processor should add `@SuppressWarnings({"deprecation","rawtypes"})` to the generated classes.
|
||||
|
||||
|
|
|
|||
|
|
@ -59,13 +59,46 @@ import org.checkerframework.checker.nullness.qual.Nullable;
|
|||
JPAMetaModelEntityProcessor.ADD_SUPPRESS_WARNINGS_ANNOTATION
|
||||
})
|
||||
public class JPAMetaModelEntityProcessor extends AbstractProcessor {
|
||||
/**
|
||||
* Debug logging from the processor
|
||||
*/
|
||||
public static final String DEBUG_OPTION = "debug";
|
||||
|
||||
/**
|
||||
* Path to a {@code persistence.xml} file
|
||||
*/
|
||||
public static final String PERSISTENCE_XML_OPTION = "persistenceXml";
|
||||
|
||||
/**
|
||||
* Path to an {@code orm.xml} file
|
||||
*/
|
||||
public static final String ORM_XML_OPTION = "ormXml";
|
||||
|
||||
/**
|
||||
* Controls whether the processor should consider XML files
|
||||
*/
|
||||
public static final String FULLY_ANNOTATION_CONFIGURED_OPTION = "fullyAnnotationConfigured";
|
||||
|
||||
/**
|
||||
* Controls whether the processor should only load XML files when there have been changes
|
||||
*/
|
||||
public static final String LAZY_XML_PARSING = "lazyXmlParsing";
|
||||
public static final String ADD_GENERATION_DATE = "addGenerationDate";
|
||||
|
||||
/**
|
||||
* Whether the {@code jakarta.annotation.Generated} annotation should be added to
|
||||
* the generated classes
|
||||
*/
|
||||
public static final String ADD_GENERATED_ANNOTATION = "addGeneratedAnnotation";
|
||||
|
||||
/**
|
||||
* Assuming that {@linkplain #ADD_GENERATED_ANNOTATION} is enabled, this option controls
|
||||
* whether {@code @Generated#date} should be populated.
|
||||
*/
|
||||
public static final String ADD_GENERATION_DATE = "addGenerationDate";
|
||||
|
||||
/**
|
||||
* Controls whether {@code @SuppressWarnings({"deprecation","rawtypes"})} should be added to the generated classes
|
||||
*/
|
||||
public static final String ADD_SUPPRESS_WARNINGS_ANNOTATION = "addSuppressWarningsAnnotation";
|
||||
|
||||
private static final Boolean ALLOW_OTHER_PROCESSORS_TO_CLAIM_ANNOTATIONS = Boolean.FALSE;
|
||||
|
|
|
|||
Loading…
Reference in New Issue