Skip to content

HHH-19519: Document breaking changes in new Hibernate Maven Plugin #10835

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

HHH-19519: Document breaking changes in new Hibernate Maven Plugin #10835

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f18af4c
HHH-19519: Document breaking changes in new Hibernate Maven Plugin
koentsje Aug 27, 2025
66d0790
HHH-19519: Document breaking changes in new Hibernate Maven Plugin
koentsje Aug 28, 2025
9ff24f8
HHH-19519: Document breaking changes in new Hibernate Maven Plugin
koentsje Sep 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 2 additions & 8 deletions documentation/src/main/asciidoc/userguide/chapters/tooling/extras/maven-example.pom
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,11 @@
<plugins>
[...]
<plugin>
<groupId>org.hibernate.orm.tooling</groupId>
<artifactId>hibernate-enhance-maven-plugin</artifactId>
<groupId>org.hibernate.orm</groupId>
<artifactId>hibernate-maven-plugin</artifactId>
<version>$currentHibernateVersion</version>
<executions>
<execution>
<configuration>
<failOnError>true</failOnError>
<enableLazyInitialization>true</enableLazyInitialization>
<enableDirtyTracking>true</enableDirtyTracking>
<enableAssociationManagement>true</enableAssociationManagement>
</configuration>
<goals>
<goal>enhance</goal>
</goals>
Expand Down
138 changes: 137 additions & 1 deletion documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,14 @@ The following sections illustrate how both <<tooling-maven-enhancement,bytecode
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 <<BytecodeEnhancement>> for details
on the configuration settings. By default, all enhancements are disabled.
on the configuration settings.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed, if anything changed, we will need the changes documented in migration-guide.adoc at the root of the repository. That needs to happen on the branch where the changes happened, though -- which I think would be 7.0.

From the top of my head, the changes are:

  1. Renaming of the plugin
  2. Default settings
  3. Maybe some Maven plugin configuration e.g. filesets?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this is only the renaming of the plugin. I included this in the other PR I just opened but I'll need to account for your other comments in that one as well.


[[maven-enhance-goal]]
===== *Enhance Goal* =====

An example of using the `enhance` goal of the plugin is shown below. By default the plugin will
perform bytecode enhancement for lazy initialization and dirty tracking. See <<maven-enhance-configuration, below>>
for more details on the available parameters.

.Apply the Bytecode Enhancement plugin
====
Expand All @@ -20,6 +26,136 @@ include::extras/maven-example.pom[]
----
====

[[maven-enhance-configuration]]
===== *Enhance Configuration* =====

[[maven-enhance-classesDirectory-parameter]]
====== `*classesDirectory*` ======
This parameter points to the folder in which to look for classes to enhance.
It defaults to the value of `{project.build.directory}/classes` and thus in most cases to `target/classes`.
While this parameter is mandatory, its value will be ignored if the <<maven-enhance-filesets-parameter, fileSets>>
parameter is specified.
Comment on lines +36 to +37
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not mandatory if it has a default.

Suggested change
While this parameter is mandatory, its value will be ignored if the <<maven-enhance-filesets-parameter, fileSets>>
parameter is specified.
If both `classesDirectory` and <<maven-enhance-filesets-parameter,fileSets>> are set, `fileSets` takes precedence.


====
[source,xml]
----
[...]
<execution>
<configuration>
<classesDirectory>path-to-some-folder</classesDirectory>
</configuration>
[...]
</execution>
[...]
----
====

[[maven-enhance-filesets-parameter]]
====== `*fileSets*` ======
This parameter comes in handy when you need to filter the classes that you want to enhance. More information
on how to use filesets is to be found on the
https://maven.apache.org/shared/file-management/fileset.html[fileset documentation page].
This is an optional parameter but if it is specified the
<<maven-enhance-classesDirectory-parameter, classesDirectory>> parameter described above is ignored.
Comment on lines +58 to +59
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This is an optional parameter but if it is specified the
<<maven-enhance-classesDirectory-parameter, classesDirectory>> parameter described above is ignored.
If both <<maven-enhance-classesDirectory-parameter, classesDirectory>> and `fileSets` are set, `fileSets` takes precedence.


====
[source,xml]
----
[...]
<execution>
<configuration>
<fileSets>
<fileset dir="path-to-some-folder">
<exclude name='Baz.class' />
</fileset>
</fileSets>
</configuration>
[...]
</execution>
[...]
----
====

[[maven-enhance-enableLazyInitialization-parameter]]
===== `*enableLazyInitialization*` =====
This parameter has a default value of `true`. It indicates that the enhance goal should perform the changes
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This parameter has a default value of `true`. It indicates that the enhance goal should perform the changes
This parameter has a default value of `true`. It indicates whether the enhance goal should perform the changes

to enable lazy loading. To disable, set the value of this attribute to `false`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
to enable lazy loading. To disable, set the value of this attribute to `false`.
to enable <<BytecodeEnhancement-lazy-loading,lazy loading>>.

