Merge branch 'hibernate:main' into HHH-18855

Author: leonschenk

documentation/src/main/asciidoc/introduction/Entities.adoc

@@ -656,10 +656,20 @@ But in the country I was born, `SUNDAY` is the _first_ day of the week!
 So we prefer `@Enumerated(STRING)` for most `enum` attributes.
 ====
 
-An interesting special case is PostgreSQL.
-Postgres supports _named_ `ENUM` types, which must be declared using a DDL `CREATE TYPE` statement.
-Sadly, these `ENUM` types aren't well-integrated with the language nor well-supported by the Postgres JDBC driver, so Hibernate doesn't use them by default.
-But if you would like to use a named enumerated type on Postgres, just annotate your `enum` attribute like this:
+An interesting special case arises on PostgreSQL and Oracle.
+
+[[named-enums]]
+.Named enumerated types
+****
+Some databases support _named_ `ENUM` types, which must be declared using in DDL using:
+
+- `CREATE TYPE ... AS ENUM` on PostgreSQL, or
+- `CREATE DOMAIN ... AS ENUM` on Oracle.
+
+These look like a perfect match for Java ``enum``s, which also have names!
+
+Sadly, these `ENUM` types aren't well-integrated with the SQL language, nor well-supported by the JDBC drivers, so Hibernate doesn't use them by default.
+But if you would like to use a named enumerated type on Postgres or Oracle, just annotate your `enum` attribute like this:
 
 [source,java]
 ----
@@ -668,6 +678,9 @@ But if you would like to use a named enumerated type on Postgres, just annotate
 Status status;
 ----
 
+Alternatively, you may enable the configuration property link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html#PREFER_NATIVE_ENUM_TYPES[`hibernate.type.prefer_native_enum_types`].
+****
+
 The limited set of pre-defined basic attribute types can be stretched a bit further by supplying a _converter_.
 
 [[converters]]
@@ -740,6 +753,7 @@ Hibernate considers a "basic type" to be formed by the marriage of two objects:
 
 When mapping a basic attribute, we may explicitly specify a `JavaType`, a `JdbcType`, or both.
 
+[[java-type]]
 [discrete]
 ==== JavaType
 
@@ -771,6 +785,7 @@ BitSet bitSet;
 
 Alternatively, the `@JavaTypeRegistration` annotation may be used to register `BitSetJavaType` as the default `JavaType` for `BitSet`.
 
+[[jdbc-type]]
 [discrete]
 ==== JdbcType
 
@@ -827,6 +842,82 @@ long currentTimeMillis;
 
 Let's abandon our analogy right here, before we start calling this basic type a "throuple".
 
