more javadoc about @Generated
including its relationship to @ColumnTransformer
This commit is contained in:
parent
61c128000b
commit
23ff00142f
|
@ -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 "";
|
||||
}
|
||||
|
|
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue