From 66bd73eaf0a725a884bda2b9b5324abc52e50c44 Mon Sep 17 00:00:00 2001
From: Koen Aers <koen.aers@gmail.com>
Date: Tue, 23 Sep 2025 14:42:05 +0200
Subject: [PATCH] HBX-3127: Actualize the Ant Reference Guide for Reverse
 Engineering   - Change the delimiters in 'common/included.xml' so that the
 examples are usable straight from a command-line   - Adapt the instructions
 in the README.md files to add the needed arguments   - Reorder and provide
 comments for some plugin executions in 'ant/pom.xml' file and add the
 '${hibernate.version}' property

Signed-off-by: Koen Aers <koen.aers@gmail.com>
---
 ant/docs/examples/5-minute-tutorial/README.md |  4 +-
 ant/docs/examples/classpath/README.md         |  3 +-
 ant/docs/examples/common/included.xml         |  6 +-
 ant/docs/examples/configuration/README.md     |  3 +-
 ant/docs/examples/jpa/README.md               |  3 +-
 ant/docs/examples/native/README.md            |  3 +-
 ant/docs/examples/properties/README.md        |  3 +-
 ant/docs/examples/templatepath/README.md      |  3 +-
 ant/pom.xml                                   | 65 +++++++++++--------
 9 files changed, 55 insertions(+), 38 deletions(-)