+[[datetime-types]]
+=== Date and time types, and time zones
+
+Dates and times should always be represented using the types defined in `java.time`.
+
+[WARNING]
+====
+Never use the legacy types `java.sql.Date`, `java.sql.Time`, `java.sql.Timestamp`, or `java.util.Date`.
+At our urging, support for these types has even been https://in.relation.to/2024/04/22/stop-using-date/[officially deprecated in JPA 3.2].
+Eventually, we hope to completely remove support for these types from the JPA spec and from Hibernate.
+====
+
+Some of the types in `java.time` map naturally to an ANSI SQL column type.
+A source of confusion is that some databases still don't follow the ANSI standard naming here.
+Also, as you're probably aware, the `DATE` type on Oracle is not an ANSI SQL `DATE`.
+In fact, Oracle doesn't have `DATE` or `TIME` types--every date or time must be stored as a timestamp.
+
+.Type mappings from `java.time` to ANSI SQL
+|====
+| `java.time` class | ANSI SQL type | MySQL | SQL Server | Oracle
+
+| `LocalDate` | `DATE` | `DATE` | `DATE` | `DATE` 💀
+| `LocalTime` | `TIME` | `TIME` | `TIME` | `TIMESTAMP` 💀
+| `LocalDateTime` | `TIMSTAMP` | `DATETIME` | `DATETIME2` | `TIMESTAMP`
+| `OffsetDateTime`, `ZonedDateTime` | `TIMESTAMP WITH TIME ZONE` | `TIMESTAMP` 🙄 | `DATETIMEOFFSET` | `TIMESTAMP WITH TIME ZONE`
+|====
+
+On the other hand, there are no perfectly natural mappings for `Instant` and `Duration` on must databases.
+By default:
+
+- `Duration` is mapped to a column of type `NUMERIC(21)` holding the length of the duration in nanoseconds, and
+- `Instant` is mapped to a column of type `TIMESTAMP` (`DATETIME` on MySQL).
+
+Fortunately, these mappings can be modified by specifying the `JdbcType`.
+
+For example, if we wanted to store an `Instant` using `TIMESTAMP WITH TIME ZONE` (`TIMESTAMP` on MySQL) instead of `TIMESTAMP`, then we could annotate the field:
+
+[source,java]
+----
+// store the Instant as a TIMESTAMP WITH TIME ZONE, instead of as a TIMESTAMP
+@JdbcTypeCode(SqlTypes.TIMESTAMP_WITH_TIMEZONE)
+Instant instant;
+----
+
+Alternatively, we could set the configuration property `hibernate.type.preferred_instant_jdbc_type`:
+
+
+[source,java]
+----
+// store field of type Instant as TIMESTAMP WITH TIME ZONE, instead of as a TIMESTAMP
+config.setProperty(MappingSettings.PREFERRED_INSTANT_JDBC_TYPE, SqlTypes.TIMESTAMP_WITH_TIMEZONE);
+----
+
+We have worked very hard to make sure that Java date and time types work with consistent and correct semantics across all databases supported by Hibernate.
+In particular, Hibernate is very careful in how it handles time zones.
+
+[WARNING]
+====
+Unfortunately, with the notable exception of Oracle, most SQL databases feature embarrassingly poor support for timezones.
+Even some databases which do supposedly support `TIMESTAMP WITH TIME ZONE` simply covert the datetime to UTC.
+Here, Hibernate is limited by the capabilities of the databases themselves, and so on many databases, time zone information will not, by default, be preserved for an `OffsetDateTime` or `ZonedDateTime`.
+====
+
+[TIP]
+====
+The still-experimental annotation link:{doc-javadoc-url}org/hibernate/annotations/TimeZoneStorage.html[`@TimeZoneStorage`] provides some additional options in case the default behavior falls short.
+//
+// [source,java]
+// ----
+// @TimeZoneStorage(COLUMN)
+// @TimeZoneColumn(name = "event_offset")
+// @Column(name = "event_timestamp")
+// private OffsetDateTime eventDateTime;
+// ----
+====
+
 [[embeddable-objects]]
 === Embeddable objects
 

documentation/src/main/asciidoc/introduction/Mapping.adoc

@@ -734,6 +734,7 @@ Of course, the behavior here depends very much on the JDBC driver, and so we rea
 
 There's a couple of alternative ways to represent an embeddable type on the database side.
 
+[[embeddable-udt]]
 [discrete]
 ==== Embeddables as UDTs
 
@@ -818,32 +819,34 @@ Here we summarize the ones we've just seen in the second half of this chapter, a
 |===
 | Annotation | Interpretation
 
