Skip to content

HHH-19812: Improvements on the Maven Enhance Plugin (Backport to 7.0) #11032

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

Open
wants to merge 3 commits into
base: 7.0
Choose a base branch
from
Open

HHH-19812: Improvements on the Maven Enhance Plugin (Backport to 7.0) #11032

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
e186a98
HHH-19817: Add the JavaDoc Style documentation appropriate for Maven …
koentsje Sep 26, 2025
321b3fd
HHH-19815: Review and Complete the documentation of the Enhance Plugi…
koentsje Oct 10, 2025
b0d8c81
HHH-19814: Document the Enhance Plugin changes in the Migration Guide
koentsje Oct 10, 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
6 changes: 2 additions & 4 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,16 +2,14 @@
<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>
Expand Down
140 changes: 139 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.

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

An example of using the `enhance` goal of the plugin is shown below. In this case 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,138 @@ 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`.
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 optional 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].
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 `false`. It indicates whether the enhance goal should perform the changes
to enable <<BytecodeEnhancement-lazy-loading,lazy loading>>.
The parameter has been deprecated for removal. After this removal, <<BytecodeEnhancement-lazy-loading,lazy loading>>
will always be enabled.

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

[[maven-enhance-enableDirtyTracking-parameter]]
===== `*enableDirtyTracking*` =====
This parameter has a default value of `false`. It indicates whether the enhance task should perform the changes
to enable <<BytecodeEnhancement-dirty-tracking,dirty tracking>>.
The parameter has been deprecated for removal. After this removal, <<BytecodeEnhancement-dirty-tracking,dirty tracking>>
will always be enabled.

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

[[maven-enhance-enableAssociationManagement-parameter]]
===== `*enableAssociationManagement*` =====
This parameter has a default value of `false`. It indicates whether the enhance task should perform the changes
to enable <<BytecodeEnhancement-dirty-tracking-bidirectional,association management>>.

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

[[maven-enhance-enableExtendedEnhancement-paremeter]]
===== `*enableExtendedEnhancement*` =====
This parameter has a default value of `false`. It indicates whether the enhance task should perform the changes
to enable the extended enhancement: enhancement of non-entities to trigger lazy-loading and inline dirty tracking
even when accessing entity fields directly..

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


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

Expand Down
31 changes: 31 additions & 0 deletions migration-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -789,3 +789,34 @@ We recommend using https://github.com/agroal/agroal[Agroal] or https://github.co
Alternatively, you may implement the `ConnectionProvider` interface to integrate the connection pool of your choice.
In fact, some connection pools already include their own implementations of `ConnectionProvider`.

[[maven-plugin-changes]]
== Changes to the Maven Plugin

The Maven bytecode enhancement plugin has been completely rewritten since version 7.0. The change that has the
biggest consequence is that the artefactId and groupId of the Maven artefact has changed. As of now, you will
need to include the plugin in the build section in your Maven pom file as illustrated below.

```
<plugin>
<groupId>org.hibernate.orm</groupId>
<artifactId>hibernate-maven-plugin</artifactId>
<version>$currentHibernateVersion</version>
<executions>
<execution>
<configuration>
<enableLazyInitialization>true</enableLazyInitialization>
<enableDirtyTracking>true</enableDirtyTracking>
</configuration>
<goals>
<goal>enhance</goal>
</goals>
</execution>
</executions>
</plugin>
```

Also, because of a regression and in contrast with the corresponding Ant task and Gradle plugin, the default values
of the `enableLazyInitialization` and `enableDirtyTracking` are set to `false` while it used to be `true`. This will
be reverted in future versions.

The documentation in the userguide has been rewritten accordingly and completed with more examples.
22 changes: 22 additions & 0 deletions ...ate-maven-plugin/src/main/java/org/hibernate/orm/tooling/maven/HibernateEnhancerMojo.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,29 +33,51 @@ public class HibernateEnhancerMojo extends AbstractMojo {
final private List<File> sourceSet = new ArrayList<File>();
private Enhancer enhancer;

/**
* A list of FileSets in which to look for classes to enhance.
* This parameter is optional but if it is specified, the 'classesDirectory' parameter is ignored.
*/
@Parameter
private FileSet[] fileSets;

/**
* The folder in which to look for classes to enhance.
* This parameter is required but if the 'fileSets' parameter is specified, it will be ignored.
*/
@Parameter(
defaultValue = "${project.build.directory}/classes",
required = true)
private File classesDirectory;

/**
* A boolean that indicates whether or not to add association management to automatically
* synchronize a bidirectional association when only one side is changed
*/
@Parameter(
defaultValue = "false",
required = true)
private boolean enableAssociationManagement;

/**
* A boolean that indicates whether or not to add dirty tracking
*/
@Parameter(
defaultValue = "false",
required = true)
private boolean enableDirtyTracking;

/**
* A boolean that indicates whether or not to add lazy initialization
*/
@Parameter(
defaultValue = "false",
required = true)
private boolean enableLazyInitialization;

/**
* A boolean that indicates whether or not to add extended enhancement.
* This setting will provide bytecode enhancement, even for non-entity classes
*/
@Parameter(
defaultValue = "false",
required = true)
Expand Down
Loading