rename Generator subtypes to BeforeExecuteGenerator and OnExecuteGenerator

- and update javadocs
- add/improve doc of new Dialect methods
- add some missing @OverRide annotations

Author: gavinking

hibernate-core/src/main/java/org/hibernate/annotations/IdGeneratorType.java

@@ -23,7 +23,7 @@
  * <p>
  * For example, if we have a custom identifier generator:
  * <pre>{@code
- * public class CustomSequenceGenerator implements InMemoryGenerator {
+ * public class CustomSequenceGenerator implements BeforeExecutionGenerator {
  *     public CustomSequenceGenerator(CustomSequence config, Member annotatedMember,
  *                                    CustomIdGeneratorCreationContext context) {
  *         ...

hibernate-core/src/main/java/org/hibernate/annotations/ValueGenerationType.java

@@ -12,8 +12,8 @@
 
 import org.hibernate.generator.AnnotationBasedGenerator;
 import org.hibernate.generator.Generator;
-import org.hibernate.generator.InDatabaseGenerator;
-import org.hibernate.generator.InMemoryGenerator;
+import org.hibernate.generator.OnExecutionGenerator;
+import org.hibernate.generator.BeforeExecutionGenerator;
 import org.hibernate.generator.internal.TenantIdGeneration;
 
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
@@ -50,9 +50,9 @@
  * Every generator annotation type has an {@link Generator} implementation which
  * is responsible for generating values. It must be either:
  * <ul>
- * <li>an {@link InMemoryGenerator}, for values that are generated in Java code,
+ * <li>an {@link BeforeExecutionGenerator}, for values that are generated in Java code,
  *     using a {@link org.hibernate.tuple.ValueGenerator}, or
- * <li>an {@link InDatabaseGenerator}, for values which are generated by the
+ * <li>an {@link OnExecutionGenerator}, for values which are generated by the
  *     database.
  * </ul>
  * A generator annotation may have members, which are used to configure the
@@ -70,8 +70,8 @@
  * {@link RetentionPolicy#RUNTIME}.
  *
  * @see Generator
- * @see InMemoryGenerator
- * @see InDatabaseGenerator
+ * @see BeforeExecutionGenerator
+ * @see OnExecutionGenerator
  * @see AnnotationBasedGenerator
  *
  * @author Gunnar Morling

hibernate-core/src/main/java/org/hibernate/cfg/annotations/PropertyBinder.java

@@ -49,8 +49,8 @@
 import org.hibernate.generator.Generator;
 import org.hibernate.binder.AttributeBinder;
 import org.hibernate.generator.GeneratorCreationContext;
-import org.hibernate.generator.InDatabaseGenerator;
-import org.hibernate.generator.InMemoryGenerator;
+import org.hibernate.generator.OnExecutionGenerator;
+import org.hibernate.generator.BeforeExecutionGenerator;
 import org.jboss.logging.Logger;
 
 import java.lang.annotation.Annotation;
@@ -452,10 +452,10 @@ private GeneratorCreator getValueGenerationFromAnnotations(XProperty property) {
 	}
 
 	private static void checkGeneratorClass(Class<? extends Generator> generatorClass) {
-		if ( !InMemoryGenerator.class.isAssignableFrom( generatorClass )
-				&& !InDatabaseGenerator.class.isAssignableFrom( generatorClass ) ) {
+		if ( !BeforeExecutionGenerator.class.isAssignableFrom( generatorClass )
+				&& !OnExecutionGenerator.class.isAssignableFrom( generatorClass ) ) {
 			throw new MappingException("Generator class '" + generatorClass.getName()
-					+ "' must implement either 'InMemoryGenerator' or 'InDatabaseGenerator'");
+					+ "' must implement either 'BeforeExecutionGenerator' or 'OnExecutionGenerator'");
 		}
 	}
 

hibernate-core/src/main/java/org/hibernate/dialect/Dialect.java

@@ -3436,17 +3436,47 @@ public boolean supportsSubqueryInSelect() {
 	}
 
 	/**
-	 * Does this dialect fully support {@code insert ... returning ...} in some form?
+	 * Does this dialect fully support returning arbitrary generated column values
+	 * after execution of an {@code insert} statement, using native SQL syntax?
+	 * <p>
+	 * Support for identity columns is insufficient here, we require something like:
+	 * <ol>
+	 * <li>{@code insert ... returning ...}
+	 * <li>{@code select from final table (insert ... )}
+	 * </ol>
 	 *
 	 * @return {@code true} if {@link org.hibernate.id.insert.InsertReturningDelegate}
 	 *         works for any sort of primary key column (not just identity columns), or
 	 *         {@code false} if {@code InsertReturningDelegate} does not work, or only
 	 *         works for specialized identity/"autoincrement" columns
+	 *
+	 * @see org.hibernate.generator.OnExecutionGenerator#getGeneratedIdentifierDelegate
+	 * @see org.hibernate.id.insert.InsertReturningDelegate
+	 *
+	 * @since 6.2
 	 */
 	public boolean supportsInsertReturning() {
 		return false;
 	}
 
+	/**
+	 * Does this dialect fully support returning arbitrary generated column values
+	 * after execution of an {@code insert} statement, using the JDBC method
+	 * {@link Connection#prepareStatement(String, String[])}.
+	 * <p>
+	 * Support for returning the generated value of an identity column via the JDBC
+	 * method {@link Connection#prepareStatement(String, int)} is insufficient here.
+	 *
+	 * @return {@code true} if {@link org.hibernate.id.insert.GetGeneratedKeysDelegate}
+	 *         works for any sort of primary key column (not just identity columns), or
+	 *         {@code false} if {@code GetGeneratedKeysDelegate} does not work, or only
+	 *         works for specialized identity/"autoincrement" columns
+	 *
+	 * @see org.hibernate.generator.OnExecutionGenerator#getGeneratedIdentifierDelegate
+	 * @see org.hibernate.id.insert.GetGeneratedKeysDelegate
+	 *
+	 * @since 6.2
+	 */
 	public boolean supportsInsertReturningGeneratedKeys() {
 		return false;
 	}

hibernate-core/src/main/java/org/hibernate/dialect/temptable/TemporaryTable.java

@@ -274,7 +274,7 @@ public static TemporaryTable createEntityTable(
 							.getEntityBinding( entityDescriptor.getEntityName() );
 
 					final Generator identifierGenerator = entityDescriptor.getEntityPersister().getGenerator();
-					final boolean identityColumn = identifierGenerator.generatedByDatabase();
+					final boolean identityColumn = identifierGenerator.generatedOnExecute();
 					final boolean hasOptimizer;
 					if ( identityColumn ) {
 						hasOptimizer = false;

hibernate-core/src/main/java/org/hibernate/event/internal/AbstractSaveEventListener.java

@@ -33,7 +33,7 @@
 import org.hibernate.persister.entity.EntityPersister;
 import org.hibernate.pretty.MessageHelper;
 import org.hibernate.generator.Generator;
-import org.hibernate.generator.InMemoryGenerator;
+import org.hibernate.generator.BeforeExecutionGenerator;
 import org.hibernate.type.Type;
 import org.hibernate.type.TypeHelper;
 
@@ -116,8 +116,8 @@ protected Object saveWithGeneratedId(
 
 		final EntityPersister persister = source.getEntityPersister( entityName, entity );
 		Generator generator = persister.getGenerator();
-		if ( !generator.generatedByDatabase() ) {
-			final Object generatedId = ( (InMemoryGenerator) generator ).generate( source, entity, null, INSERT );
+		if ( !generator.generatedOnExecute() ) {
+			final Object generatedId = ( (BeforeExecutionGenerator) generator ).generate( source, entity, null, INSERT );
 			if ( generatedId == null ) {
 				throw new IdentifierGenerationException( "null id generated for: " + entity.getClass() );
 			}

hibernate-core/src/main/java/org/hibernate/generator/AnnotationBasedGenerator.java

@@ -29,8 +29,8 @@
  * {@code AnnotationType} is the generator annotation type used to configure the
  * generator.
  * <p>
- * Every instance of this class must implement either {@link InMemoryGenerator} or
- * {@link InDatabaseGenerator}.
+ * Every instance of this class must implement either {@link BeforeExecutionGenerator} or
+ * {@link OnExecutionGenerator}.
  *
  * @param <A> The generator annotation type supported by an implementation
  *

hibernate-core/src/main/java/org/hibernate/generator/InMemoryGenerator.java renamed to hibernate-core/src/main/java/org/hibernate/generator/BeforeExecutionGenerator.java

@@ -15,7 +15,7 @@
  * database via a parameter of a JDBC prepared statement, just like any other field or property
  * value.
  * <p>
- * Any {@link InMemoryGenerator} with {@linkplain #getEventTypes() generation event types}
+ * Any {@link BeforeExecutionGenerator} with {@linkplain #getEventTypes() generation event types}
  * {@link EventTypeSets#INSERT_ONLY} may be used to produce {@linkplain jakarta.persistence.Id
  * identifiers}. The built-in identifier generators all implement the older extension point
  * {@link org.hibernate.id.IdentifierGenerator}, which is a subtype of this interface, but that
@@ -30,10 +30,11 @@
  * {@link org.hibernate.annotations.ValueGenerationType}, as for any {@link Generator}.
  *
  * @author Steve Ebersole
+ * @author Gavin King
  *
  * @since 6.2
  */
-public interface InMemoryGenerator extends Generator {
+public interface BeforeExecutionGenerator extends Generator {
 	/**
 	 * Generate a value.
 	 *
@@ -45,7 +46,8 @@ public interface InMemoryGenerator extends Generator {
 	 */
 	Object generate(SharedSessionContractImplementor session, Object owner, Object currentValue, EventType eventType);
 
-	default boolean generatedByDatabase() {
+	@Override
+	default boolean generatedOnExecute() {
 		return false;
 	}
 }

hibernate-core/src/main/java/org/hibernate/generator/Generator.java

@@ -7,7 +7,6 @@
 package org.hibernate.generator;
 
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
-import org.hibernate.tuple.ValueGenerator;
 
 import java.io.Serializable;
 import java.util.EnumSet;
@@ -18,18 +17,22 @@
 /**
  * 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 must implement either
- * {@link InMemoryGenerator} or {@link InDatabaseGenerator} depending on whether values are
- * generated in Java code, or by the database.
+ * {@link BeforeExecutionGenerator} or {@link 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.
  * <ul>
  * <li>Value generation via arbitrary code written in Java is the responsibility of the method
- *     {@link InMemoryGenerator#generate(SharedSessionContractImplementor, Object, Object, EventType)}.
+ *     {@link 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.
+ *	   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.
  * <li>A value generated by the database might be generated implicitly, by a trigger, or using
  *	   a {@code default} column value specified in DDL, for example, or it might be generated
  *	   by a SQL expression occurring explicitly in the SQL {@code insert} or {@code update}
- *	   statement. In this case, the generated value is retrieved from the database using a SQL
- *	   {@code select}.
+ *	   statement. In this case, the generated value may be retrieved from the database using a
+ *	   SQL {@code select}, though in certain cases this additional round trip may be avoided.
+ *	   An important example is id generation using an identity column.
  * </ul>
  * Generically, a generator may be integrated with the program using the meta-annotation
  * {@link org.hibernate.annotations.ValueGenerationType}, which associates the generator with
@@ -71,12 +74,20 @@
  */
 public interface Generator extends Serializable {
 	/**
-	 * Determines if the property value is generated in Java, or by the database.
+	 * Determines if the property value is generated in Java code, or by the database.
+	 * <ul>
+	 * <li>Generators which only implement {@link BeforeExecutionGenerator} must result
+	 *     {@code false}.
+	 * <li>Generators which only implement {@link OnExecutionGenerator} must result
+	 *     {@code true}.
+	 * <li>Generators which implement both subinterfaces may decide at runtime what value
+	 *     to return.
+	 * </ul>
 	 *
 	 * @return {@code true} if the value is generated by the database, or false if it is
-	 *		   generated in Java using a {@link ValueGenerator}.
+	 *		   generated in Java code.
 	 */
-	boolean generatedByDatabase();
+	boolean generatedOnExecute();
 
 	/**
 	 * The {@linkplain EventType event types} for which this generator should be called

hibernate-core/src/main/java/org/hibernate/generator/InDatabaseGenerator.java renamed to hibernate-core/src/main/java/org/hibernate/generator/OnExecutionGenerator.java

@@ -18,11 +18,18 @@
 import static org.hibernate.generator.internal.NaturalIdHelper.getNaturalIdPropertyNames;
 
 /**
+ * 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 {@code insert} or {@code update} statement which wrote the row.
+ * <p>
  * A value generated by the database might be generated implicitly, by a trigger, or using
  * a {@code default} column value specified in DDL, for example, or it might be generated
  * by a SQL expression occurring explicitly in the SQL {@code insert} or {@code update}
- * statement. In this case, the generated value is retrieved from the database using a SQL
- * {@code select}.
+ * statement.
+ * <p>
+ * The generated value is usually retrieved from the database using a SQL {@code select},
+ * but in {@linkplain #getGeneratedIdentifierDelegate certain cases} this additional round
+ * trip may be avoided.
  * <p>
  * Implementations should override {@link #referenceColumnsInSql(Dialect)},
  * {@link #writePropertyValue()}, and {@link #getReferencedColumnValues(Dialect)} as needed
@@ -34,10 +41,11 @@
  * implementation of {@link org.hibernate.id.insert.InsertGeneratedIdentifierDelegate}.
  *
  * @author Steve Ebersole
+ * @author Gavin King
  *
  * @since 6.2
  */
-public interface InDatabaseGenerator extends Generator {
+public interface OnExecutionGenerator extends Generator {
 
 	/**
 	 * Determines if the columns whose values are generated are included in the column list
@@ -133,7 +141,8 @@ default String[] getUniqueKeyPropertyNames(EntityPersister persister) {
 		return getNaturalIdPropertyNames( persister );
 	}
 
-	default boolean generatedByDatabase() {
+	@Override
+	default boolean generatedOnExecute() {
 		return true;
 	}
 }

hibernate-core/src/main/java/org/hibernate/generator/internal/CurrentTimestampGeneration.java

@@ -14,8 +14,8 @@
 import org.hibernate.dialect.Dialect;
 import org.hibernate.engine.spi.SharedSessionContractImplementor;
 import org.hibernate.generator.EventType;
-import org.hibernate.generator.InDatabaseGenerator;
-import org.hibernate.generator.InMemoryGenerator;
+import org.hibernate.generator.OnExecutionGenerator;
+import org.hibernate.generator.BeforeExecutionGenerator;
 import org.hibernate.internal.util.ReflectHelper;
 import org.hibernate.generator.GeneratorCreationContext;
 import org.hibernate.tuple.GenerationTiming;
@@ -46,7 +46,7 @@
  * @author Steve Ebersole
  * @author Gavin King
  */
-public class CurrentTimestampGeneration implements InMemoryGenerator, InDatabaseGenerator {
+public class CurrentTimestampGeneration implements BeforeExecutionGenerator, OnExecutionGenerator {
 	private final EnumSet<EventType> eventTypes;
 	private final ValueGenerator<?> generator;
 
@@ -80,7 +80,7 @@ private static ValueGenerator<?> getGenerator(SourceType source, Member member)
 	}
 
 	@Override
-	public boolean generatedByDatabase() {
+	public boolean generatedOnExecute() {
 		return generator == null;
 	}
 

hibernate-core/src/main/java/org/hibernate/generator/internal/GeneratedAlwaysGeneration.java

@@ -9,7 +9,7 @@
 import org.hibernate.annotations.GeneratedColumn;
 import org.hibernate.dialect.Dialect;
 import org.hibernate.generator.EventType;
-import org.hibernate.generator.InDatabaseGenerator;
+import org.hibernate.generator.OnExecutionGenerator;
 
 import java.util.EnumSet;
 
@@ -20,7 +20,7 @@
  *
  * @author Gavin King
  */
-public class GeneratedAlwaysGeneration implements InDatabaseGenerator {
+public class GeneratedAlwaysGeneration implements OnExecutionGenerator {
 
 	public GeneratedAlwaysGeneration() {}
 

hibernate-core/src/main/java/org/hibernate/generator/internal/GeneratedGeneration.java

@@ -10,23 +10,23 @@
 import org.hibernate.annotations.GenerationTime;
 import org.hibernate.dialect.Dialect;
 import org.hibernate.generator.EventType;
-import org.hibernate.generator.InDatabaseGenerator;
+import org.hibernate.generator.OnExecutionGenerator;
 
 import java.util.EnumSet;
 
 import static org.hibernate.generator.EventTypeSets.fromArray;
 import static org.hibernate.internal.util.StringHelper.isEmpty;
 
 /**
- * A fairly generic {@link InDatabaseGenerator} which marks a property as generated in the
+ * A fairly generic {@link OnExecutionGenerator} which marks a property as generated in the
  * database with semantics given explicitly by a {@link Generated @Generated} annotation.
  *
  * @see Generated
  *
  * @author Steve Ebersole
  * @author Gunnar Morling
  */
-public class GeneratedGeneration implements InDatabaseGenerator {
+public class GeneratedGeneration implements OnExecutionGenerator {
 
 	private final EnumSet<EventType> eventTypes;
 	private final boolean writable;

hibernate-core/src/main/java/org/hibernate/generator/internal/SourceGeneration.java

@@ -17,7 +17,7 @@
 import org.hibernate.generator.EventType;
 import org.hibernate.generator.EventTypeSets;
 import org.hibernate.generator.GeneratorCreationContext;
-import org.hibernate.generator.InMemoryGenerator;
+import org.hibernate.generator.BeforeExecutionGenerator;
 import org.hibernate.internal.CoreMessageLogger;
 import org.hibernate.tuple.TimestampGenerators;
 import org.hibernate.tuple.ValueGenerator;
@@ -52,7 +52,7 @@
  */
 @Deprecated(since = "6.2")
 @Internal
-public class SourceGeneration implements InMemoryGenerator {
+public class SourceGeneration implements BeforeExecutionGenerator {
 
 	private static final CoreMessageLogger log = Logger.getMessageLogger(
 			CoreMessageLogger.class,