-| `@Enumerated`, `@EnumeratedValue` | Specify how an `enum` type should be persisted
-| `@Nationalized` | Use a nationalized character type: `NCHAR`, `NVARCHAR`, or `NCLOB`
-| `@Lob` 💀 | Use JDBC LOB APIs to read and write the annotated attribute
-| `@Array` | Map a collection to a SQL `ARRAY` type of the specified length
-| `@Struct` | Map an embeddable to a SQL UDT with the given name
-| `@TimeZoneStorage` | Specify how the time zone information should be persisted
-| `@JdbcType` or `@JdbcTypeCode` | Use an implementation of `JdbcType` to map an arbitrary SQL type
+| `@Enumerated`, `@EnumeratedValue` | Specify how an <<enums,`enum` type should be persisted>>
+| `@Nationalized` | Use a <<nationalized-chars,nationalized character type>>: `NCHAR`, `NVARCHAR`, or `NCLOB`
+| `@Lob` 💀 | Use <<lobs,JDBC LOB APIs>> to read and write the annotated attribute
+| `@Array` | Map a collection to a <<arrays,SQL `ARRAY` type>> of the specified length
+| `@Struct` | Map an <<embeddable-udt,embeddable to a SQL UDT>> with the given name
+| `@TimeZoneStorage` | Specify how the link:{doc-javadoc-url}org/hibernate/annotations/TimeZoneStorageType.html[time zone information should be persisted]
+| `@JdbcType` or `@JdbcTypeCode` | Use an implementation of <<jdbc-type,`JdbcType`>> to map an arbitrary SQL type
 | `@Collate` | Specify a collation for a column
 |===
 
-In addition, there are some configuration properties which have a _global_ affect on how basic types map to SQL column types:
+In addition, there are link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html[some configuration properties] which have a _global_ effect on how basic types map to SQL column types:
 
 .Type mapping settings
 [%autowidth.stretch]
 |===
 | Configuration property name | Purpose
 
-| `hibernate.use_nationalized_character_data` | Enable use of nationalized character types by default
-| `hibernate.type.preferred_boolean_jdbc_type` | Specify the default SQL column type for mapping `boolean`
-| `hibernate.type.preferred_uuid_jdbc_type` | Specify the default SQL column type for mapping `UUID`
-| `hibernate.type.preferred_duration_jdbc_type` | Specify the default SQL column type for mapping `Duration`
-| `hibernate.type.preferred_instant_jdbc_type` | Specify the default SQL column type for mapping `Instant`
-| `hibernate.timezone.default_storage` | Specify the default strategy for storing time zone information
-| `` |
+| `hibernate.use_nationalized_character_data` | Enable use of <<nationalized-chars,nationalized character types>> by default
+| `hibernate.type.preferred_boolean_jdbc_type` | Specify the default SQL column type for storing a `boolean`
+| `hibernate.type.preferred_uuid_jdbc_type` | Specify the default SQL column type for storing a `UUID`
+| `hibernate.type.preferred_duration_jdbc_type` | Specify the default SQL column type for storing a `Duration`
+| `hibernate.type.preferred_instant_jdbc_type` | Specify the default SQL column type for storing an `Instant`
+| `hibernate.timezone.default_storage` | Specify the default strategy for link:{doc-javadoc-url}org/hibernate/annotations/TimeZoneStorageType.html[storing time zone information]
+| `hibernate.type.prefer_native_enum_types` | Use <<named-enums,named enum types>> on PostgreSQL and Oracle
 |===
 
+Earlier, we saw how to use these settings to control the default mappings for <<datetime-types,`Instant` and `Duration`>>.
+
 [TIP]
 ====
 These are _global_ settings and thus quite clumsy.
@@ -863,7 +866,7 @@ Thus, the attribute is a sort of "derived" value.
 |===
 | Annotation | Purpose
 
-| `@Formula` | Map an attribute to a SQL formula
+| link:{doc-javadoc-url}org/hibernate/annotations/Formula.html[`@Formula`] | Map an attribute to a SQL formula
 | `@JoinFormula` | Map an association to a SQL formula
 | `@DiscriminatorFormula` | Use a SQL formula as the discriminator in <<mapping-inheritance,single table inheritance>>.
 |===
@@ -887,6 +890,8 @@ class Order {
 }
 ----
 
+The formula is evaluated every time the entity is read from the database.
+
 [[derived-identity]]
 === Derived Identity
 

