From 23ff00142fea818072124873efe58d2de86657ce Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Tue, 8 Nov 2022 13:06:58 +0100
Subject: [PATCH] more javadoc about @Generated

including its relationship to @ColumnTransformer
---
 .../annotations/ColumnTransformer.java        | 37 ++++++++++++++-----
 .../org/hibernate/annotations/Generated.java  |  5 +++
 2 files changed, 33 insertions(+), 9 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java b/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java
index 6131e33a67..ac05ef8736 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java
@@ -14,19 +14,38 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Specifies custom SQL expressions used to read and write to a column in all generated SQL
- * involving the annotated persistent attribute.
+ * Specifies custom SQL expressions used to read and write to the column mapped by
+ * the annotated persistent attribute in all generated SQL involving the annotated
+ * persistent attribute.
  * <ul>
- * <li>A <code>write</code> expression must contain exactly one JDBC-style '?' placeholder.
- * <li>A <code>read</code> expression may not contain JDBC-style placeholders.
+ * <li>A {@link #write} expression must contain exactly one JDBC-style '?' placeholder.
+ * <li>A {@link #read} expression may not contain JDBC-style placeholders.
  * </ul>
  * For example:
  * <pre>
- * {@code @Column(name="credit_card_num")
+ * {@code
+ * @Column(name="credit_card_num")
  * @ColumnTransformer(read="decrypt(credit_card_num)"
  *                    write="encrypt(?)")
- * String creditCardNumber;}
+ * String creditCardNumber;
+ * }
  * </pre>
+ * A column transformer {@link #write} expression transforms the value of a persistent
+ * attribute of an entity as it is being written to the database.
+ * <ul>
+ * <li>If there is a matching {@link #read} expression to undo the effect of this
+ *     transformation, then we're entitled to consider the in-memory state of the Java
+ *     entity instance as synchronized with the database after a SQL {@code insert} or
+ *     {@code update} is executed.
+ * <li>On the other hand, if there's no matching {@link #read} expression, or if the
+ *     read expression does not exactly undo the effect of the transformation, the
+ *     in-memory state of the Java entity instance should be considered unsynchronized
+ *     with the database after every SQL {@code insert} or {@code update} is executed.
+ * </ul>
+ * In the second scenario, we may ask Hibernate to resynchronize the in-memory state
+ * with the database after each {@code insert} or {@code update} by annotating the
+ * persistent attribute {@link Generated @Generated(value=ALWAYS, writable=true)}.
+ * This results in a SQL {@code select} after every {@code insert} or {@code update}.
  *
  * @see ColumnTransformers
  *
@@ -43,13 +62,13 @@ public @interface ColumnTransformer {
 	String forColumn() default "";
 
 	/**
-	 * Custom SQL expression used to read from the column.
+	 * A custom SQL expression used to read from the column.
 	 */
 	String read() default "";
 
 	/**
-	 * Custom SQL expression used to write to the column. The expression must contain exactly
-	 * one JDBC-style '?' placeholder.
+	 * A custom SQL expression used to write to the column. The expression must contain
+	 * exactly one JDBC-style '?' placeholder.
 	 */
 	String write() default "";
 }
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Generated.java b/hibernate-core/src/main/java/org/hibernate/annotations/Generated.java
index ccdb252ca2..130b80731d 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/Generated.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/Generated.java
@@ -61,6 +61,8 @@ public @interface Generated {
 	 * <ul>
 	 * <li>If {@link GenerationTime#INSERT}, the generated value will be
 	 *     selected after each SQL {@code insert} statement is executed.
+	 * <li>If {@link GenerationTime#UPDATE}, the generated value will be
+	 *     selected after each SQL {@code update} statement is executed.
 	 * <li>If {@link GenerationTime#ALWAYS}, the generated value will be
 	 *     selected after each SQL {@code insert} or {@code update}
 	 *     statement is executed.
@@ -80,6 +82,9 @@ public @interface Generated {
 	 * is included in SQL {@code insert} and {@code update} statements. This
 	 * is useful if the generated value is obtained by transforming the
 	 * assigned property value as it is being written.
+	 * <p>
+	 * Often used in combination with {@link SQLInsert}, {@link SQLUpdate},
+	 * or {@link ColumnTransformer#write()}.
 	 *
 	 * @return {@code true} if the current value should be included in SQL
 	 *         {@code insert} and {@code update} statements.