Hibernate ORM - hibernate-core 6.4.4.Final · org.hibernate.generator.OnExecutionGenerator

A generator which produces a new value by actually going ahead and writing a row to the database, then retrieving the value which was generated by the database itself as a side effect of the SQL insert or update statement which wrote the row.

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.

The generated value is usually retrieved from the database using a SQL select, but in certain cases this additional round trip may be avoided.

Implementations should override referenceColumnsInSql(Dialect), writePropertyValue(), and getReferencedColumnValues(Dialect) as needed in order to achieve the desired behavior.

In implementation of this interface does not specify how the generated value is retrieved from the database after it is generated, this being the responsibility of the coordinating code in org.hibernate.metamodel.mapping.internal.GeneratedValuesProcessor or in an implementation of org.hibernate.id.insert.InsertGeneratedIdentifierDelegate.

Method Summary

Modifier and Type	Method and Description
public default boolean	generatedOnExecution() Implements org.hibernate.generator.Generator.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.
public default InsertGeneratedIdentifierDelegate	getGeneratedIdentifierDelegate(PostInsertIdentityPersister persister) The `InsertGeneratedIdentifierDelegate` used to retrieve the generated value if this object is an identifier generator.
public String[]	Returns: The column value to be used in the generated SQL statement. getReferencedColumnValues(Dialect The SQL dialect, allowing generation of an expression in dialect-specific SQL. dialect) A SQL expression indicating how to calculate the generated values when the mapped columns are included in the SQL statement.
public default String[]	getUniqueKeyPropertyNames(EntityPersister persister) The name of a property of the entity which may be used to locate the just-`insert`ed row containing the generated value.
public boolean	Returns: `true` if the column is included in the column list of the SQL statement. referenceColumnsInSql(Dialect dialect) Determines if the columns whose values are generated are included in the column list of the SQL `insert` or `update` statement.
public boolean	writePropertyValue() Determines if the property values are written to JDBC as the argument of a JDBC `?`

Inherited from org.hibernate.generator.Generator:: generatedOnExecution generatesOnInsert generatesOnUpdate generatesSometimes getEventTypes

Method Detail

generatedOnExecution back to summary