documentation/src/main/asciidoc/querylanguage/Expressions.adoc

@@ -941,6 +941,7 @@ Its BNF is given by:
 "PAD" "(" expression "WITH" expression ("LEADING" | "TRAILING") padCharacter? ")"
 ----
 
+[[collations]]
 [discrete]
 ===== Collations
 

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

@@ -210,7 +210,7 @@ public class SessionFactoryOptionsBuilder implements SessionFactoryOptions {
 	private boolean orderUpdatesEnabled;
 	private boolean orderInsertsEnabled;
 	private boolean collectionsInDefaultFetchGroupEnabled = true;
-	private final boolean UnownedAssociationTransientCheck;
+	private final boolean unownedAssociationTransientCheck;
 	private final boolean passProcedureParameterNames;
 	private final boolean preferJdbcDatetimeTypes;
 
@@ -597,14 +597,14 @@ else if ( defaultNullPrecedence != null ) {
 				JDBC_TIME_ZONE
 		);
 
-		if ( jdbcTimeZoneValue instanceof TimeZone ) {
-			this.jdbcTimeZone = (TimeZone) jdbcTimeZoneValue;
+		if ( jdbcTimeZoneValue instanceof TimeZone timeZone ) {
+			this.jdbcTimeZone = timeZone;
 		}
-		else if ( jdbcTimeZoneValue instanceof ZoneId ) {
-			this.jdbcTimeZone = TimeZone.getTimeZone( (ZoneId) jdbcTimeZoneValue );
+		else if ( jdbcTimeZoneValue instanceof ZoneId zoneId ) {
+			this.jdbcTimeZone = TimeZone.getTimeZone( zoneId );
 		}
-		else if ( jdbcTimeZoneValue instanceof String ) {
-			this.jdbcTimeZone = TimeZone.getTimeZone( ZoneId.of((String) jdbcTimeZoneValue) );
+		else if ( jdbcTimeZoneValue instanceof String string ) {
+			this.jdbcTimeZone = TimeZone.getTimeZone( ZoneId.of( string ) );
 		}
 		else if ( jdbcTimeZoneValue != null ) {
 			throw new IllegalArgumentException( "Configuration property " + JDBC_TIME_ZONE
@@ -665,7 +665,7 @@ else if ( jdbcTimeZoneValue != null ) {
 				Statistics.DEFAULT_QUERY_STATISTICS_MAX_SIZE
 		);
 
-		this.UnownedAssociationTransientCheck = getBoolean(
+		this.unownedAssociationTransientCheck = getBoolean(
 				UNOWNED_ASSOCIATION_TRANSIENT_CHECK,
 				configurationSettings,
 				isJpaBootstrap()
@@ -1305,7 +1305,7 @@ public boolean isCollectionsInDefaultFetchGroupEnabled() {
 
 	@Override
 	public boolean isUnownedAssociationTransientCheck() {
-		return UnownedAssociationTransientCheck;
+		return unownedAssociationTransientCheck;
 	}
 
 	@Override

hibernate-core/src/main/java/org/hibernate/boot/model/internal/EntityBinder.java

@@ -94,6 +94,7 @@
 import org.hibernate.mapping.SimpleValue;
 import org.hibernate.mapping.SingleTableSubclass;
 import org.hibernate.mapping.Subclass;
+import org.hibernate.mapping.SyntheticProperty;
 import org.hibernate.mapping.Table;
 import org.hibernate.mapping.TableOwner;
 import org.hibernate.mapping.UnionSubclass;
@@ -566,7 +567,7 @@ private Component createMapperProperty(
 				propertyAccessor,
 				isIdClass
 		);
-		final Property mapperProperty = new Property();
+		final Property mapperProperty = new SyntheticProperty();
 		mapperProperty.setName( NavigablePath.IDENTIFIER_MAPPER_PROPERTY );
 		mapperProperty.setUpdateable( false );
 		mapperProperty.setInsertable( false );