From 0c0765d3dc8b03875406eac479c8b207c3aff34e Mon Sep 17 00:00:00 2001
From: Koen Aers <koen.aers@gmail.com>
Date: Thu, 8 May 2025 16:41:29 +0200
Subject: [PATCH] HBX-2984: Create Reference Guide for Ant   - Add an example
 for the 'property' and 'propertySet' configurations

Signed-off-by: Koen Aers <koen.aers@gmail.com>
---
 ant/docs/examples/classpath/build.xml         |  2 +-
 ant/docs/examples/common/included.xml         |  1 +
 ant/docs/examples/properties/.gitignore       | 18 +++++
 .../examples/properties/HelloExporter.java    | 40 +++++++++++
 ant/docs/examples/properties/README.md        | 18 +++++
 ant/docs/examples/properties/build.xml        | 66 +++++++++++++++++++
 ant/docs/reference-guide.md                   | 12 ++++
 7 files changed, 156 insertions(+), 1 deletion(-)
 create mode 100644 ant/docs/examples/properties/.gitignore
 create mode 100644 ant/docs/examples/properties/HelloExporter.java
 create mode 100644 ant/docs/examples/properties/README.md
 create mode 100644 ant/docs/examples/properties/build.xml

diff --git a/ant/docs/examples/classpath/build.xml b/ant/docs/examples/classpath/build.xml
index 6b575617a6..3437276de1 100644
--- a/ant/docs/examples/classpath/build.xml
+++ b/ant/docs/examples/classpath/build.xml
@@ -34,7 +34,7 @@
   </target>
 
   <target name="reveng" depends="compile">
-    <hibernatetool destdir="generated-sources">
+    <hibernatetool destdir="dummy">
       <!-- The classpath to be used by the 'hibernatetool' task to look up additional classes or resources -->
       <classpath location="additional/classes"/>
       <!-- Dummy configuration, as it is needed for any 'hibernatetool' task -->
diff --git a/ant/docs/examples/common/included.xml b/ant/docs/examples/common/included.xml
index 9275c11972..0c60f45216 100644
--- a/ant/docs/examples/common/included.xml
+++ b/ant/docs/examples/common/included.xml
@@ -36,6 +36,7 @@
     <path id="classpath">
         <path refid="hibernate-tools.path"/>
         <path refid="jdbc-driver.path"/>
+        <path location="."/>
     </path>
 
     <taskdef
