Package org.hibernate.generator

Interface Generator

All Superinterfaces:
Serializable
All Known Subinterfaces:
AnnotationBasedGenerator<A>, BeforeExecutionGenerator, BulkInsertionCapableIdentifierGenerator, IdentifierGenerator, OnExecutionGenerator, OptimizableGenerator, PersistentIdentifierGenerator, PostInsertIdentifierGenerator
All Known Implementing Classes:
AbstractPostInsertGenerator, AbstractUUIDGenerator, Assigned, Assigned, CompositeNestedGeneratedValueGenerator, CurrentTimestampGeneration, ForeignGenerator, GeneratedAlwaysGeneration, GeneratedGeneration, GUIDGenerator, IdentityGenerator, IncrementGenerator, NativeGenerator, OrderedSequenceGenerator, SelectGenerator, SequenceStyleGenerator, SourceGeneration, TableGenerator, TenantIdGeneration, UuidGenerator, UUIDGenerator, UUIDHexGenerator, VersionGeneration
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 identifier generation at runtime. Furthermore, this condition can be based on the state of the owner entity, see generatedOnExecution and generatedBeforeExecution.

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:

A Generator may be a managed bean (for example, a CDI bean) instantiated by the bean container. In this case, only the first of these options, AnnotationBasedGenerator, is available.

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:

Since:
6.2
See Also:

  • Method Details

    • 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.

      Defaults to generatedOnExecution(), but may be overridden to allow conditional on-execution value generation based on the current state of the owner entity.

      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.
      Since:
      6.4
      See Also:

    • generatedBeforeExecution

      default boolean generatedBeforeExecution(Object entity, SharedSessionContractImplementor session)
      Determines if the property value is generated before in Java code that executes before the row is written.

      Defaults to !generatedOnExecution(), but may be overridden to allow conditional before-execution value generation based on the current state of the owner entity.

      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 in Java code before the statement is executed via JDBC.
      Since:
      7.0
      See Also:

    • 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

    • allowMutation

      default boolean allowMutation()
      Determine if this generator allows generated fields to be manually assigned a value on events which do not trigger value generation.
      Returns:
      true if this generator allows manually assigned values, false otherwise (default).
      Since:
      7.0

    • generatesSometimes

      default boolean generatesSometimes()

    • generatesOnInsert

      default boolean generatesOnInsert()

    • generatesOnUpdate

      default boolean generatesOnUpdate()

    • generatesOnForceIncrement

      @Incubating default boolean generatesOnForceIncrement()