Skip to content

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

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 1 commit into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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.

[[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.

====
[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.

====
[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
to enable lazy loading. To disable, set the value of this attribute to `false`.
The parameter has been deprecated for removal.

====
[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
to enable dirty tracking. To disable, set the value of this attribute to `false`.
The parameter has been deprecated for removal.

====
[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
23 changes: 23 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,26 @@ 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>
<goals>
<goal>enhance</goal>
</goals>
</execution>
</executions>
</plugin>
```

The documentation in the userguide has been rewritten accordingly and completed with more examples.
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