diff --git a/documentation/src/main/asciidoc/userguide/chapters/tooling/gradle.adoc b/documentation/src/main/asciidoc/userguide/chapters/tooling/gradle.adoc index cbf68686cb..39b882883a 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/tooling/gradle.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/tooling/gradle.adoc @@ -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) - diff --git a/documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc b/documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc index b062947f61..3dc4d31f5e 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc @@ -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 ==== diff --git a/documentation/src/main/asciidoc/userguide/chapters/tooling/modelgen.adoc b/documentation/src/main/asciidoc/userguide/chapters/tooling/modelgen.adoc index a6a51de157..1128003ff3 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/tooling/modelgen.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/tooling/modelgen.adoc @@ -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 <> +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 <> 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 (<>, <> +The generator is expected to be run using the `javac` link:{ann-proc-path}[-processorpath] option. +See the tool-specific discussions (<>, <> and <>) 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. + diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/jpamodelgen/JPAMetaModelEntityProcessor.java b/tooling/metamodel-generator/src/main/java/org/hibernate/jpamodelgen/JPAMetaModelEntityProcessor.java index 9988ea2860..6a887fd2d6 100644 --- a/tooling/metamodel-generator/src/main/java/org/hibernate/jpamodelgen/JPAMetaModelEntityProcessor.java +++ b/tooling/metamodel-generator/src/main/java/org/hibernate/jpamodelgen/JPAMetaModelEntityProcessor.java @@ -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;