Package org.hibernate.generator

Interface Generator

All Superinterfaces:

Serializable

All Known Subinterfaces:

AnnotationBasedGenerator<A>, AnnotationValueGeneration<A>, BeforeExecutionGenerator, BulkInsertionCapableIdentifierGenerator, IdentifierGenerator, OnExecutionGenerator, OptimizableGenerator, PersistentIdentifierGenerator, PostInsertIdentifierGenerator, ValueGeneration

All Known Implementing Classes:

AbstractPostInsertGenerator, AbstractUUIDGenerator, Assigned, CompositeNestedGeneratedValueGenerator, CreationTimestampGeneration, CurrentTimestampGeneration, ForeignGenerator, GeneratedAlwaysGeneration, GeneratedGeneration, GUIDGenerator, IdentityGenerator, IncrementGenerator, OrderedSequenceGenerator, SelectGenerator, SequenceStyleGenerator, SourceGeneration, TableGenerator, TenantIdGeneration, UpdateTimestampGeneration, UuidGenerator, UUIDGenerator, UUIDHexGenerator, VersionGeneration, VmValueGeneration

public interface Generator
extends Serializable

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 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(A, java.lang.reflect.Member, org.hibernate.generator.GeneratorCreationContext),
• declare a constructor with the same signature as AnnotationBasedGenerator.initialize(A, java.lang.reflect.Member, org.hibernate.generator.GeneratorCreationContext),
• 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 IdGeneratorType meta-annotation or the older-style 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 ValueGenerationType meta-annotation.

Since:

6.2

See Also:

ValueGenerationType, IdGeneratorType, Generated

Method Summary

Modifier and Type	Method	Description
default boolean	allowAssignedIdentifiers()	Determine if this generator allows identifier values to be manually assigned to the entity instance before persisting it.
boolean	generatedOnExecution()	Determines if the property value is generated when a row is written to the database, or in Java code that executes before the row is written.
default boolean	generatedOnExecution(Object entity, SharedSessionContractImplementor session)	Determines if the property value is generated when a row is written to the database, or in Java code that executes before the row is written.
default boolean	generatesOnInsert()
default boolean	generatesOnUpdate()
default boolean	generatesSometimes()
EnumSet<EventType>	getEventTypes()	The event types for which this generator should be called to produce a new value.

Method Detail

generatedOnExecution

boolean generatedOnExecution()

Determines if the property value is generated when a row is written to the database, or in Java code that executes before the row is written.

• Generators which only implement BeforeExecutionGenerator must result false.
• Generators which only implement OnExecutionGenerator must result true.
• Generators which implement both subinterfaces may decide at runtime what value to return.

Returns:

true if the value is generated by the database as a side effect of the execution of an insert or update statement, or false if it is generated in Java code before the statement is executed via JDBC.

generatedOnExecution

default boolean generatedOnExecution(Object entity,
                                     SharedSessionContractImplementor session)

Determines if the property value is generated when a row is written to the database, or in Java code that executes before the row is written.

Defaults to generatedOnExecution(), but can be overloaded allowing conditional value generation timing (on/before execution) based on the current state of the owner entity. Note that a generator must implement both BeforeExecutionGenerator and OnExecutionGenerator to achieve this behavior.

Parameters:

entity - The instance of the entity owning the attribute for which we are generating a value.

session - The session from which the request originates.

Returns:

true if the value is generated by the database as a side effect of the execution of an insert or update statement, or false if it is generated in Java code before the statement is executed via JDBC.

Since:

6.4

See Also:

generatedOnExecution(), BeforeExecutionGenerator, OnExecutionGenerator

getEventTypes

EnumSet<EventType> getEventTypes()

The event types for which this generator should be called to produce a new value.

Identifier generators must return EventTypeSets.INSERT_ONLY.

Returns:

a set of EventTypes.

allowAssignedIdentifiers

default boolean allowAssignedIdentifiers()

Determine if this generator allows identifier values to be manually assigned to the entity instance before persisting it. This is useful when, for example, needing existing assigned values to be used as identifiers and falling back to generated values by default.

Returns:

true if this generator allows pre-assigned identifier values, false otherwise (default).

Since:

6.5

generatesSometimes

default boolean generatesSometimes()

generatesOnInsert

default boolean generatesOnInsert()

generatesOnUpdate

default boolean generatesOnUpdate()