From 6fce38dcff5bee5be565f4142942f80d2aff7f40 Mon Sep 17 00:00:00 2001
From: Koen Aers <koen.aers@gmail.com>
Date: Mon, 12 May 2025 15:34:53 +0200
Subject: [PATCH] HBX-2984: Create Reference Guide for Ant   - Add an example
 using the native '<configuration>' element   - Add XML snippet illustrating
 the use of exporters

Signed-off-by: Koen Aers <koen.aers@gmail.com>
---
 ant/docs/examples/native-cfg/.gitignore | 18 +++++++++++++
 ant/docs/examples/native-cfg/README.md  | 18 +++++++++++++
 ant/docs/examples/native-cfg/build.xml  | 36 +++++++++++++++++++++++++
 ant/docs/reference-guide.md             |  9 +++++++
 4 files changed, 81 insertions(+)
 create mode 100644 ant/docs/examples/native-cfg/.gitignore
 create mode 100644 ant/docs/examples/native-cfg/README.md
 create mode 100644 ant/docs/examples/native-cfg/build.xml

diff --git a/ant/docs/examples/native-cfg/.gitignore b/ant/docs/examples/native-cfg/.gitignore
new file mode 100644
index 0000000000..616fc09000
--- /dev/null
+++ b/ant/docs/examples/native-cfg/.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.                                           #
+############################################################################
+generated-sources
\ No newline at end of file
diff --git a/ant/docs/examples/native-cfg/README.md b/ant/docs/examples/native-cfg/README.md
new file mode 100644
index 0000000000..71b3c53674
--- /dev/null
+++ b/ant/docs/examples/native-cfg/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/native-cfg/build.xml b/ant/docs/examples/native-cfg/build.xml
new file mode 100644
index 0000000000..5dae1a637f
--- /dev/null
+++ b/ant/docs/examples/native-cfg/build.xml
@@ -0,0 +1,36 @@
+<!--
+  ~ 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="native-cfg" default="reveng">
+
+  <!-- Include the 'hibernatetool' task definition from the file '../common/included.xml' -->
+  <include file="../common/included.xml"/>
+
+  <target name="clean">
+    <!-- Delete the folder 'generated-sources' if it exists -->
+    <delete dir="generated-sources"/>
+  </target>
+
+  <target name="reveng" depends="clean">
+    <hibernatetool destdir="generated-sources">
+      <!-- Native configuration reading properties from '../common/hibernate.properties' -->
+      <configuration propertyfile="../common/hibernate.properties"/>
+      <!-- Transform the 'hibernate.properties' file in 'hibernate.cfg.xml' -->
+      <hbm2cfgxml/>
+    </hibernatetool>
+  </target>
+
+</project>
+
diff --git a/ant/docs/reference-guide.md b/ant/docs/reference-guide.md
index 0187289175..d47e3b9582 100644
--- a/ant/docs/reference-guide.md
+++ b/ant/docs/reference-guide.md
@@ -186,6 +186,15 @@ elements is to be found in section 2 further down this guide.
 Hibernate Tools is very versatile and can be used to generate a wide variety of artefacts. This generation
 is performed when adding one or more exporter elements to the `<hibernatetool>` task. 
 
+```xml
+<target name="reveng">
+    <hibernatetool destdir="...">
+        <jdbcconfiguration propertyfile="hibernate.properties" />
+        <hbm2java/>
+    </hibernatetool>
+</target>
+```
+
 The most used exporters are
 * `<hbm2java>` for the generation of Java files
 * `<hbmtemplate>` when generating artefacts based on custom templates