Describes the generation of values of a certain field or property of an entity. A generated value might be generated in Java, or by the database. Every instance of this interface must implement either or both of BeforeExecutionGenerator and OnExecutionGenerator depending on whether values are generated in Java code before execution of a SQL statement, or by the database when the SQL statement is executed.

• Value generation via arbitrary code written in Java is the responsibility of the method BeforeExecutionGenerator#generate(SharedSessionContractImplementor, Object, Object, EventType). In this case, the generated value is written to the database just like any other field or property value. The Java code may, of course, ask the database to actually generate the value. Examples include timestamp generation using the JVM system time, and id generation using a database sequence.
• A value generated by the database might be generated implicitly, by a trigger, or using a default column value specified in DDL, for example, or it might be generated by a SQL expression occurring explicitly in the SQL insert or update statement. In this case, the generated value may be retrieved from the database using a SQL select, though in certain cases this additional round trip may be avoided. An important example is id generation using an identity column.

A Generator may implement both interfaces and determine the timing of ID generation at runtime. Furthermore, this condition can be based on the state of the owner entity, see generatedOnExecution.

Generically, a generator may be integrated with the program using the meta-annotation org.hibernate.annotations.ValueGenerationType, which associates the generator with a Java annotation type, called the generator annotation. A generator may receive parameters from its generator annotation. The generator may either:

• implement AnnotationBasedGenerator, and receive the annotation as an argument to AnnotationBasedGenerator#initialize,
• declare a constructor with the same signature as AnnotationBasedGenerator#initialize,
• declare a constructor which accepts just the annotation instance, or
• declare a only default constructor, in which case it will not receive parameters.

A generator must implement getEventTypes() to specify the events for which it should be called to produce a new value. EventTypeSets provides a convenient list of possibilities.

There are two especially important applications of this machinery:

• An identifier generator is a generator capable of producing surrogate primary key values. An identifier generator must respond to insert events only. That is, getEventTypes() must return EventTypeSets#INSERT_ONLY. It may be integrated using the org.hibernate.annotations.IdGeneratorType meta-annotation or the older-style org.hibernate.annotations.GenericGenerator annotation.
• A version generator is a generator capable of seeding and incrementing version numbers. A version generator must respond to both insert and update events. That is, getEventTypes() must return EventTypeSets#INSERT_AND_UPDATE. It may be integrated using org.hibernate.annotations.ValueGenerationType meta-annotation.