generatedOnExecution	back to summary
public default boolean generatedOnExecution() Implements org.hibernate.generator.Generator.generatedOnExecution. Doc from org.hibernate.generator.Generator.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:boolean `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. Annotations @Override

public default boolean generatedOnExecution()

Implements org.hibernate.generator.Generator.generatedOnExecution.

Doc from org.hibernate.generator.Generator.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:boolean

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.

Annotations

@Override

getGeneratedIdentifierDelegate back to summary

getGeneratedIdentifierDelegate	back to summary
public default InsertGeneratedIdentifierDelegate getGeneratedIdentifierDelegate(PostInsertIdentityPersister persister) The `InsertGeneratedIdentifierDelegate` used to retrieve the generated value if this object is an identifier generator. This is ignored by `org.hibernate.metamodel.mapping.internal.GeneratedValuesProcessor`, which handles multiple generators at once. So if this object is not an identifier generator, this method is never called. Note that this method arguably breaks the separation of concerns between the generator and coordinating code, by specifying how the generated value should be retrieved. The problem solved here is: we want to obtain an insert-generated primary key. But, sadly, without already knowing the primary key, there's no completely-generic way to locate the just-inserted row to obtain it. We need one of the following things: a database which supports some form of `insert ... returning` syntax, or can do the same thing using the JDBC `getGeneratedKeys()` API, or a second unique key of the entity, that is, a property annotated `@NaturalId`. Alternatively, if the generated id is an identity/"autoincrement" column, we can take advantage of special platform-specific functionality to retrieve it. Taking advantage of the specialness of identity columns is the job of one particular implementation: `org.hibernate.id.IdentityGenerator`. And the need for customized behavior for identity columns is the reason why this layer-breaking method exists. Annotations @Incubating

public default InsertGeneratedIdentifierDelegate getGeneratedIdentifierDelegate(PostInsertIdentityPersister persister)

The InsertGeneratedIdentifierDelegate used to retrieve the generated value if this object is an identifier generator.

This is ignored by org.hibernate.metamodel.mapping.internal.GeneratedValuesProcessor, which handles multiple generators at once. So if this object is not an identifier generator, this method is never called.

Note that this method arguably breaks the separation of concerns between the generator and coordinating code, by specifying how the generated value should be retrieved.

The problem solved here is: we want to obtain an insert-generated primary key. But, sadly, without already knowing the primary key, there's no completely-generic way to locate the just-inserted row to obtain it.

We need one of the following things:

a database which supports some form of insert ... returning syntax, or can do the same thing using the JDBC getGeneratedKeys() API, or
a second unique key of the entity, that is, a property annotated @NaturalId.

Alternatively, if the generated id is an identity/"autoincrement" column, we can take advantage of special platform-specific functionality to retrieve it. Taking advantage of the specialness of identity columns is the job of one particular implementation: org.hibernate.id.IdentityGenerator. And the need for customized behavior for identity columns is the reason why this layer-breaking method exists.

Annotations

@Incubating

getReferencedColumnValues back to summary

getReferencedColumnValues	back to summary
public String[] getReferencedColumnValues(Dialect dialect) A SQL expression indicating how to calculate the generated values when the mapped columns are included in the SQL statement. The SQL expressions might be: function calls like `current_timestamp` or `nextval('mysequence')`, or syntactic markers like `default`. Parameters dialect:Dialect The SQL dialect, allowing generation of an expression in dialect-specific SQL. Returns:String[] The column value to be used in the generated SQL statement.

public String[] getReferencedColumnValues(Dialect dialect)

A SQL expression indicating how to calculate the generated values when the mapped columns are included in the SQL statement. The SQL expressions might be:

function calls like current_timestamp or nextval('mysequence'), or
syntactic markers like default.

Parameters

dialect:Dialect: The SQL dialect, allowing generation of an expression in dialect-specific SQL.

Returns:String[]

The column value to be used in the generated SQL statement.

getUniqueKeyPropertyNames back to summary

getUniqueKeyPropertyNames	back to summary
public default String[] getUniqueKeyPropertyNames(EntityPersister persister) The name of a property of the entity which may be used to locate the just-`insert`ed row containing the generated value. Of course, the columns mapped by this property should form a unique key of the entity. The default implementation uses the `@NaturalId` property, if there is one. Annotations @Incubating

public default String[] getUniqueKeyPropertyNames(EntityPersister persister)

The name of a property of the entity which may be used to locate the just-inserted row containing the generated value. Of course, the columns mapped by this property should form a unique key of the entity.

The default implementation uses the @NaturalId property, if there is one.

Annotations

@Incubating

referenceColumnsInSql back to summary

referenceColumnsInSql	back to summary
public boolean referenceColumnsInSql(Dialect dialect) Determines if the columns whose values are generated are included in the column list of the SQL `insert` or `update` statement. For example, this method should return: `true` if the value is generated by calling a SQL function like `current_timestamp`, or `false` if the value is generated by a trigger, by `generated always as`, or using a column default value. Returns:boolean `true` if the column is included in the column list of the SQL statement.

public boolean referenceColumnsInSql(Dialect dialect)

Determines if the columns whose values are generated are included in the column list of the SQL insert or update statement. For example, this method should return:

true if the value is generated by calling a SQL function like current_timestamp, or
false if the value is generated by a trigger, by generated always as, or using a column default value.

Returns:boolean: true if the column is included in the column list of the SQL statement.

writePropertyValue	back to summary
public boolean writePropertyValue() Determines if the property values are written to JDBC as the argument of a JDBC `?` parameter.

public Interface OnExecutionGenerator

Method Summary

Method Detail