diff --git a/ant/docs/examples/properties/.gitignore b/ant/docs/examples/properties/.gitignore
new file mode 100644
index 0000000000..5fe236879c
--- /dev/null
+++ b/ant/docs/examples/properties/.gitignore
@@ -0,0 +1,18 @@
+############################################################################
+# Hibernate Tools, Tooling for your Hibernate Projects                     #
+#                                                                          #
+# Copyright 2004-2025 Red Hat, Inc.                                        #
+#                                                                          #
+# Licensed under the Apache License, Version 2.0 (the "License");          #
+# you may not use this file except in compliance with the License.         #
+# You may obtain a copy of the License at                                  #
+#                                                                          #
+#     http://www.apache.org/licenses/LICENSE-2.0                           #
+#                                                                          #
+# Unless required by applicable law or agreed to in writing, software      #
+# distributed under the License is distributed on an "AS IS" basis,        #
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
+# See the License for the specific language governing permissions and      #
+# limitations under the License.                                           #
+############################################################################
+*.class
\ No newline at end of file
diff --git a/ant/docs/examples/properties/HelloExporter.java b/ant/docs/examples/properties/HelloExporter.java
new file mode 100644
index 0000000000..99aa55805d
--- /dev/null
+++ b/ant/docs/examples/properties/HelloExporter.java
@@ -0,0 +1,40 @@
+/*
+ * Hibernate Tools, Tooling for your Hibernate Projects
+ *
+ * Copyright 2004-2025 Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" basis,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import org.hibernate.tool.api.export.Exporter;
+
+import java.util.Properties;
+
+public class HelloExporter implements Exporter {
+
+    private Properties properties = new Properties();
+
+    @Override
+    public Properties getProperties() {
+        return properties;
+    }
+
+    @Override
+    public void start() {
+        System.out.println("Hello, " + getGreetedOne());
+    }
+
+    private Object getGreetedOne() {
+        Object result = getProperties().get("greetedOne");
+        return (result == null ? "World" : result) + "!" ;
+    }
+}
\ No newline at end of file
diff --git a/ant/docs/examples/properties/README.md b/ant/docs/examples/properties/README.md
new file mode 100644
index 0000000000..71b3c53674
--- /dev/null
+++ b/ant/docs/examples/properties/README.md
@@ -0,0 +1,18 @@
+<!--
+  ~ Copyright 2004 - 2025 Red Hat, Inc.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" basis,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+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
diff --git a/ant/docs/examples/properties/build.xml b/ant/docs/examples/properties/build.xml
new file mode 100644
index 0000000000..0656e40b25
--- /dev/null
+++ b/ant/docs/examples/properties/build.xml
@@ -0,0 +1,66 @@
+<!--
+  ~ Copyright 2004 - 2025 Red Hat, Inc.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" basis,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+<project name="properties" default="reveng">
+
+  <!-- Include the 'hibernatetool' task definition from the file '../common/included.xml' -->
+  <include file="../common/included.xml"/>
+
+  <target name="clean">
+    <!-- Delete the compiled class for 'HelloExporter.java' if it exists -->
+    <delete file="HelloExporter.class"/>
+  </target>
+
+  <target name="compile" depends="clean">
+    <!-- Compile the custom exporter 'HelloExporter.java' -->
+    <javac classpathref="classpath" srcdir="." />
+  </target>
+
+  <target name="reveng" depends="compile">
+    <!-- Property to use in the propertySet case -->
+    <property name="thingOne" value="Bar"/>
+    <echo message="First try without any property set"/>
+    <hibernatetool destdir="dummy">
+      <!-- Dummy configuration, as it is needed for any 'hibernatetool' task -->
+      <configuration />
+      <!-- Custom exporter 'HelloExporter' will say 'Hello, World!' -->
+      <hbmtemplate exporterclass="HelloExporter"/>
+    </hibernatetool>
+    <echo message="Now try with a property element: 'greetedOne' is set to 'Foo'"/>
+    <hibernatetool destdir="dummy">
+      <!-- <property> element to be used by the HelloExporter below -->
+      <property key="greetedOne" value="Foo"/>
+      <!-- Dummy configuration, as it is needed for any 'hibernatetool' task -->
+      <configuration />
+      <!-- Custom exporter of class 'HelloExporter' to be found on the specified classpath -->
+      <hbmtemplate exporterclass="HelloExporter"/>
+    </hibernatetool>
+    <echo message="Lastly try with a propertySet element: 'greetedOne' is set to 'Bar'"/>
+    <hibernatetool destdir="dummy">
+      <!-- <propertySet> element to be used by the HelloExporter below -->
+      <!-- The property 'thingOne' defined above is mapped to 'greetedOne' and subsequently used -->
+      <propertySet>
+        <propertyref prefix="thing"/>
+        <mapper type="glob" from="thing*" to="greeted*"/>
+      </propertySet>
+      <!-- Dummy configuration, as it is needed for any 'hibernatetool' task -->
+      <configuration />
+      <!-- Custom exporter of class 'HelloExporter' to be found on the specified classpath -->
+      <hbmtemplate exporterclass="HelloExporter"/>
+    </hibernatetool>
+  </target>
+
+</project>
+
diff --git a/ant/docs/reference-guide.md b/ant/docs/reference-guide.md
index 7a3872c9bf..b5e4b5b717 100644
--- a/ant/docs/reference-guide.md
+++ b/ant/docs/reference-guide.md
@@ -123,6 +123,18 @@ for classes and/or resources that are used e.g. by the configured exporters.
 All the usual configuration possibilities for [Ant path-like structures](https://ant.apache.org/manual/using.html#path) 
 are applicable. 
 
+### 1.2.4 The `<property>` and `<propertySet>` elements
+
+
+
+### 1.2.5 The Configuration Elements
+
+
+
+### 1.2.6 The Exporter Elements
+
+
+
 ## 2. The Hibernate Tools Configurations 
 
 The reverse engineering and generation of artefacts with Hibernate Tools is based on a