From 24f041c140dd1dc97a63662dcd5bff09082044ab Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Mon, 31 Mar 2025 11:57:34 +0200
Subject: [PATCH] nice javadoc for ConstraintViolationException

---
 .../ConstraintViolationException.java         | 41 +++++++++++++++++--
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/exception/ConstraintViolationException.java b/hibernate-core/src/main/java/org/hibernate/exception/ConstraintViolationException.java
index bcfcd95fb3a3..e5e77cba273c 100644
--- a/hibernate-core/src/main/java/org/hibernate/exception/ConstraintViolationException.java
+++ b/hibernate-core/src/main/java/org/hibernate/exception/ConstraintViolationException.java
@@ -11,9 +11,17 @@
 
 /**
  * A {@link JDBCException} indicating that the requested DML operation
- * resulted in violation of a defined integrity constraint.
+ * resulted in violation of a defined data integrity constraint.
  *
  * @author Steve Ebersole
+ *
+ * @see jakarta.persistence.Column#unique
+ * @see jakarta.persistence.Column#nullable
+ * @see jakarta.persistence.Column#check
+ * @see jakarta.persistence.JoinColumn#foreignKey
+ * @see jakarta.persistence.Table#uniqueConstraints
+ * @see jakarta.persistence.Table#check
+ * @see jakarta.persistence.JoinTable#foreignKey
  */
 public class ConstraintViolationException extends JDBCException {
 
@@ -43,37 +51,62 @@ public ConstraintViolationException(String message, SQLException root, String sq
 	/**
 	 * Returns the name of the violated constraint, if known.
 	 *
-	 * @return The name of the violated constraint, or null if not known.
+	 * @apiNote Some databases do not reliably report the name of
+	 *          the constraint which was violated. Furthermore,
+	 *          many constraints have system-generated names.
+	 *
+	 * @return The name of the violated constraint, or {@code null}
+	 *         if the name is not known.
+	 *
+	 * @see jakarta.persistence.ForeignKey#name
+	 * @see jakarta.persistence.UniqueConstraint#name
+	 * @see jakarta.persistence.CheckConstraint#name
 	 */
 	public @Nullable String getConstraintName() {
 		return constraintName;
 	}
 
 	/**
-	 * Returns the kind of constraint that was violated.
+	 * Returns the {@linkplain ConstraintKind kind} of constraint
+	 * that was violated.
 	 */
 	public ConstraintKind getKind() {
 		return kind;
 	}
 
 	/**
-	 * Enumerates the kinds of constraint violation recognized by Hibernate.
+	 * Enumerates the kinds of integrity constraint violation recognized
+	 * by Hibernate.
 	 */
 	public enum ConstraintKind {
 		/**
 		 * A {@code not null} constraint violation.
+		 *
+		 * @apiNote The {@linkplain #getConstraintName constraint name}
+		 *          in this case is usually just the column name.
+		 *
+		 * @see jakarta.persistence.Column#nullable
 		 */
 		NOT_NULL,
 		/**
 		 * A {@code unique} or {@code primary key} constraint violation.
+		 *
+		 * @see jakarta.persistence.Column#unique
+		 * @see jakarta.persistence.Table#uniqueConstraints
 		 */
 		UNIQUE,
 		/**
 		 * A {@code foreign key} constraint violation.
+		 *
+		 * @see jakarta.persistence.JoinColumn#foreignKey
+		 * @see jakarta.persistence.JoinTable#foreignKey
 		 */
 		FOREIGN_KEY,
 		/**
 		 * A {@code check} constraint violation.
+		 *
+		 * @see jakarta.persistence.Column#check
+		 * @see jakarta.persistence.Table#check
 		 */
 		CHECK,
 		/**