org.hibernate.annotations.Generated Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of beangle-hibernate-core Show documentation
Hibernate Orm Core Shade,Support Scala Collection
There is a newer version: 6.6.2.Final
Show newest version
/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or .
 */
package org.hibernate.annotations;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import org.hibernate.generator.EventType;
import org.hibernate.generator.internal.GeneratedGeneration;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import static org.hibernate.generator.EventType.INSERT;

/**
 * Specifies that the value of the annotated property is generated by the
 * database. The generated value will be automatically retrieved using a
 * SQL {@code select} after it is generated.
 * 
 * {@code @Generated} relieves the program of the need to explicitly call
 * {@link org.hibernate.Session#refresh(Object) refresh()} to synchronize
 * state held in memory with state generated by the database when a SQL
 * {@code insert} or {@code update} is executed.
 * 

 * This is most useful when:
 * 

 * a database table has a column value populated by a database trigger,
 * 
a mapped column has a default value defined in DDL, in which case
 *     {@code @Generated} is used in conjunction with {@link ColumnDefault},
 * 
a {@linkplain #sql() SQL expression} is used to compute the value of
 *     a mapped column, or
 * 
when a custom SQL {@link SQLInsert insert} or {@link SQLUpdate update}
 *     statement specified by an entity assigns a value to the annotated
 *     property of the entity, or {@linkplain #writable() transforms} the
 *     value currently assigned to the annotated property.
 * 
 * 
 * On the other hand:
 * 

 * for identity/autoincrement columns mapped to an identifier property,
 *     use {@link jakarta.persistence.GeneratedValue}, and
 * 
for columns with a {@code generated always as} clause, prefer the
 *     {@link GeneratedColumn} annotation, so that Hibernate automatically
 *     generates the correct DDL.
 * 
 *
 * @author Emmanuel Bernard
 *
 * @see jakarta.persistence.GeneratedValue
 * @see ColumnDefault
 * @see GeneratedColumn
 */
@ValueGenerationType( generatedBy = GeneratedGeneration.class )
@IdGeneratorType( GeneratedGeneration.class )
@Target( {FIELD, METHOD} )
@Retention( RUNTIME )
public @interface Generated {
	/**
	 * Specifies the events that cause the value to be generated by the
	 * database.
	 * 
	 * If {@link EventType#INSERT} is included, the generated value
	 *     will be selected after each SQL {@code insert} statement is
	 *     executed.
	 * 
If {@link EventType#UPDATE} is included, the generated value
	 *     will be selected after each SQL {@code update} statement is
	 *     executed.
	 * 
	 */
	EventType[] event() default INSERT;

	/**
	 * Specifies the events that cause the value to be generated by the
	 * database.
	 * 
	 * If {@link GenerationTime#INSERT}, the generated value will be
	 *     selected after each SQL {@code insert} statement is executed.
	 * 
If {@link GenerationTime#UPDATE}, the generated value will be
	 *     selected after each SQL {@code update} statement is executed.
	 * 
If {@link GenerationTime#ALWAYS}, the generated value will be
	 *     selected after each SQL {@code insert} or {@code update}
	 *     statement is executed.
	 * 
	 * 
	 * @deprecated use {@link #event()}
	 */
	@Deprecated(since = "6.2")
	GenerationTime value() default GenerationTime.INSERT;

	/**
	 * A SQL expression used to generate the value of the column mapped by
	 * the annotated property. The expression is included in generated SQL
	 * {@code insert} and {@code update} statements.
	 */
	String sql() default "";

	/**
	 * Determines if the value currently assigned to the annotated property
	 * 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.
	 * 
	 * 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.
	 */
	boolean writable() default false;
}