Merge remote-tracking branch 'upstream/main' into main-perf

Author: theigl

hibernate-community-dialects/src/test/java/org/hibernate/community/dialect/SQLServer2005DialectTestCase.java

@@ -26,7 +26,7 @@
  * Unit test of the behavior of the SQLServerDialect utility methods
  *
  * @author Valotasion Yoryos
- * @author Lukasz Antoniak (lukasz dot antoniak at gmail dot com)
+ * @author Lukasz Antoniak
  * @author Chris Cranford
  */
 public class SQLServer2005DialectTestCase extends BaseUnitTestCase {

hibernate-core/src/main/java/org/hibernate/Session.java

@@ -118,7 +118,7 @@
  * An easy way to be sure that session and transaction management is being done correctly
  * is to {@linkplain SessionFactory#inTransaction(Consumer) let the factory do it}:
  * <pre>
- * sessionFactory.inTransaction(session -> {
+ * sessionFactory.inTransaction(session -&gt; {
  *     //do the work
  *     ...
  * });
@@ -127,7 +127,7 @@
  * A session may be used to {@linkplain #doWork(Work) execute JDBC work} using its JDBC
  * connection and transaction:
  * <pre>
- * session.doWork(connection -> {
+ * session.doWork(connection -&gt; {
  *     try ( PreparedStatement ps = connection.prepareStatement( " ... " ) ) {
  *         ps.execute();
  *     }

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

@@ -33,6 +33,13 @@
 @Retention( RUNTIME )
 @Repeatable( CompositeTypeRegistrations.class )
 public @interface CompositeTypeRegistration {
+	/**
+	 * The embeddable type described by the {@link #userType}.
+	 */
 	Class<?> embeddableClass();
+
+	/**
+	 * The {@link CompositeUserType}.
+	 */
 	Class<? extends CompositeUserType<?>> userType();
 }

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

@@ -19,17 +19,21 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Registers the BasicJavaType to use for the given {@link #javaType}
+ * Registers a {@link BasicJavaType} as the default Java type descriptor for the given
+ * {@link #javaType}.
  * <p>
  * Registrations applied to a package are processed before Hibernate begins to process
  * any attributes, etc.
  * <p>
  * Registrations applied to a class are only applied once Hibernate begins to process
- * that class; it will also affect all future processing.  However, it will not change
- * previous resolutions to use this newly registered one.  Because of this randomness
+ * that class; it will also affect all future processing. However, it will not change
+ * previous resolutions to use this newly registered one. Due to this nondeterminism,
  * it is recommended to only apply registrations to packages or to use a
  * {@link org.hibernate.boot.model.TypeContributor}.
  *
+ * @implNote {@link BasicJavaType} registrations are maintained by the
+ *           {@link org.hibernate.type.descriptor.java.spi.JavaTypeRegistry}.
+ *
  * @since 6.0
  */
 @Target({PACKAGE, TYPE, ANNOTATION_TYPE})

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

@@ -12,26 +12,33 @@
 import java.lang.annotation.Target;
 
 import org.hibernate.type.descriptor.jdbc.JdbcType;
-import org.hibernate.type.descriptor.jdbc.spi.JdbcTypeRegistry;
 
 import static java.lang.annotation.ElementType.PACKAGE;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Describes a SqlTypeDescriptor to be added to the {@link JdbcTypeRegistry}
+ * Registers a {@link JdbcType} as the default JDBC type descriptor for a certain
+ * {@linkplain org.hibernate.type.SqlTypes type code}. The type code is determined by:
+ * <ol>
+ * <li>{@link #registrationCode}, if specified, or
+ * <li>{@link JdbcType#getJdbcTypeCode()}.
+ * </ol>
  * <p>
  * Registrations applied to a package are processed before Hibernate begins to process
  * any attributes, etc.
  * <p>
  * Registrations applied to a class are only applied once Hibernate begins to process
- * that class; it will also affect all future processing.  However, it will not change
- * previous resolutions to use this newly registered one.  Because of this randomness
+ * that class; it will also affect all future processing. However, it will not change
+ * previous resolutions to use this newly registered one. Due to this nondeterminism,
  * it is recommended to only apply registrations to packages or to use a
  * {@link org.hibernate.boot.model.TypeContributor}.
  *
  * @see org.hibernate.boot.model.TypeContributor
  *
+ * @implNote {@link JdbcType} registrations are maintained by the
+ *           {@link org.hibernate.type.descriptor.jdbc.spi.JdbcTypeRegistry}.
+ *
  * @since 6.0
  */
 @Target({PACKAGE, TYPE})

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

@@ -19,7 +19,8 @@
 
 /**
  * Registers a custom {@linkplain UserType user type} implementation
- * to be used by default for all references to a particular basic type.
+ * to be used by default for all references to a particular class of
+ * {@linkplain jakarta.persistence.Basic basic type}.
  * <p>
  * May be overridden for a specific entity field or property using
  * {@link Type @Type}.
@@ -36,6 +37,13 @@
 @Retention( RUNTIME )
 @Repeatable( TypeRegistrations.class )
 public @interface TypeRegistration {
+	/**
+	 * The basic type described by the {@link #userType}.
+	 */
 	Class<?> basicClass();
+
+	/**
+	 * The {@link UserType}.
+	 */
 	Class<? extends UserType<?>> userType();
 }

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

@@ -39,7 +39,7 @@ enum Style {
 		RANDOM,
 		/**
 		 * Applies a time-based generation strategy consistent with IETF RFC 4122.
-		 * Uses IP address rather than mac address.
+		 * Uses IP address rather than MAC address.
 		 *
 		 * @implNote Can be a bottleneck due to the need to synchronize in order
 		 *           to increment an internal count as part of the algorithm.

hibernate-core/src/main/java/org/hibernate/annotations/package-info.java

@@ -122,6 +122,10 @@
  *         <li>{@link org.hibernate.annotations.Nationalized}
  *         </ul>
  *     <li><p>
+ *         Furthermore, a {@link org.hibernate.annotations.JavaTypeRegistration} or
+ *         {@link org.hibernate.annotations.JdbcTypeRegistration} allows the choice
+ *         of {@code JavaType} or {@code JdbcType} to be made <em>implicitly</em>.
+ *     <li><p>
  *         A compositional type mapping also comes with a
  *         {@link org.hibernate.type.descriptor.java.MutabilityPlan}, which is usually
  *         chosen by the {@code JavaType}, but which may be overridden using the
@@ -133,12 +137,15 @@
  *     all come in specialized flavors for handling map keys, list indexes, and so on.
  * <li><p>
  *     Alternatively, a program may implement the {@link org.hibernate.usertype.UserType}
- *     interface and associate it with a field or property explicitly using the
- *     {@link org.hibernate.annotations.Type @Type} annotation, or implicitly using the
- *     {@link org.hibernate.annotations.TypeRegistration @TypeRegistration} annotation.
+ *     interface and associate it with a field or property
+ *     <ul>
+ *     <li>explicitly, using the {@link org.hibernate.annotations.Type @Type} annotation,
+ *         or
+ *     <li>implicitly, using the {@link org.hibernate.annotations.TypeRegistration @TypeRegistration}
+ *         annotation.
+ *     </ul>
  *     <p>
  *     There are some specialized flavors of the {@code @Type} annotation too.
- * </li>
  * </ul>
  * <p>
  * These two approaches cannot be used together. A {@code UserType} always takes precedence
@@ -165,6 +172,21 @@
  * See the <em>User Guide</em> or the package {@link org.hibernate.type} for further
  * discussion.
  *
+ * <h3 id="composite-types">Composite types</h3>
+ *
+ * A <em>composite type</em> is a type which maps to multiple columns. An example of a
+ * composite type is an {@linkplain jakarta.persistence.Embeddable embeddable} object,
+ * but this is not the only sort of composite type in Hibernate.
+ * <p>
+ * A program may implement the {@link org.hibernate.usertype.CompositeUserType}
+ * interface and associate it with a field or property:
+ * <ul>
+ * <li>explicitly, using the {@link org.hibernate.annotations.CompositeType @CompositeType}
+ *     annotation, or
+ * <li>implicitly, using the {@link org.hibernate.annotations.CompositeTypeRegistration @CompositeTypeRegistration}
+ *     annotation.
+ * </ul>
+ *
  * <h3 id="second-level-cache">Second level cache</h3>
  * <p>
  * When we make a decision to store an entity in the second-level cache, we must decide

hibernate-core/src/main/java/org/hibernate/boot/internal/IdGeneratorInterpreterImpl.java

@@ -30,7 +30,7 @@
 public class IdGeneratorInterpreterImpl implements IdGeneratorStrategyInterpreter {
 	private static final CoreMessageLogger log = CoreLogging.messageLogger( IdGeneratorInterpreterImpl.class );
 
-	private IdGeneratorStrategyInterpreter fallbackInterpreter = FallbackInterpreter.INSTANCE;
+	private final IdGeneratorStrategyInterpreter fallbackInterpreter = FallbackInterpreter.INSTANCE;
 	private ArrayList<IdGeneratorStrategyInterpreter> delegates;
 
 	@Override
@@ -88,16 +88,13 @@ private static class FallbackInterpreter implements IdGeneratorStrategyInterpret
 		@Override
 		public String determineGeneratorName(GenerationType generationType, GeneratorNameDeterminationContext context) {
 			switch ( generationType ) {
-				case IDENTITY: {
+				case IDENTITY:
 					return "identity";
-				}
-				case SEQUENCE: {
+				case SEQUENCE:
 					return SequenceStyleGenerator.class.getName();
-				}
-				case TABLE: {
+				case TABLE:
 					return org.hibernate.id.enhanced.TableGenerator.class.getName();
-				}
-				case AUTO: {
+				case AUTO:
 					if ( "increment".equalsIgnoreCase( context.getGeneratedValueGeneratorName() ) ) {
 						return IncrementGenerator.class.getName();
 					}
@@ -108,14 +105,12 @@ public String determineGeneratorName(GenerationType generationType, GeneratorNam
 					}
 
 					return SequenceStyleGenerator.class.getName();
-				}
-				default: {
+				default:
 					// UNKNOWN
 					if ( "UUID".equals( generationType.name() ) ) {
 						return UUIDGenerator.class.getName();
 					}
 					throw new UnsupportedOperationException( "Unsupported generation type:" + generationType );
-				}
 			}
 		}
 

hibernate-core/src/main/java/org/hibernate/boot/model/IdentifierGeneratorDefinition.java

@@ -16,7 +16,6 @@
 import org.hibernate.AssertionFailure;
 import org.hibernate.Internal;
 import org.hibernate.id.IdentifierGenerator;
-import org.hibernate.internal.util.collections.CollectionHelper;
 
 import jakarta.persistence.GenerationType;
 import jakarta.persistence.Index;
@@ -26,6 +25,7 @@
 
 import static java.util.Collections.emptyMap;
 import static java.util.Collections.unmodifiableMap;
+import static org.hibernate.internal.util.collections.CollectionHelper.isEmpty;
 
 /**
  * Models the definition of an {@linkplain org.hibernate.id.IdentityGenerator identifier generator}
@@ -47,7 +47,7 @@ public IdentifierGeneratorDefinition(
 			final Map<String, String> parameters) {
 		this.name = name;
 		this.strategy = strategy;
-		this.parameters = CollectionHelper.isEmpty( parameters ) ? emptyMap() : unmodifiableMap( parameters );
+		this.parameters = isEmpty( parameters ) ? emptyMap() : unmodifiableMap( parameters );
 	}
 
 	public IdentifierGeneratorDefinition(

hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java

@@ -23,6 +23,9 @@
 import org.hibernate.jpa.SpecHints;
 import org.hibernate.query.spi.QueryPlan;
 import org.hibernate.query.sqm.NullPrecedence;
+import org.hibernate.query.sqm.mutation.internal.temptable.GlobalTemporaryTableStrategy;
+import org.hibernate.query.sqm.mutation.internal.temptable.LocalTemporaryTableStrategy;
+import org.hibernate.query.sqm.mutation.internal.temptable.PersistentTableStrategy;
 import org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode;
 import org.hibernate.resource.jdbc.spi.StatementInspector;
 
@@ -41,6 +44,11 @@
  *     <li>via {@link Configuration#setProperty(String, String)}, or
  *     <li>via {@link org.hibernate.boot.registry.StandardServiceRegistryBuilder#applySetting(String, Object)}.
  * </ul>
+ * <p>
+ * Note that Hibernate does not distinguish between JPA-defined configuration
+ * properties and "native" configuration properties. Any property listed here
+ * may be used to configure Hibernate no matter what configuration mechanism
+ * or bootstrap API is used.
  *
  * @author Steve Ebersole
  */
@@ -894,6 +902,7 @@ public interface AvailableSettings {
 	 *
 	 * @deprecated {@code hbm.xml} mappings are no longer supported, making this attribute irrelevant
 	 */
+	@SuppressWarnings("DeprecatedIsStillUsed")
 	@Deprecated(since = "6", forRemoval = true)
 	String ARTIFACT_PROCESSING_ORDER = "hibernate.mapping.precedence";
 
@@ -1159,6 +1168,7 @@ public interface AvailableSettings {
 	 * @deprecated Will be removed without replacement. See HHH-15631
 	 */
 	@Deprecated(forRemoval = true)
+	@SuppressWarnings("DeprecatedIsStillUsed")
 	String USE_REFLECTION_OPTIMIZER = "hibernate.bytecode.use_reflection_optimizer";
 
 	/**
@@ -1408,6 +1418,7 @@ public interface AvailableSettings {
 	 * @deprecated this is only honored for {@code hibernate-infinispan}
 	 */
 	@Deprecated
+	@SuppressWarnings("DeprecatedIsStillUsed")
 	String CACHE_KEYS_FACTORY = "hibernate.cache.keys_factory";
 
 	/**
@@ -1685,10 +1696,10 @@ public interface AvailableSettings {
 	 * For cases where the {@value #HBM2DDL_SCRIPTS_ACTION} value indicates that schema commands
 	 * should be written to DDL script file, specifies if schema commands should be appended to
 	 * the end of the file rather than written at the beginning of the file.
-	 *
+	 * <p>
 	 * Values are: {@code true} for appending schema commands to the end of the file, {@code false}
 	 * for writing schema commands at the beginning.
-	 *
+	 * <p>
 	 * The default value is {@code true}
 	 */
 	String HBM2DDL_SCRIPTS_CREATE_APPEND = "hibernate.hbm2ddl.schema-generation.script.append";
@@ -2467,6 +2478,7 @@ public interface AvailableSettings {
 	 * no {@code @OrderColumn}.
 	 */
 	@Deprecated( since = "6.0" )
+	@SuppressWarnings("DeprecatedIsStillUsed")
 	String JPA_LIST_COMPLIANCE	= "hibernate.jpa.compliance.list";
 
 	/**
@@ -3091,13 +3103,15 @@ public interface AvailableSettings {
 	 * @deprecated Will be removed without replacement. See HHH-15641
 	 */
 	@Deprecated(forRemoval = true)
+	@SuppressWarnings("DeprecatedIsStillUsed")
 	String ENHANCER_ENABLE_DIRTY_TRACKING = "hibernate.enhancer.enableDirtyTracking";
 
 	/**
 	 * Enable lazy loading feature in runtime bytecode enhancement
 	 *
 	 * @deprecated Will be removed without replacement. See HHH-15641
 	 */
+	@SuppressWarnings("DeprecatedIsStillUsed")
 	@Deprecated(forRemoval = true)
 	String ENHANCER_ENABLE_LAZY_INITIALIZATION = "hibernate.enhancer.enableLazyInitialization";
 
@@ -3148,20 +3162,47 @@ public interface AvailableSettings {
 	String VALIDATE_XML = "hibernate.validate_xml";
 
 	/**
-	 * Enables processing `hbm.xml` mappings by transforming them to `mapping.xml` and using
+	 * Enables processing {@code hbm.xml} mappings by transforming them to {@code mapping.xml} and using
 	 * that processor.  Default is false, must be opted-into.
 	 *
 	 * @since 6.1
 	 */
 	String TRANSFORM_HBM_XML = "hibernate.transform_hbm_xml.enabled";
 
 	/**
-	 * How features in a `hbm.xml` file which are not supported for transformation should be handled.
+	 * How features in a {@code hbm.xml} file which are not supported for transformation should be handled.
 	 * <p>
 	 * Default is {@link org.hibernate.boot.jaxb.hbm.transform.UnsupportedFeatureHandling#ERROR}
 	 *
 	 * @see org.hibernate.boot.jaxb.hbm.transform.UnsupportedFeatureHandling
 	 * @since 6.1
 	 */
 	String TRANSFORM_HBM_XML_FEATURE_HANDLING = "hibernate.transform_hbm_xml.unsupported_feature_handling";
+
+	/**
+	 * Allows creation of {@linkplain org.hibernate.dialect.temptable.TemporaryTableKind#PERSISTENT persistent}
+	 * temporary tables at application startup to be disabled. By default, table creation is enabled.
+	 */
+	String BULK_ID_STRATEGY_PERSISTENT_TEMPORARY_CREATE_TABLES = PersistentTableStrategy.CREATE_ID_TABLES;
+	/**
+	 * Allows dropping of {@linkplain org.hibernate.dialect.temptable.TemporaryTableKind#PERSISTENT persistent}
+	 * temporary tables at application shutdown to be disabled. By default, table dropping is enabled.
+	 */
+	String BULK_ID_STRATEGY_PERSISTENT_TEMPORARY_DROP_TABLES = PersistentTableStrategy.DROP_ID_TABLES;
+	/**
+	 * Allows creation of {@linkplain org.hibernate.dialect.temptable.TemporaryTableKind#GLOBAL global}
+	 * temporary tables at application startup to be disabled. By default, table creation is enabled.
+	 */
+	String BULK_ID_STRATEGY_GLOBAL_TEMPORARY_CREATE_TABLES = GlobalTemporaryTableStrategy.CREATE_ID_TABLES;
+	/**
+	 * Allows dropping of {@linkplain org.hibernate.dialect.temptable.TemporaryTableKind#GLOBAL global}
+	 * temporary tables at application shutdown to be disabled. By default, table dropping is enabled.
+	 */
+	String BULK_ID_STRATEGY_GLOBAL_TEMPORARY_DROP_TABLES = GlobalTemporaryTableStrategy.DROP_ID_TABLES;
+	/**
+	 * Allows dropping of {@linkplain org.hibernate.dialect.temptable.TemporaryTableKind#LOCAL local}
+	 * temporary tables at transaction commit to be enabled. By default, table dropping is disabled,
+	 * and the database will drop the temporary tables automatically.
+	 */
+	String BULK_ID_STRATEGY_LOCAL_TEMPORARY_DROP_TABLES = LocalTemporaryTableStrategy.DROP_ID_TABLES;
 }