From 439c90f5015462f34069221979def9e30784aebf Mon Sep 17 00:00:00 2001 From: Gavin King Date: Sat, 16 Nov 2024 10:52:26 +0100 Subject: [PATCH] add links between chapters --- .../main/asciidoc/introduction/Entities.adoc | 23 ++++++++++--- .../main/asciidoc/introduction/Mapping.adoc | 34 ++++++++++--------- .../asciidoc/querylanguage/Expressions.adoc | 1 + .../org/hibernate/cfg/MappingSettings.java | 3 ++ 4 files changed, 41 insertions(+), 20 deletions(-) diff --git a/documentation/src/main/asciidoc/introduction/Entities.adoc b/documentation/src/main/asciidoc/introduction/Entities.adoc index 241165a822..052d1f239d 100644 --- a/documentation/src/main/asciidoc/introduction/Entities.adoc +++ b/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 diff --git a/documentation/src/main/asciidoc/introduction/Mapping.adoc b/documentation/src/main/asciidoc/introduction/Mapping.adoc index ffc6d70140..e76cf11128 100644 --- a/documentation/src/main/asciidoc/introduction/Mapping.adoc +++ b/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,33 @@ 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 <> +| `@Nationalized` | Use a <>: `NCHAR`, `NVARCHAR`, or `NCLOB` +| `@Lob` 💀 | Use <> to read and write the annotated attribute +| `@Array` | Map a collection to a <> of the specified length +| `@Struct` | Map an <> 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 <> to map an arbitrary SQL type | `@Collate` | Specify a collation for a column |=== -In addition, there are link:{doc-javadoc-url}org/hibernate/cfg/MappingSettings.html[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 <> 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 <> on PostgreSQL and Oracle |=== -For example, if we wanted to store an `Instant` using `timestamp with time zone` (called `timestamp` on MySQL, and `datetimeoffset` on SQL Server) instead of `timestamp` (`datetime` on MySQL, `datetime2` on SQL Server), then we could annotated every field of type `Instant`: +For example, if we wanted to store an `Instant` using `timestamp with time zone` (called `timestamp` on MySQL, and `datetimeoffset` on SQL Server) instead of `timestamp` (`datetime` on MySQL, `datetime2` on SQL Server), then we could annotate every field of type `Instant`: [source,java] ---- @@ -851,7 +853,7 @@ For example, if we wanted to store an `Instant` using `timestamp with time zone` Instant instant; ---- -Alternatively, we could affect every field of type `Instant` with the property `hibernate.type.preferred_instant_jdbc_type`: +Alternatively, we could set the property `hibernate.type.preferred_instant_jdbc_type`: [source,java] diff --git a/documentation/src/main/asciidoc/querylanguage/Expressions.adoc b/documentation/src/main/asciidoc/querylanguage/Expressions.adoc index 0cc495010f..77b1d01722 100644 --- a/documentation/src/main/asciidoc/querylanguage/Expressions.adoc +++ b/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 diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/MappingSettings.java b/hibernate-core/src/main/java/org/hibernate/cfg/MappingSettings.java index c71af86276..fd9c78b741 100644 --- a/hibernate-core/src/main/java/org/hibernate/cfg/MappingSettings.java +++ b/hibernate-core/src/main/java/org/hibernate/cfg/MappingSettings.java @@ -279,6 +279,9 @@ public interface MappingSettings { * * @settingDefault {@link Dialect#getPreferredSqlTypeCodeForArray()}. * + * @see org.hibernate.type.SqlTypes#ARRAY + * @see org.hibernate.type.SqlTypes#TABLE + * * @since 6.6 */ @Incubating