Merge branch 'main' into HHH-20302-fix-use-max-with-LocalDateTime

Author: MohammedAymanKhan

.git-blame-ignore-revs

@@ -5,3 +5,14 @@
 9c7dd3bf34dfbb2f4fa9eb79a0294c2cc759c836
 b2a528f2945cee26667b22b867ccef143b7c430c
 4273f1cde06f3622f50c2846078398c1977a49c4
+# Hibernate Tools merging
+05a9a8742e1684419ca4bcabcca060dc31048053
+3710fc0e8332992d7b87f66839dc489c4f46a8c8
+09f4af10843fc1d1e1dcd01d1f4856991fa8989d
+c7cc700acfe372cf6e67d7e60b021a8bf08360c6
+6acfbba01701d767065ed87207269d96adbdc52f
+bede74dc6f816065c78e31cd62ef16981dd90497
+75f4ce5d156e7987579eb32834667975d2d81ad4
+c448b6ba40c93c648b8d645d59ccf4bba55df567
+c57ae64b723fc6c7cb23a06a6b871869dca6ff3f
+9580fd1af50a637431a7a51242cdcb35aa3c0fe8

documentation/documentation.gradle

@@ -39,6 +39,13 @@ def jpaVersion = ormBuildDetails.jpaVersion
 defaultTasks 'buildDocs'
 
 configurations {
+	// hibernate-ant -> hibernate-reveng -> google-java-format -> guava
+	// guava publishes JRE/Android variants that Gradle's reportAggregation
+	// configuration cannot resolve; guava is not needed for report aggregation
+	reportAggregation {
+		exclude group: 'com.google.guava', module: 'guava'
+	}
+
 	core
 
 	testing

documentation/src/main/asciidoc/userguide/chapters/tooling/Tooling.adoc

@@ -14,10 +14,12 @@ These services include
 * <<tooling-enhancement,Bytecode enhancement>>
 * <<tooling-modelgen,Static Metamodel generation>>
 * <<tooling-schema,Schema management>>
+* <<tooling-reveng,Reverse engineering>>
 
 include::enhancement.adoc[]
 include::modelgen.adoc[]
 include::schema.adoc[]
+include::reveng.adoc[]
 
 include::gradle.adoc[]
 include::maven.adoc[]

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

@@ -4,7 +4,8 @@
 Hibernate provides https://ant.apache.org/[Ant] support.
 Everything Ant related is available from the
 https://central.sonatype.com/artifact/org.hibernate.orm/hibernate-ant[hibernate-ant]
-library.
+library.  The Ant integration supports <<tooling-ant-enhancement,bytecode enhancement>>,
+<<tooling-ant-modelgen,metamodel generation>>, and <<tooling-ant-reveng,reverse engineering>>.
 
 [[tooling-ant-enhancement]]
 ==== Bytecode Enhancement ====
@@ -192,6 +193,134 @@ Ant's https://ant.apache.org/manual/Tasks/javac.html[javac] task.
 ====
 
 
+[[tooling-ant-reveng]]
+==== Reverse Engineering
+
+Hibernate provides an Ant task for <<tooling-reveng,reverse engineering>> an existing database
+into Java entities, mapping files, DAOs, configuration files, and DDL scripts.
+
+
+[[tooling-ant-reveng-task]]
+===== Task Definition
+
+The reverse engineering task is implemented by `org.hibernate.tool.ant.HibernateToolTask`.
+Define it in your `build.xml` using a `taskdef`:
+
+[source,xml,subs="attributes+"]
+----
+<taskdef name="hibernatetool"
+         classname="org.hibernate.tool.ant.HibernateToolTask"
+         classpathref="toolslib"/>
+----
+
+The `toolslib` classpath must include the
+https://central.sonatype.com/artifact/org.hibernate.orm/hibernate-ant[hibernate-ant]
+artifact and its dependencies, as well as the JDBC driver for your database.
+
+
+[[tooling-ant-reveng-hibernatetool]]
+===== The `<hibernatetool>` Task
+
+The `<hibernatetool>` task is the main entry point. It accepts the following attributes:
+
+`destdir`:: The base output directory for generated files. Required (can be set on the task or on individual exporters).
+`templatepath`:: Path to a directory containing custom FreeMarker templates.
+
+It also accepts `<property>` child elements for passing additional properties, and
+a `<classpath>` element for configuring the classpath.
+
+
+[[tooling-ant-reveng-configurations]]
+===== Configuration Elements
+
+A `<hibernatetool>` task requires exactly one configuration element that defines how metadata is obtained.
+For reverse engineering from a database, use `<jdbcconfiguration>`:
+
+`<jdbcconfiguration>`:: Reads database metadata via JDBC for reverse engineering. Attributes:
++
+--
+`propertyfile`;; Path to a properties file containing JDBC connection settings.
+`configurationfile`;; Path to a `hibernate.cfg.xml` file.
+`packagename`;; The default Java package name for generated classes.
+`reversestrategy`;; Fully qualified class name of a custom reverse engineering strategy.
+`revengfile`;; Path containing reverse engineering configuration XML file(s) for customizing schema selection and type mappings.
+`detectmanytomany`;; Whether to detect many-to-many link tables. Default: `true`.
+`detectonetoone`;; Whether to detect one-to-one associations. Default: `true`.
+`detectoptimisticlock`;; Whether to detect `VERSION`/`TIMESTAMP` columns for optimistic locking. Default: `true`.
+--
+
+Other configuration elements are also available for non-JDBC scenarios:
+
+`<configuration>`:: Uses a `hibernate.cfg.xml` and/or HBM mapping files as input.
+`<jpaconfiguration>`:: Uses a JPA `persistence.xml` as input.
+
+
+[[tooling-ant-reveng-exporters]]
+===== Exporter Elements
+
+One or more exporter elements can be nested inside `<hibernatetool>` to specify what artifacts to generate.
+Each exporter supports a `destdir` attribute to override the output directory.
+
+`<hbm2java>`:: Generates Java entity classes.
+`<hbm2hbmxml>`:: Generates `hbm.xml` mapping files.
+`<hbm2dao>`:: Generates Data Access Object (DAO) classes.
+`<hbm2ddl>`:: Generates DDL scripts (schema creation/drop).
+`<hbm2cfgxml>`:: Generates a `hibernate.cfg.xml` configuration file.
+`<hbm2doc>`:: Generates HTML documentation of the database schema.
+`<hbmtemplate>`:: Runs a custom FreeMarker template for user-defined code generation.
+`<query>`:: Executes HQL queries against the configured metadata.
+
+
+[[tooling-ant-reveng-example]]
+===== Example
+
+The following `build.xml` generates JPA entity classes from a database:
+
+[source,xml,subs="attributes+"]
+----
+<project name="reveng-example" default="generate">
+
+    <path id="toolslib">
+        <fileset dir="${lib.dir}">
+            <include name="**/*.jar"/>
+        </fileset>
+    </path>
+
+    <taskdef name="hibernatetool"
+             classname="org.hibernate.tool.ant.HibernateToolTask"
+             classpathref="toolslib"/>
+
+    <target name="generate">
+        <hibernatetool destdir="${build.dir}/generated-sources">
+            <classpath>
+                <path refid="toolslib"/>
+            </classpath>
+            <jdbcconfiguration
+                propertyfile="src/main/resources/hibernate.properties"
+                packagename="com.example.model"
+                detectmanytomany="true"/>
+            <hbm2java/>
+        </hibernatetool>
+    </target>
+
+</project>
+----
+
+To generate multiple artifact types in a single run, add additional exporter elements:
+
+[source,xml]
+----
+<hibernatetool destdir="${build.dir}/generated-sources">
+    <jdbcconfiguration
+        propertyfile="src/main/resources/hibernate.properties"
+        packagename="com.example.model"/>
+    <hbm2java/>
+    <hbm2dao/>
+    <hbm2ddl/>
+</hibernatetool>
+----
+
+
 [[tooling-ant-schema]]
 ==== Schema Management
 

documentation/src/main/asciidoc/userguide/chapters/tooling/gradle.adoc

@@ -1,8 +1,9 @@
 [[tooling-gradle]]
 === Gradle
 
-Hibernate provides the ability to integrate both
-<<tooling-gradle-enhancement,bytecode enhancement>> and <<tooling-gradle-modelgen,metamodel generation>> capabilities into Gradle builds.
+Hibernate provides the ability to integrate
+<<tooling-gradle-enhancement,bytecode enhancement>>, <<tooling-gradle-modelgen,metamodel generation>>,
+and <<tooling-gradle-reveng,reverse engineering>> capabilities into Gradle builds.
 
 [[tooling-gradle-enhancement]]
 ==== Bytecode Enhancement
@@ -29,7 +30,7 @@ hibernate {
 
 Enhancement is configured through the `enhancement` extension.
 
-NOTE: `hibernate {}` and `enhancement {}` are separate to allow for schema tooling capabilities to be added later.
+NOTE: `enhancement {}` and `reveng {}` are nested inside `hibernate {}` to configure different capabilities of the plugin.
 
 [source,gradle]
 ----
@@ -66,3 +67,104 @@ dependencies {
     annotationProcessor "org.hibernate.orm:hibernate-processor:{fullVersion}"
 }
 ----
+
+
+[[tooling-gradle-reveng]]
+==== Reverse Engineering
+
+The <<tooling-gradle-enhancement,Hibernate ORM Gradle plugin>> also provides
+<<tooling-reveng,reverse engineering>> capabilities to generate Java entities, mapping files,
+DAOs, configuration files, and DDL scripts from an existing database.
+
+NOTE: The Gradle configuration cache must be disabled when using reverse engineering tasks.
+Add `org.gradle.configuration-cache=false` to your `gradle.properties` file.
+
+
+[[tooling-gradle-reveng-tasks]]
+===== Available Tasks
+
+The plugin registers the following tasks:
+
+`generateJava`:: Generates Java entity classes from the database schema.
+`generateDao`:: Generates Data Access Object (DAO) classes.
+`generateHbm`:: Generates `hbm.xml` mapping files.
+`generateCfg`:: Generates a `hibernate.cfg.xml` configuration file.
+`runSql`:: Executes the SQL statement specified by the `sqlToRun` extension property against the database.
+
+
+[[tooling-gradle-reveng-configuration]]
+===== Extension Configuration
+
+Reverse engineering is configured through the `reveng` block inside the `hibernate` extension:
+
+[source,gradle]
+----
+hibernate {
+    reveng {
+        hibernateProperties = 'hibernate.properties'
+        outputFolder = 'generated-sources'
+        packageName = 'com.example.model'
+        generateAnnotations = true
+        useGenerics = true
+    }
+}
+----
+
+The extension supports the following properties:
+
+`hibernateProperties`:: Name of the properties file containing JDBC connection settings. The file is looked up from the project's main resource set. Default: `hibernate.properties`.
+`outputFolder`:: Relative path (from the project directory) where generated files are written. Default: `generated-sources`.
+`packageName`:: The default Java package name for generated classes. Default: empty (default package).
+`generateAnnotations`:: Whether to generate Jakarta Persistence annotations on entity classes. Default: `true`.
+`useGenerics`:: Whether to use Java generics in generated code. Default: `true`.
+`revengStrategy`:: Fully qualified class name of a custom reverse engineering strategy. Default: `null` (uses the default strategy).
+`revengFile`:: Name of a reverse engineering configuration XML file (looked up from the main resource set). Default: `null`.
+`templatePath`:: Path to a directory containing custom FreeMarker templates for code generation. Default: `null`.
+`sqlToRun`:: The SQL statement to execute when running the `runSql` task. Default: empty string.
+
+
+[[tooling-gradle-reveng-properties]]
+===== Hibernate Properties
+
+Create a `hibernate.properties` file in `src/main/resources/` with your JDBC connection settings:
+
+[source,properties]
+----
+hibernate.connection.driver_class=org.h2.Driver
+hibernate.connection.url=jdbc:h2:tcp://localhost/./mydb
+hibernate.connection.username=sa
+hibernate.default_catalog=MY_CATALOG
+hibernate.default_schema=PUBLIC
+----
+
+The JDBC driver must be declared as a project dependency.
+
+
+[[tooling-gradle-reveng-example]]
+===== Example
+
+The following `build.gradle` generates JPA entity classes from an H2 database:
+
+[source,gradle,subs="attributes+"]
+----
+plugins {
+    id 'java'
+    id 'org.hibernate.orm' version '{fullVersion}'
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation 'com.h2database:h2:2.2.224'
+}
+
+hibernate {
+    reveng {
+        hibernateProperties = 'hibernate.properties'
+        packageName = 'com.example.model'
+        outputFolder = 'generated-sources'
+    }
+}
+----