more javadoc about @Generated

including its relationship to @ColumnTransformer
This commit is contained in:
Gavin King 2022-11-08 13:06:58 +01:00
parent 61c128000b
commit 23ff00142f
2 changed files with 33 additions and 9 deletions

View File

@ -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 "";
}

View File

@ -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.