diff --git a/ant/docs/examples/5-minute-tutorial/README.md b/ant/docs/examples/5-minute-tutorial/README.md
index 07e8b430cf..5fb96e4f25 100644
--- a/ant/docs/examples/5-minute-tutorial/README.md
+++ b/ant/docs/examples/5-minute-tutorial/README.md
@@ -16,4 +16,6 @@
 To run this example:
   - Have [Apache Ant](https://ant.apache.org) installed
   - Have [H2 Sakila database](https://github.com/hibernate/sakila-h2) running
-  - Issue `ant` from a command-line window 
\ No newline at end of file
+  - Issue `ant -Dhibernate.version=${hibernate.version} -Dh2.version=${h2.version} -Djavaee-api.version=${javaee-api.version}` 
+    from a command-line window opened in this folder
+
diff --git a/ant/docs/examples/classpath/README.md b/ant/docs/examples/classpath/README.md
index 71b3c53674..aebdc3b71d 100644
--- a/ant/docs/examples/classpath/README.md
+++ b/ant/docs/examples/classpath/README.md
@@ -15,4 +15,5 @@
   -->
 To run this example:
   - Have [Apache Ant](https://ant.apache.org) installed
-  - Issue `ant` from a command-line window 
\ No newline at end of file
+- Issue `ant -Dhibernate.version=${hibernate.version} -Dh2.version=${h2.version} -Djavaee-api.version=${javaee-api.version}`
+  from a command-line window opened in this folder
diff --git a/ant/docs/examples/common/included.xml b/ant/docs/examples/common/included.xml
index 4b00c01fd5..98e862105a 100644
--- a/ant/docs/examples/common/included.xml
+++ b/ant/docs/examples/common/included.xml
@@ -15,11 +15,11 @@
   -->
 <project name="common" xmlns:ivy="antlib:org.apache.ivy.ant">
 
-    <property name="hibernate-tools.version" value="@project.version@"/>
-    <property name="javaee-api.version" value="@javaee-api.version@"/>
+    <property name="hibernate-tools.version" value="${hibernate.version}"/>
+    <property name="javaee-api.version" value="${javaee-api.version}"/>
     <property name="jdbc-driver.org" value="com.h2database"/>
     <property name="jdbc-driver.module" value="h2"/>
-    <property name="jdbc-driver.version" value="@h2.version@"/>
+    <property name="jdbc-driver.version" value="${h2.version}"/>
 
     <ivy:cachepath
             organisation="org.hibernate.tool"
diff --git a/ant/docs/examples/configuration/README.md b/ant/docs/examples/configuration/README.md
index 71b3c53674..675196bc05 100644
--- a/ant/docs/examples/configuration/README.md
+++ b/ant/docs/examples/configuration/README.md
@@ -15,4 +15,5 @@
   -->
 To run this example:
   - Have [Apache Ant](https://ant.apache.org) installed
-  - Issue `ant` from a command-line window 
\ No newline at end of file
+  - Issue `ant -Dhibernate.version=${hibernate.version} -Dh2.version=${h2.version} -Djavaee-api.version=${javaee-api.version}`
+    from a command-line window opened in this folder
diff --git a/ant/docs/examples/jpa/README.md b/ant/docs/examples/jpa/README.md
index 71b3c53674..675196bc05 100644
--- a/ant/docs/examples/jpa/README.md
+++ b/ant/docs/examples/jpa/README.md
@@ -15,4 +15,5 @@
   -->
 To run this example:
   - Have [Apache Ant](https://ant.apache.org) installed
-  - Issue `ant` from a command-line window 
\ No newline at end of file
+  - Issue `ant -Dhibernate.version=${hibernate.version} -Dh2.version=${h2.version} -Djavaee-api.version=${javaee-api.version}`
+    from a command-line window opened in this folder
diff --git a/ant/docs/examples/native/README.md b/ant/docs/examples/native/README.md
index 71b3c53674..675196bc05 100644
--- a/ant/docs/examples/native/README.md
+++ b/ant/docs/examples/native/README.md
@@ -15,4 +15,5 @@
   -->
 To run this example:
   - Have [Apache Ant](https://ant.apache.org) installed
-  - Issue `ant` from a command-line window 
\ No newline at end of file
+  - Issue `ant -Dhibernate.version=${hibernate.version} -Dh2.version=${h2.version} -Djavaee-api.version=${javaee-api.version}`
+    from a command-line window opened in this folder
diff --git a/ant/docs/examples/properties/README.md b/ant/docs/examples/properties/README.md
index 71b3c53674..675196bc05 100644
--- a/ant/docs/examples/properties/README.md
+++ b/ant/docs/examples/properties/README.md
@@ -15,4 +15,5 @@
   -->
 To run this example:
   - Have [Apache Ant](https://ant.apache.org) installed
-  - Issue `ant` from a command-line window 
\ No newline at end of file
+  - Issue `ant -Dhibernate.version=${hibernate.version} -Dh2.version=${h2.version} -Djavaee-api.version=${javaee-api.version}`
+    from a command-line window opened in this folder
diff --git a/ant/docs/examples/templatepath/README.md b/ant/docs/examples/templatepath/README.md
index 07e8b430cf..56926633d4 100644
--- a/ant/docs/examples/templatepath/README.md
+++ b/ant/docs/examples/templatepath/README.md
@@ -16,4 +16,5 @@
 To run this example:
   - Have [Apache Ant](https://ant.apache.org) installed
   - Have [H2 Sakila database](https://github.com/hibernate/sakila-h2) running
-  - Issue `ant` from a command-line window 
\ No newline at end of file
+  - Issue `ant -Dhibernate.version=${hibernate.version} -Dh2.version=${h2.version} -Djavaee-api.version=${javaee-api.version}`
+    from a command-line window opened in this folder
diff --git a/ant/pom.xml b/ant/pom.xml
index e2f4ae70ed..dce7b156d7 100644
--- a/ant/pom.xml
+++ b/ant/pom.xml
@@ -33,6 +33,8 @@
 	<properties>
 		<!-- This is a publicly distributed module that should be published: -->
 		<deploy.skip>false</deploy.skip>
+		<!-- To run the integration tests we need to set ${hibernate.version} -->
+		<hibernate.version>${project.version}</hibernate.version>
 	</properties>
 
 	<dependencies>
@@ -68,33 +70,10 @@
 
     <build>
         <plugins>
-			<plugin>
-				<groupId>org.apache.maven.plugins</groupId>
-				<artifactId>maven-resources-plugin</artifactId>
-				<executions>
-					<execution>
-						<id>filter-test-resources</id>
-						<phase>process-test-resources</phase>
-						<goals>
-							<goal>testResources</goal>
-						</goals>
-						<configuration>
-							<resources>
-								<resource>
-									<directory>${project.build.testOutputDirectory}</directory>
-									<filtering>true</filtering>
-									<includes>
-										<include>common/included.xml</include>
-									</includes>
-								</resource>
-							</resources>
-							<delimiters>
-								<delimiter>@*@</delimiter>
-							</delimiters>
-						</configuration>
-					</execution>
-				</executions>
-			</plugin>
+			<!-- Prepare the integration tests :
+			  * Add the 'src/it/java' folder as as source of additional tests (only contains integration tests)
+			  * Add the contents of the 'docs/examples' folder as additional test resources
+			-->
             <plugin>
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>build-helper-maven-plugin</artifactId>
@@ -130,8 +109,38 @@
 					</execution>
                 </executions>
             </plugin>
+			<!-- Prepare the integration tests
+			  * Filter the 'common/included.xml' file, and replace the delimited values with their actual properties
+			-->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-resources-plugin</artifactId>
+				<executions>
+					<execution>
+						<id>filter-test-resources</id>
+						<phase>process-test-resources</phase>
+						<goals>
+							<goal>testResources</goal>
+						</goals>
+						<configuration>
+							<resources>
+								<resource>
+									<directory>${project.build.testOutputDirectory}</directory>
+									<filtering>true</filtering>
+									<includes>
+										<include>common/included.xml</include>
+									</includes>
+								</resource>
+							</resources>
+							<delimiters>
+								<delimiter>@*@</delimiter>
+							</delimiters>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
+			<!-- run the integration tests -->
 			<plugin>
-				<!-- run the integration tests -->
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-failsafe-plugin</artifactId>
 				<executions>