Skip to content

Commit f18af4c

Browse files
koentsjekoentsje
committed
HHH-19519: Document breaking changes in new Hibernate Maven Plugin
 - Add JavaDoc style documentation to the plugin parameters to improve the Maven plugin description - Change the parameter defaults for 'enableLazyInitialization' and 'enableDirtyTracking' to bring it in line with the former behaviour - Modify the 'groupId' and 'artifactId' in the documentation - Provide complete documentation in the User Guide in line with the Ant task for bytecode enhancement
1 parent b62cc43 commit f18af4c

File tree

3 files changed

+167
-11
lines changed

3 files changed

+167
-11
lines changed

‎documentation/src/main/asciidoc/userguide/chapters/tooling/extras/maven-example.pom‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,11 @@
22
<plugins>
33
[...]
44
<plugin>
5-
<groupId>org.hibernate.orm.tooling</groupId>
6-
<artifactId>hibernate-enhance-maven-plugin</artifactId>
5+
<groupId>org.hibernate.orm</groupId>
6+
<artifactId>hibernate-maven-plugin</artifactId>
77
<version>$currentHibernateVersion</version>
88
<executions>
99
<execution>
10-
<configuration>
11-
<failOnError>true</failOnError>
12-
<enableLazyInitialization>true</enableLazyInitialization>
13-
<enableDirtyTracking>true</enableDirtyTracking>
14-
<enableAssociationManagement>true</enableAssociationManagement>
15-
</configuration>
1610
<goals>
1711
<goal>enhance</goal>
1812
</goals>

‎documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc‎

Lines changed: 137 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,14 @@ The following sections illustrate how both <<tooling-maven-enhancement,bytecode
99
Hibernate provides a https://maven.apache.org/[Maven] plugin capable of providing
1010
build-time enhancement of the domain model as they are compiled as part of a Maven
1111
build. See the section on <<BytecodeEnhancement>> for details
12-
on the configuration settings. By default, all enhancements are disabled.
12+
on the configuration settings.
1313

14+
[[maven-enhance-goal]]
15+
===== *Enhance Goal* =====
16+
17+
An example of using the `enhance` goal of the plugin is shown below. By default the plugin will
18+
perform bytecode enhancement for lazy initialization and dirty tracking. See <<maven-enhance-configuration, below>>
19+
for more details on the available parameters.
1420

1521
.Apply the Bytecode Enhancement plugin
1622
====
@@ -20,6 +26,136 @@ include::extras/maven-example.pom[]
2026
----
2127
====
2228