The parameter has been deprecated for removal.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe explain what will happen on removal (always enabled? always disabled?).


====
[source,xml]
----
[...]
<execution>
<configuration>
<enableLazyInitialization>false</enableLazyInitialization>
</configuration>
[...]
</execution>
[...]
----
====

[[maven-enhance-enableDirtyTracking-parameter]]
===== `*enableDirtyTracking*` =====
This parameter has a default value of `true`. It indicates that the enhance task should perform the changes
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This parameter has a default value of `true`. It indicates that the enhance task should perform the changes
This parameter has a default value of `true`. It indicates whether the enhance task should perform the changes

to enable dirty tracking. To disable, set the value of this attribute to `false`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
to enable dirty tracking. To disable, set the value of this attribute to `false`.
to enable <<BytecodeEnhancement-dirty-tracking,dirty tracking>>.

The parameter has been deprecated for removal.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe explain what will happen on removal (always enabled? always disabled?).


====
[source,xml]
----
[...]
<execution>
<configuration>
<enableDirtyTracking>false</enableDirtyTracking>
</configuration>
[...]
</execution>
[...]
----
====

[[maven-enhance-enableAssociationManagement-parameter]]
===== `*enableAssociationManagement*` =====
This parameter has a default value of `false`. It indicates that the enhance task should not perform the changes
to enable association management. To enable, set the value of this attribute to `true`.

====
[source,xml]
----
[...]
<execution>
<configuration>
<enableAssociationManagement>true</enableAssociationManagement>
</configuration>
[...]
</execution>
[...]
----
====

[[maven-enhance-enableExtendedEnhancement-paremeter]]
===== `*enableExtendedEnhancement*` =====
This parameter has a default value of `false`. It indicates that the enhance task should not perform the changes
to enable the extended enhancement (i.e. even on non-entities).
To enable this, set the value of this attribute to `true`.

====
[source,xml]
----
[...]
<execution>
<configuration>
<enableExtendedEnhancement>true</enableExtendedEnhancement>
</configuration>
[...]
</execution>
[...]
----
====


[[tooling-maven-modelgen]]
==== Static Metamodel Generation

Expand Down
51 changes: 49 additions & 2 deletions tooling/hibernate-maven-plugin/hibernate-maven-plugin.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,34 @@ plugins {

description = 'Maven plugin to integrate aspects of Hibernate into your build.'

sourceSets {
intTest {
compileClasspath += sourceSets.main.output
runtimeClasspath += sourceSets.main.output
}
}

configurations {
intTestImplementation.extendsFrom implementation
intTestRuntimeOnly.extendsFrom runtimeOnly
}

dependencies {
implementation project( ":hibernate-core" )

implementation "org.apache.maven:maven-plugin-api:3.6.3"
implementation "org.apache.maven:maven-plugin-api:3.9.11"
implementation "org.apache.maven:maven-project:2.2.1"
implementation "org.apache.maven.shared:file-management:3.1.0"

compileOnly "org.apache.maven.plugin-tools:maven-plugin-annotations:3.6.0"
compileOnly "org.apache.maven.plugin-tools:maven-plugin-tools-annotations:3.15.1"

intTestImplementation 'org.junit.jupiter:junit-jupiter:5.13.4'
intTestImplementation 'org.apache.maven:maven-embedder:3.9.11'
intTestRuntimeOnly 'org.junit.platform:junit-platform-launcher'
intTestRuntimeOnly 'ch.qos.logback:logback-classic:1.5.18'
intTestRuntimeOnly 'org.apache.maven:maven-compat:3.9.11'
intTestRuntimeOnly 'org.apache.maven.resolver:maven-resolver-transport-http:1.9.24'
intTestRuntimeOnly 'org.apache.maven.resolver:maven-resolver-connector-basic:1.9.24'
}

def releasePrepareTask = tasks.register("releasePrepare") {
Expand All @@ -37,6 +57,25 @@ tasks.register("preVerifyRelease") {
dependsOn releasePrepareTask
}

tasks.register('integrationTest', Test) {
description = 'Runs integration tests.'
group = 'verification'

testClassesDirs = sourceSets.intTest.output.classesDirs
classpath = sourceSets.intTest.runtimeClasspath
shouldRunAfter test

useJUnitPlatform()

testLogging {
events "passed"
}
}

tasks.forbiddenApisIntTest {
enabled = false
}

var publishingExtension = project.getExtensions().getByType(PublishingExtension) as PublishingExtension
publishingExtension.publications.named("publishedArtifacts") {
from components.java
Expand Down Expand Up @@ -64,3 +103,11 @@ publishingExtension.publications.named("publishedArtifacts") {
}
}

integrationTest {
environment "hibernateVersion", project.version
}

integrationTest.dependsOn rootProject.childProjects.'hibernate-core'.tasks.publishToMavenLocal
integrationTest.dependsOn publishToMavenLocal
check.dependsOn integrationTest

Loading