Skip to content

Commit 99bb944

Browse files
koentsjesebersole
koentsje
authored and
sebersole
committed
HHH-19638: Document the Ant enhancement task in User Guide tooling section
 - Create a test for 'org.hibernate.tool.enhance.EnhancementTask' that covers all the configuration settings (except for 'failOnError') - Describe how to add the task definition to your Ant build, with minimal example - Add a description and short example for each of the configuration attributes and/or elements
1 parent 80626c9 commit 99bb944

File tree

7 files changed

+598
-2
lines changed

7 files changed

+598
-2
lines changed

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

Lines changed: 164 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,170 @@
11
[[tooling-ant]]
2-
=== Ant Plugin
2+
=== Ant
33

4-
Hibernate provides https://ant.apache.org/[Ant] support ...
4+
Hibernate provides https://ant.apache.org/[Ant] support.
5+
Everything Ant related is available from the
6+
https://central.sonatype.com/artifact/org.hibernate.orm/hibernate-ant[hibernate-ant]
7+
library.
58

9+
[[tooling-ant-enhancement]]
10+
==== Bytecode Enhancement ====
11+
12+
Hibernate provides an https://ant.apache.org/[Ant] task implementation
13+
that you can use to do build-time bytecode enhancement of your domain
14+
model. You can visit <<BytecodeEnhancement>> for discussion of the capabilities
15+
of an enhanced model.
16+
17+
[[ant-enhance-task]]
18+
===== *Enhance Task* =====
19+
20+
The task implementation is in class `org.hibernate.tool.enhance.EnhancementTask`,
21+
so you will need to include a `taskdef` in your `build.xml` that uses this class
22+
to define your task. Below is a minimal Ant `build.xml` file that shows the use
23+
of the enhancement task.
24+
25+
[[enhance-task-example]]
26+
.Enhance Task Example
27+
====
28+
[source, XML]]
29+
----
30+
include::extras/ant-enhance-example.xml[]
31+
----
32+
====
33+
34+
As you can see above, https://ant.apache.org/ivy[Apache Ivy] was used to
35+
handle the dependency on the
36+
https://central.sonatype.com/artifact/org.hibernate.orm/hibernate-ant[hibernate-ant]
37+
library. Now let's dive a little deeper in the configuration possibilities for the
38+
enhancement task.
39+
40+
[[ant-enhance-configuration]]
41+
===== *Enhance Configuration* =====
42+
43+
[[ant-enhance-base-attribute]]
44+
====== `*base*` ======
45+
This attribute is mandatory. It points to the base folder where the enhancement task will look
46+
to discover classes that have to be enhanced. It is either combined with the `dir`
47+
attribute that specifies a subfolder of `base` where the classes are located (or of course
48+
the entire `base` folder) or else with a `<fileset>` child element that has a similar role.
49+
If neither `dir` nor `<fileset>` are used, no classes will be enhanced.
50+
51+
====
52+
[source, XML]]
53+
----
54+
<enhance base='${basedir}/dest' .../>
55+
----
56+
====
57+
58+
[[ant-enhance-dir-attribute]]
59+
====== `*dir*` ======
60+
This attribute is combined with the (mandatory) `base` attribute described above. It points to
61+
a subfolder of `base` where the enhancement task will look to discover the classes to be enhanced.
62+
If the `dir` attribute is specified, the use of a `<fileset>` child element will be ignored.
63+
If neither `dir` nor `<fileset>` are used, no classes will be enhanced.
64+
65+
====
66+
[source, XML]]
67+
----
68+
<enhance
69+
base='...'
70+
dir='some subfolder of base'/>
71+
----
72+
====
73+
74+
[[ant-enhance-fileset-element]]
75+
===== `*<fileset>*` =====
76+
This child element is combined with the (mandatory) `base` attribute described above. It can be used
77+
to detail which classes should be selected for enhancement. The use of `<fileset>` is well documented on the
78+
https://ant.apache.org/manual/Types/fileset.html[Ant FileSet documentation page]. If the `dir` attribute
79+
described above is specified, the `<fileset>` element will be ignored.
80+
If neither `dir` nor `<fileset>` are used, no classes will be enhanced.
81+
82+
====
83+
[source, XML]]
84+
----
85+
<enhance base='${basedir}/dest'>
86+
<fileset dir="some subfolder of base">
87+
<exclude name='Baz.class' />
88+
</fileset>
89+
</enhance>
90+
----
91+
====
92+
93+
[[ant-enhance-enableLazyInitialization-attribute]]
94+
===== `*enableLazyInitialization*` =====
95+
This attribute has a default value of `true`. It indicates that the enhance task should perform the changes
96+
to enable lazy loading. To disable, set the value of this attribute to `false`.
97+
98+
====
99+
[source, XML]]
100+
----
101+
<enhance
102+
...
103+
enableLazyInitialization='false'/>
104+
----
105+
====
106+
107+
108+
[[ant-enhance-enableDirtyTracking-attribute]]
109+
===== `*enableDirtyTracking*` =====
110+
This attribute has a default value of `true`. It indicates that the enhance task should perform the changes
111+
to enable dirty tracking. To disable, set the value of this attribute to `false`.
112+
113+
====
114+
[source, XML]]
115+
----
116+
<enhance
117+
...
118+
enableDirtyTracking='false'/>
119+
----
120+
====
121+
122+
[[ant-enhance-enableAssociationManagement-attribute]]
123+
===== `*enableAssociationManagement*` =====
124+
This attribute has a default value of `false`. It indicates that the enhance task should not perform the changes
125+
to enable association management. To enable, set the value of this attribute to `true`.
126+
127+
====
128+
[source, XML]]
129+
----
130+
<enhance
131+
...
132+
enableAssociationManagement='true'/>
133+
----
134+
====
135+
136+
[[ant-enhance-enableExtendedEnhancement-attribute]]
137+
===== `*enableExtendedEnhancement*` =====
138+
This attribute has a default value of `false`. It indicates that the enhance task should not perform the changes
139+
to enable the extended enhancement (i.e. even on non-entities).
140+
To enable this, set the value of this attribute to `true`.
141+
142+
====
143+
[source, XML]]
144+
----
145+
<enhance
146+
...
147+
enableExtendedEnhancement='true'/>
148+
----
149+
====
150+
151+
[[ant-enhance-failOnError-attribute]]
152+
===== `*failOnError*` =====
153+
This attribute has a default value of `true`. It indicates that the enhance task will throw an Ant BuildException
154+
when it encounters a problem. If you prefer the build to continue, you can set the value to `false`.
155+
156+
====
157+
[source, XML]]
158+
----
159+
<enhance
160+
...
161+
failOnError='false'/>
162+
----
163+
====
164+
165+
===== *Final Remark* =====
166+
If the values of the four attributes `enableLazyInitialization`, `enableDirtyTracking`, `enableAssociationManagement`,
167+
`enableExtendedEnhancement` are all `false`, the enhancement task is not executed.
6168

7169
[[tooling-ant-modelgen]]
8170
==== Static Metamodel Generation in Ant

‎documentation/src/main/asciidoc/userguide/chapters/tooling/extras/ant-enhance-example.xml

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<project name="example" xmlns:ivy="antlib:org.apache.ivy.ant">
2+
[...]
3+
<ivy:cachepath
4+
organisation="org.hibernate.orm"
5+
module="hibernate-ant"
6+
revision="${hibernate.version}"
7+
pathid="hibernate-ant.path"
8+
inline="true"/>
9+
[...]
10+
<taskdef
11+
name="enhance"
12+
classname='org.hibernate.tool.enhance.EnhancementTask'
13+
classpathref="hibernate-ant.path" />
14+
[...]
15+
<target name="enhance" depends="compile">
16+
<enhance base='${basedir}/dest' dir='${basedir}/dest'/>
17+
</target>
18+
[...]
19+
</project>
20+

‎tooling/hibernate-ant/hibernate-ant.gradle

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,5 @@ description = 'Annotation Processor to generate JPA 2 static metamodel classes'
1010
dependencies {
1111
compileOnly libs.ant
1212
implementation project( ':hibernate-core' )
13+
testImplementation libs.ant
1314
}

0 commit comments

Comments
 (0)