29+
[[maven-enhance-configuration]]
30+
===== *Enhance Configuration* =====
31+
32+
[[maven-enhance-classesDirectory-parameter]]
33+
====== `*classesDirectory*` ======
34+
This parameter points to the folder in which to look for classes to enhance.
35+
It defaults to the value of `{project.build.directory}/classes` and thus in most cases to `target/classes`.
36+
While this parameter is mandatory, its value will be ignored if the <<maven-enhance-filesets-parameter, fileSets>>
37+
parameter is specified.
38+
39+
====
40+
[source,xml]
41+
----
42+
[...]
43+
<execution>
44+
<configuration>
45+
<classesDirectory>path-to-some-folder</classesDirectory>
46+
</configuration>
47+
[...]
48+
</execution>
49+
[...]
50+
----
51+
====
52+
53+
[[maven-enhance-filesets-parameter]]
54+
====== `*fileSets*` ======
55+
This parameter comes in handy when you need to filter the classes that you want to enhance. More information
56+
on how to use filesets is to be found on the
57+
https://maven.apache.org/shared/file-management/fileset.html[fileset documentation page].
58+
This is an optional parameter but if it is specified the
59+
<<maven-enhance-classesDirectory-parameter, classesDirectory>> parameter described above is ignored.
60+
61+
====
62+
[source,xml]
63+
----
64+
[...]
65+
<execution>
66+
<configuration>
67+
<fileSets>
68+
<fileset dir="path-to-some-folder">
69+
<exclude name='Baz.class' />
70+
</fileset>
71+
</fileSets>
72+
</configuration>
73+
[...]
74+
</execution>
75+
[...]
76+
----
77+
====
78+
79+
[[maven-enhance-enableLazyInitialization-parameter]]
80+
===== `*enableLazyInitialization*` =====
81+
This parameter has a default value of `true`. It indicates that the enhance goal should perform the changes
82+
to enable lazy loading. To disable, set the value of this attribute to `false`.
83+
The parameter has been deprecated for removal.
84+
85+
====
86+
[source,xml]
87+
----
88+
[...]
89+
<execution>
90+
<configuration>
91+
<enableLazyInitialization>false</enableLazyInitialization>
92+
</configuration>
93+
[...]
94+
</execution>
95+
[...]
96+
----
97+
====
98+
99+
[[maven-enhance-enableDirtyTracking-parameter]]
100+
===== `*enableDirtyTracking*` =====
101+
This parameter has a default value of `true`. It indicates that the enhance task should perform the changes
102+
to enable dirty tracking. To disable, set the value of this attribute to `false`.
103+
The parameter has been deprecated for removal.
104+
105+
====
106+
[source,xml]
107+
----
108+
[...]
109+
<execution>
110+
<configuration>
111+
<enableDirtyTracking>false</enableDirtyTracking>
112+
</configuration>
113+
[...]
114+
</execution>
115+
[...]
116+
----
117+
====
118+
119+
[[maven-enhance-enableAssociationManagement-parameter]]
120+
===== `*enableAssociationManagement*` =====
121+
This parameter has a default value of `false`. It indicates that the enhance task should not perform the changes
122+
to enable association management. To enable, set the value of this attribute to `true`.
123+
124+
====
125+
[source,xml]
126+
----
127+
[...]
128+
<execution>
129+
<configuration>
130+
<enableAssociationManagement>true</enableAssociationManagement>
131+
</configuration>
132+
[...]
133+
</execution>
134+
[...]
135+
----
136+
====
137+
138+
[[maven-enhance-enableExtendedEnhancement-paremeter]]
139+
===== `*enableExtendedEnhancement*` =====
140+
This parameter has a default value of `false`. It indicates that the enhance task should not perform the changes
141+
to enable the extended enhancement (i.e. even on non-entities).
142+
To enable this, set the value of this attribute to `true`.
143+
144+
====
145+
[source,xml]
146+
----
147+
[...]
148+
<execution>
149+
<configuration>
150+
<enableExtendedEnhancement>true</enableExtendedEnhancement>
151+
</configuration>
152+
[...]
153+
</execution>
154+
[...]
155+
----
156+
====
157+
158+
23159
[[tooling-maven-modelgen]]
24160
==== Static Metamodel Generation
25161

‎tooling/hibernate-maven-plugin/src/main/java/org/hibernate/orm/tooling/maven/HibernateEnhancerMojo.java‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,29 +33,55 @@ public class HibernateEnhancerMojo extends AbstractMojo {
3333
final private List<File> sourceSet = new ArrayList<File>();
3434
private Enhancer enhancer;
3535

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

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

52+
/**
53+
* A boolean that indicates whether or not to add association management to automatically
54+
* synchronize a bidirectional association when only one side is changed
55+
*/
4456
@Parameter(
4557
defaultValue = "false",
4658
required = true)
4759
private boolean enableAssociationManagement;
4860

61+
/**
62+
* A boolean that indicates whether or not to add dirty tracking
63+
*/
64+
@Deprecated(
65+
forRemoval = true)
4966
@Parameter(
50-
defaultValue = "false",
67+
defaultValue = "true",
5168
required = true)
5269
private boolean enableDirtyTracking;
5370

71+
/**
72+
* A boolean that indicates whether or not to add lazy initialization
73+
*/
74+
@Deprecated(
75+
forRemoval = true)
5476
@Parameter(
55-
defaultValue = "false",
77+
defaultValue = "true",
5678
required = true)
5779
private boolean enableLazyInitialization;
5880

81+
/**
82+
* A boolean that indicates whether or not to add extended enhancement.
83+
* This setting will provide bytecode enhancement, even for non-entity classes
84+
*/
5985
@Parameter(
6086
defaultValue = "false",
6187
required = true)

0 commit comments

Comments
 (0)