Add more info on Hibernate ORM validation modes to the documentation

Author: marko-bekhta

docs/pom.xml

@@ -3219,6 +3219,17 @@
                             <versionString>${hibernate-search.version}</versionString>
                         </configuration>
                     </execution>
+                    <execution>
+                        <id>parse-version-hibernate-validator</id>
+                        <goals>
+                            <goal>parse-version</goal>
+                        </goals>
+                        <phase>validate</phase>
+                        <configuration>
+                            <propertyPrefix>hibernate-validator</propertyPrefix>
+                            <versionString>${hibernate-validator.version}</versionString>
+                        </configuration>
+                    </execution>
                 </executions>
             </plugin>
             <plugin>

docs/src/main/asciidoc/_attributes.adoc

@@ -29,6 +29,7 @@
 // overridden to the full version, at least when building locally.
 :hibernate-orm-version-major-minor: ${hibernate-orm.majorVersion}.${hibernate-orm.minorVersion}
 :hibernate-search-version-major-minor: ${hibernate-search.majorVersion}.${hibernate-search.minorVersion}
+:hibernate-validator-version-major-minor: ${hibernate-validator.majorVersion}.${hibernate-validator.minorVersion}
 // .
 :quarkus-home-url: ${quarkus-home-url}
 :quarkus-org-url: https://github.com/quarkusio
@@ -54,6 +55,7 @@
 :hibernate-orm-docs-url: https://docs.jboss.org/hibernate/orm/{hibernate-orm-version-major-minor}/userguide/html_single/Hibernate_User_Guide.html
 :hibernate-orm-dialect-docs-url: https://docs.jboss.org/hibernate/orm/{hibernate-orm-version-major-minor}/dialect/dialect.html
 :hibernate-search-docs-url: https://docs.jboss.org/hibernate/search/{hibernate-search-version-major-minor}/reference/en-US/html_single/
+:hibernate-validator-docs-url: https://docs.jboss.org/hibernate/validator/{hibernate-validator-version-major-minor}/reference/en-US/html_single/
 // .
 :amazon-services-guide: https://docs.quarkiverse.io/quarkus-amazon-services/dev/index.html
 :config-consul-guide: https://docs.quarkiverse.io/quarkus-config-extensions/dev/consul.html

docs/src/main/asciidoc/hibernate-orm.adoc

@@ -1510,3 +1510,81 @@ Format mappers *must* have both `@PersistenceUnitExtension` and either `@JsonFor
 
 Having multiple JSON (or XML) format mappers registered for the same persistence unit will result in an exception, because of the ambiguity.
 ====
+
+[[validator_integration]]
+== Validation modes and Hibernate Validator integration
+
+Hibernate Validator integration into Hibernate ORM opens up the following capabilities:
+
+- performing entity validation on lifecycle events
+- applying constraint information from entities to DDL
+
+From Quarkus's perspective, this is controlled by the <<quarkus-hibernate-orm_quarkus-hibernate-orm-validation-mode,`quarkus.hibernate-orm.validation.mode` configuration property>>.
+The available validation modes are:
+
+- `auto` -- the default option; works the same as `callback` and `ddl` enabled simultaneously
+when the Jakarta Validation provider is available (i.e. the Hibernate Validator extension is enabled),
+and as `none` if no provider is available.
+- `callback` -- Hibernate Validator will perform the lifecycle event validation.
+- `ddl` -- Jakarta Validation constraints will be considered for the DDL operations
+- `none` -- Jakarta Validation integration will be disabled.
+
+While all constraints with corresponding Jakarta Validation rules will apply during the `callback` validation,
+in the `ddl` mode, only a subset of constraints is used to influence the DDL.
+In the Hibernate Validator documentation, you can find link:{hibernate-validator-docs-url}#section-builtin-constraints[the list of available constraints] and their impact on the DDL generation.
+
+Let's consider having a simple entity with some constraints applied to its properties:
+
+[source,java]
+----
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+
+@Entity
+public class MyEntity {
+    @Id
+    public long id;
+
+    @NotNull
+    @NotEmpty
+    @Size(max = 50)
+    public String name;
+
+	public String value;
+}
+----
+
+With the `ddl` mode enabled, the resulting schema would be expected to have the following constraints:
+[source,sql]
+----
+create table myentity
+(
+    id    bigint      not null  primary key,
+    name  varchar(50) not null, // <1>
+    value varchar(255),         // <2>
+);
+----
+<1> The `name` column has a `not null` constraint because of the `@NotNull` constraint,
+and the length of the values is limited to `50` because of the `@Size(max=50)` constraint.
++
+<2> Since the `value` property in the entity has no constraints, there are no additional constraints in the DDL,
+and the `255` length limit comes from the default `jakarta.persistence.Column#lenght()`.
+
+With the `callback` mode, expect getting a `jakarta.validation.ConstraintViolationException` thrown:
+
+[source,java]
+----
+try {
+    MyEntity entity = new MyEntity();
+    entity.setName(veryLongName);
+    em.persist(entity);
+    em.flush();
+} catch (ConstraintViolationException exception) {
+    // handle the constraint violations somehow
+}
+----
+
+Since Quarkus has built-in exception mappers for `jakarta.validation.ConstraintViolationException`,
+explicitly handling these exceptions might be redundant. See the xref:validation.adoc#rest-end-point-validation[REST end point validation]
+section of the Hibernate Validator guide for more details.