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; import static java.lang.annotation.RetentionPolicy.RUNTIME;
/** /**
* Specifies custom SQL expressions used to read and write to a column in all generated SQL * Specifies custom SQL expressions used to read and write to the column mapped by
* involving the annotated persistent attribute. * the annotated persistent attribute in all generated SQL involving the annotated
* persistent attribute.
* <ul> * <ul>
* <li>A <code>write</code> expression must contain exactly one JDBC-style '?' placeholder. * <li>A {@link #write} expression must contain exactly one JDBC-style '?' placeholder.
* <li>A <code>read</code> expression may not contain JDBC-style placeholders. * <li>A {@link #read} expression may not contain JDBC-style placeholders.
* </ul> * </ul>
* For example: * For example:
* <pre> * <pre>
* {@code @Column(name="credit_card_num") * {@code
* @Column(name="credit_card_num")
* @ColumnTransformer(read="decrypt(credit_card_num)" * @ColumnTransformer(read="decrypt(credit_card_num)"
* write="encrypt(?)") * write="encrypt(?)")
* String creditCardNumber;} * String creditCardNumber;
* }
* </pre> * </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 * @see ColumnTransformers
* *
@ -43,13 +62,13 @@ public @interface ColumnTransformer {
String forColumn() default ""; 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 ""; String read() default "";
/** /**
* Custom SQL expression used to write to the column. The expression must contain exactly * A custom SQL expression used to write to the column. The expression must contain
* one JDBC-style '?' placeholder. * exactly one JDBC-style '?' placeholder.
*/ */
String write() default ""; String write() default "";
} }

View File

@ -61,6 +61,8 @@ public @interface Generated {
* <ul> * <ul>
* <li>If {@link GenerationTime#INSERT}, the generated value will be * <li>If {@link GenerationTime#INSERT}, the generated value will be
* selected after each SQL {@code insert} statement is executed. * 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 * <li>If {@link GenerationTime#ALWAYS}, the generated value will be
* selected after each SQL {@code insert} or {@code update} * selected after each SQL {@code insert} or {@code update}
* statement is executed. * statement is executed.
@ -80,6 +82,9 @@ public @interface Generated {
* is included in SQL {@code insert} and {@code update} statements. This * is included in SQL {@code insert} and {@code update} statements. This
* is useful if the generated value is obtained by transforming the * is useful if the generated value is obtained by transforming the
* assigned property value as it is being written. * 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 * @return {@code true} if the current value should be included in SQL
* {@code insert} and {@code update} statements. * {@code insert} and {@code update} statements.