more about table mappings

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 <<mapping-entity-classes>>:
 
+.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
 

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
 

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

@@ -32,7 +32,7 @@ In <<entity-inheritance>> 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 <<primary-key-column-mappings,primary key column mappings>>
+| `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`&mdash;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&mdash;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