From e1160fec9164f50060a4f23b0a8cc2b9f9cf98d5 Mon Sep 17 00:00:00 2001 From: Gavin Date: Wed, 10 May 2023 23:45:17 +0200 Subject: [PATCH] more about table mappings --- .../asciidoc/introduction/Configuration.adoc | 8 +++ .../main/asciidoc/introduction/Entities.adoc | 2 + .../main/asciidoc/introduction/Mapping.adoc | 49 +++++++++++++++++-- 3 files changed, 56 insertions(+), 3 deletions(-) diff --git a/documentation/src/main/asciidoc/introduction/Configuration.adoc b/documentation/src/main/asciidoc/introduction/Configuration.adoc index 3d8669d9de..902804d8a9 100644 --- a/documentation/src/main/asciidoc/introduction/Configuration.adoc +++ b/documentation/src/main/asciidoc/introduction/Configuration.adoc @@ -54,6 +54,7 @@ Where `{version}` is the version of Hibernate you're using. You'll also need to add a dependency for the JDBC driver for your database. +.JDBC driver dependencies |=== | Database | Driver dependency @@ -77,6 +78,7 @@ Where `{version}` is the latest version of the JDBC driver for your databse. Optionally, you might also add any of the following additional features: +.Optional dependencies |=== | Optional feature | Dependencies @@ -223,6 +225,7 @@ With rare exception, the default behavior of every one of these settings was car The properties you really do need to get started are these three: +.JDBC connection settings |=== | Configuration property name | Purpose @@ -251,6 +254,7 @@ This pool is not meant for use in production, and later, when we discuss perform Alternatively, in a container environment, you'll need at least one of these properties: +.Transaction management settings |=== | Configuration property name | Purpose @@ -271,6 +275,7 @@ annotations you've specified in your Java code, and export the schema at initialization time by specifying one or more of the following configuration properties: +.Schema management settings [cols="1,1"] |=== | Configuration property name | Purpose @@ -333,6 +338,7 @@ logger.hibernate.level = debug You can make the logged SQL more readable by enabling one or both of the following settings: +.Setting for SQL logging to the console |=== | Configuration property name | Purpose @@ -346,6 +352,7 @@ These settings can really help when troubleshooting SQL. The following properties are very useful for minimizing the amount of information you'll need to explicitly specify in `@Table` and `@Column` annotations, which we'll discuss below in <>: +.Settings for minimizing explicit mapping information |=== | Configuration property name | Purpose @@ -369,6 +376,7 @@ Please refer to the Javadoc for these interfaces for more information about the _By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode data. So, if you're working with SQL Server, you might need to force Hibernate to use the `nchar` and `nvarchar` types. +.Setting the use of nationalized charcter data |=== | Configuration property name | Purpose diff --git a/documentation/src/main/asciidoc/introduction/Entities.adoc b/documentation/src/main/asciidoc/introduction/Entities.adoc index 50cf8cca62..ec736dd912 100644 --- a/documentation/src/main/asciidoc/introduction/Entities.adoc +++ b/documentation/src/main/asciidoc/introduction/Entities.adoc @@ -207,6 +207,7 @@ On the other hand, if, as is more common, you're working with a pre-existing dat JPA defines the following strategies for generating ids, which are enumerated by `GenerationType`: +.Standard id generation strategies |=== | Strategy | Java type | Implementation @@ -445,6 +446,7 @@ The `@Id` and `@Version` attributes we've already seen are just specialized exam A _basic_ attribute of an entity is a field or property which maps to a single column of the associated database table. The JPA specification defines a quite limited set of basic types: +.JPA-standard basic attribute types |==== | Classification | Package | Types diff --git a/documentation/src/main/asciidoc/introduction/Mapping.adoc b/documentation/src/main/asciidoc/introduction/Mapping.adoc index c0e50edfee..795899da5a 100644 --- a/documentation/src/main/asciidoc/introduction/Mapping.adoc +++ b/documentation/src/main/asciidoc/introduction/Mapping.adoc @@ -32,7 +32,7 @@ In <> we saw that entity classes may exist within an inherit There's three basic strategies for mapping an entity hierarchy to relational tables. Let's put them in a table, so we can more easily compare the points of difference between them. - +.Entity inheritance mapping strategies |=== | Strategy | Mapping | Polymorphic queries | Constraints | Normalization | When to use it @@ -155,6 +155,7 @@ is a bad idea, since it's impossible to create a foreign key constraint that tar The following annotations specify exactly how elements of the domain model map to tables of the relational model: +.Annotations for mapping tables |=== | Annotation | Purpose @@ -183,11 +184,50 @@ However, the `@SecondaryTable` annotation allows us to spread its attributes acr class Book { ... } ---- +The `@Table` annotation can do more than just specify a name: + +.`@Table` annotation members +|=== +| Annotation member | Purpose + +| `name` | The name of the mapped table +| `schema` 💀 | The schema to which the table belongs +| `catalog` 💀 | The catalog to which the table belongs +| `uniqueConstraints` | One or more `@UniqueConstraint` annotations declaring multi-column unique constraints +| `indexes` | One or more `@Index` annotations each declaring an index +|=== + +[TIP] +.Don't hardcode the schema and catalog +==== +It's very often a bad idea to hardcode the schema and catalog in a `@Table` annotation. +It's usually better to set the configuration properties `hibernate.default_schema` and `hibernate.default_catalog`, or simply ensure that your JDBC connection URL specifies the schema and catalog. +==== + + +The `@SecondaryTable` annotation is even more interesting: + +.`@SecondaryTable` annotation members +|=== +| Annotation member | Purpose + +| `name` | The name of the mapped table +| `schema` 💀 | The schema to which the table belongs +| `catalog` 💀 | The catalog to which the table belongs +| `uniqueConstraints` | One or more `@UniqueConstraint` annotations declaring multi-column unique constraints +| `indexes` | One or more `@Index` annotations each declaring an index +| `pkJoinColumns` | One or more `@PrimaryKeyJoinColumn` annotations, specifying <> +| `foreignKey` | An `@ForeignKey` annotation specifying the name of the `FOREIGN KEY` constraint on the ``@PrimaryKeyJoinColumn``s +|=== + +To understand this annotation better, we must first discuss column mappings in general. + [[column-mappings]] === Mapping to columns These annotations specify how elements of the domain model map to columns of tables in the relational model: +.Annotations for mapping columns |=== | Annotation | Purpose @@ -205,6 +245,7 @@ We use the `@Column` annotation to map basic attributes. The `@Column` annotation is not only useful for specifying the column name. +.`@Column` annotation members |=== | Annotation member | Purpose @@ -257,6 +298,7 @@ We don't use `@Column` to map associations. The `@JoinColumn` annotation is used to customize a foreign key column. +.`@JoinColumn` annotation members |=== | Annotation member | Purpose @@ -303,6 +345,7 @@ The `@PrimaryKeyJoinColumn` is a special-purpose annotation for mapping: - the primary key column of a `@SecondaryTable`—which is also a foreign key referencing the primary table, or - the primary key column of the primary table mapped by a subclass in a `JOINED` inheritance hierarchy—which is also a foreign key referencing the primary table mapped by the root entity. +.`@PrimaryKeyJoinColumn` annotation members |=== | Annotation member | Purpose @@ -323,7 +366,7 @@ class Person { ... } @Entity @Table(name="Authors") -@PrimaryKeyJoinColumn(name="personId") // the name of the primary key of the Authors table +@PrimaryKeyJoinColumn(name="personId") // the primary key of the Authors table class Author { ... } ---- @@ -334,7 +377,7 @@ But to map a secondary table primary key, the `@PrimaryKeyJoinColumn` annotation @Entity @Table(name="Books") @SecondaryTable(name="Editions", - pkJoinColumns = @PrimaryKeyJoinColumn(name="bookId")) // the name of the primary key of the Editions table + pkJoinColumns = @PrimaryKeyJoinColumn(name="bookId")) // the primary key of the Editions table class Book { @Id @GeneratedValue @Column(name="bookId") // the name of the primary key of the Books table