prevent orphaned table titles

split a section

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

@@ -178,7 +178,7 @@ Native SQL queries are _not_ automatically filtered by tenant id; you'll have to
 ====
 
 .Multi-tenancy configuration
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name           | Purpose
 
@@ -316,7 +316,7 @@ However, the older APIs are still available and custom ``IdentifierGenerator``s
 Hibernate has a range of built-in generators which are defined in terms of this new framework.
 
 .Built-in generators
-[cols="20,25,~"]
+[%breakable,cols="20,25,~"]
 |===
 | Annotation | Implementation | Purpose
 
@@ -433,7 +433,7 @@ A popular `PhysicalNamingStrategy` produces snake case identifiers.
 Custom naming strategies may be enabled using the configuration properties we already mentioned without much explanation back in <<minimizing>>.
 
 .Naming strategy configuration
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name           | Purpose
 

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

@@ -6,7 +6,7 @@ Unfortunately, there's several distinct ways to configure and bootstrap Hibernat
 
 The four basic ways to obtain an instance of Hibernate are shown in the following table:
 
-[cols="50,50"]
+[%breakable,cols="50,50"]
 |===
 
 | Using the standard JPA-defined XML, and the operation `Persistence.createEntityManagerFactory()`
@@ -57,7 +57,7 @@ You'll also need to add a dependency for the JDBC
 driver for your database.
 
 .JDBC driver dependencies
-[cols="50,~"]
+[%breakable,cols="50,~"]
 |===
 | Database                  | Driver dependency
 
@@ -90,7 +90,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
-[cols="50,~"]
+[%breakable,cols="50,~"]
 |===
 | Optional feature | Dependencies
 
@@ -272,7 +272,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
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name | Purpose
 
@@ -294,7 +294,7 @@ Pooling JDBC connections is an extremely important performance optimization.
 You can set the size of Hibernate's built-in connection pool using this property:
 
 .Built-in connection pool size
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name | Purpose
 
@@ -311,7 +311,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
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name            | Purpose
 
@@ -333,7 +333,7 @@ initialization time by specifying one or more of the following configuration
 properties:
 
 .Schema management settings
-[cols="52,~"]
+[%breakable,cols="52,~"]
 |===
 | Configuration property name                                | Purpose
 
@@ -387,7 +387,7 @@ You can make the output much more readable by enabling formatting or highlightin
 These settings really help when troubleshooting the generated SQL statements.
 
 .Settings for SQL logging to the console
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name | Purpose
 
@@ -423,7 +423,7 @@ But with this approach we miss out on the pretty highlighting.
 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 <<object-relational-mapping>>:
 
 .Settings for minimizing explicit mapping information
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name           | Purpose
 
@@ -446,7 +446,7 @@ We'll have more to say about them in <<naming-strategies>>.
 _By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode data. But a Java string may contain any Unicode character. So, if you're working with SQL Server, you might need to force Hibernate to use the `nchar` and `nvarchar` column types.
 
 .Setting the use of nationalized character data
-[cols="40,~"]
+[%breakable,cols="40,~"]
 |===
 | Configuration property name                 | Purpose
 

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

@@ -228,7 +228,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
-[cols="25,15,~"]
+[%breakable,cols="25,15,~"]
 |===
 | Strategy                  | Java type | Implementation
 
@@ -512,7 +512,7 @@ Hibernate automatically generates a `UNIQUE` constraint on the columns mapped by
 Consider using the natural id attributes to implement <<equals-and-hash>>.
 ====
 
-The payoff for doing this extra work, as we will see <<enable-second-level-cache,much later>>, is that we can take advantage of optimized natural id lookups that make use of the second-level cache.
+The payoff for doing this extra work, as we will see <<natural-id-cache,much later>>, is that we can take advantage of optimized natural id lookups that make use of the second-level cache.
 
 Note that even when you've identified a natural key, we still recommend the use of a generated surrogate key in foreign keys, since this makes your data model _much_ easier to change.
 
@@ -523,7 +523,7 @@ A _basic_ attribute of an entity is a field or property which maps to a single c
 The JPA specification defines a quite limited set of basic types:
 
 .JPA-standard basic attribute types
-[cols="30,^14,~"]
+[%breakable,cols="30,^14,~"]
 |====
 | Classification | Package | Types
 
@@ -556,7 +556,7 @@ As we'll soon see in <<embeddable-objects>>, Hibernate has much better ways to h
 Hibernate slightly extends this list with the following types:
 
 .Additional basic attribute types in Hibernate
-[cols="30,^14,56"]
+[%breakable,cols="30,^14,56"]
 |====
 | Classification | Package | Types
 
@@ -949,7 +949,7 @@ There are three annotations for mapping associations: `@ManyToOne`, `@OneToMany`
 They share some common annotation members:
 
 .Association-defining annotation members
-[cols="13,~,35"]
+[%breakable,cols="13,~,35"]
 |===
 | Member | Interpretation | Default value
 
@@ -1251,7 +1251,7 @@ That is, the collection is a _bag_, not a set.
 
 We've now seen the following kinds of entity attribute:
 
-[cols="32,^15,^15,~"]
+[%breakable,cols="32,^15,^15,~"]
 |===
 | Kind of entity attribute | Kind of reference | Multiplicity | Examples
 
@@ -1281,7 +1281,7 @@ And the answer again is that _it does_. Indeed, there are two different ways to
 
 So we may expand our taxonomy with:
 
-[cols="32,^15,^15,~"]
+[%breakable,cols="32,^15,^15,~"]
 |===
 | Kind of entity attribute | Kind of reference | Multiplicity | Examples
 
@@ -1419,7 +1419,7 @@ There's much more we could say about "element collections", but we won't say it,
 Let's pause to remember the annotations we've met so far.
 
 .Declaring entities and embeddable types
-[cols="22,~,^13"]
+[%breakable,cols="22,~,^13"]
 |===
 | Annotation | Purpose | JPA-standard
 
@@ -1430,7 +1430,7 @@ Let's pause to remember the annotations we've met so far.
 |===
 
 .Declaring basic attributes
-[cols="22,~,^10,^13"]
+[%breakable,cols="22,~,^10,^13"]
 |===
 | Annotation | Purpose | | JPA-standard
 
@@ -1445,7 +1445,7 @@ Let's pause to remember the annotations we've met so far.
 |===
 
 .Converters and compositional basic types
-[cols="22,~,^13"]
+[%breakable,cols="22,~,^13"]
 |===
 | Annotation | Purpose | JPA-standard
 
@@ -1459,7 +1459,7 @@ Let's pause to remember the annotations we've met so far.
 |===
 
 .System-generated identifiers
-[cols="22,~,^13"]
+[%breakable,cols="22,~,^13"]
 |===
 | Annotation | Purpose | JPA-standard
 
@@ -1471,7 +1471,7 @@ Let's pause to remember the annotations we've met so far.
 |===
 
 .Declaring entity associations
-[cols="22,~,^13"]
+[%breakable,cols="22,~,^13"]
 |===
 | Annotation | Purpose | JPA-standard
 

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

@@ -214,7 +214,7 @@ Of course, the main reason we need an `EntityManager` is to do stuff to the data
 The following important operations let us interact with the persistence context and schedule modifications to the data:
 
 .Methods for modifying data and managing the persistence context
-[cols="30,~"]
+[%breakable,cols="30,~"]
 |===
 | Method name and parameters | Effect
 
@@ -241,7 +241,7 @@ Modifications are automatically detected when the session is <<flush,flushed>>.
 On the other hand, the following operations all result in immediate access to the database:
 
 .Methods for reading and locking data
-[cols="30,~"]
+[%breakable,cols="30,~"]
 |===
 | Method name and parameters | Effect
 
@@ -491,7 +491,7 @@ session.setHibernateFlushMode(FlushMode.MANUAL);
 Since flushing is a somewhat expensive operation (the session must dirty-check every entity in the persistence context), setting the flush mode to `COMMIT` can occasionally be a useful optimization.
 
 .Flush modes
-[cols="15,15,~"]
+[%breakable,cols="15,15,~"]
 |===
 | Hibernate `FlushMode` | JPA `FlushModeType` | Interpretation
 
@@ -538,7 +538,7 @@ The method we call depends on what Kind it is:
 Selection queries usually start with the keyword `select` or `from`, whereas mutation queries begin with the keyword `insert`, `update`, or `delete`.
 
 .Executing HQL
-[cols="10,36,32,22"]
+[%breakable,cols="10,36,32,22"]
 |===
 | Kind | `Session` method | `EntityManager` method | `Query` execution method
 
@@ -717,7 +717,7 @@ If you change the default behavior, and set the property to `INLINE` instead of
 Execution of a criteria query works almost exactly like execution of HQL.
 
 .Executing criteria queries
-[cols="10,36,32,22"]
+[%breakable,cols="10,36,32,22"]
 |===
 | Kind | `Session` method | `EntityManager` method | `Query` execution method
 
@@ -744,7 +744,7 @@ But ultimately, the true value of ORM is not in avoiding SQL, but in alleviating
 As we said <<introduction,right up front>>, Hibernate's generated SQL is meant to be used in conjunction with handwritten SQL, and native SQL queries are one of the facilities we provide to make that easy.
 
 .Executing SQL
-[cols="10,36,32,22"]
+[%breakable,cols="10,36,32,22"]
 |===
 | Kind | `Session` method | `EntityManager` method | `Query` execution method
 
@@ -908,7 +908,7 @@ The `@NamedNativeQuery` annotation lets us do the same for native SQL queries.
 There's much less advantage to using `@NamedNativeQuery`, because there is very little that Hibernate can do to validate the correctness of a query written in the native SQL dialect of your database.
 
 .Executing named queries
-[cols="10,36,32,22"]
+[%breakable,cols="10,36,32,22"]
 |===
 | Kind | `Session` method | `EntityManager` method | `Query` execution method
 
@@ -941,7 +941,7 @@ But as we also <<entity-graph,already saw>>, it can't quite do everything.
 Therefore, Hibernate has some APIs that streamline certain more complicated lookups:
 
 .Operations for lookup by id
-[cols="30,~"]
+[%breakable,cols="30,~"]
 |===
 | Method name | Purpose
 
@@ -969,7 +969,7 @@ If we don't specify the batch size explicitly, a batch size will be chosen autom
 
 We also have some operations for working with lookups by <<natural-identifiers, natural id>>:
 
-[cols="30,~"]
+[%breakable,cols="30,~"]
 |===
 | Method name | Purpose
 

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

@@ -211,7 +211,7 @@ class Book { ... }
 The `@Table` annotation can do more than just specify a name:
 
 .`@Table` annotation members
-[cols="20,~"]
+[%breakable,cols="20,~"]
 |===
 | Annotation member | Purpose
 
@@ -237,7 +237,7 @@ Instead:
 The `@SecondaryTable` annotation is even more interesting:
 
 .`@SecondaryTable` annotation members
-[cols="20,~"]
+[%breakable,cols="20,~"]
 |===
 | Annotation member | Purpose
 
@@ -299,7 +299,7 @@ class Author {
 Here, there should be a `UNIQUE` constraint on _both_ columns of the association table.
 
 .`@JoinTable` annotation members
-[cols="20,~"]
+[%breakable,cols="20,~"]
 |===
 | Annotation member | Purpose
 
@@ -341,7 +341,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
-[cols="20,~"]
+[%breakable,cols="20,~"]
 |===
 | Annotation member | Purpose
 
@@ -395,7 +395,7 @@ We don't use `@Column` to map associations.
 The `@JoinColumn` annotation is used to customize a foreign key column.
 
 .`@JoinColumn` annotation members
-[cols="20,~"]
+[%breakable,cols="20,~"]
 |===
 | Annotation member | Purpose
 
@@ -508,7 +508,7 @@ The `@PrimaryKeyJoinColumn` is a special-purpose annotation for mapping:
 - 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
-[cols="20,~"]
+[%breakable,cols="20,~"]
 |===
 | Annotation member | Purpose
 
@@ -559,7 +559,7 @@ So we don't usually need to explicitly specify that a column should be of type `
 The constant values defined in the class `org.hibernate.Length` are very helpful here:
 
 .Predefined column lengths
-[cols="10,12,~"]
+[%breakable,cols="10,12,~"]
 |===
 | Constant | Value | Description
 

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

@@ -51,7 +51,7 @@ As long as you set at least one property with the prefix `hibernate.agroal`, the
 There's many to choose from:
 
 .Settings for configuring Agroal
-[cols="37,~"]
+[%breakable,cols="37,~"]
 |===
 | Configuration property name | Purpose
 
@@ -70,7 +70,7 @@ There's many to choose from:
 The following settings are common to all connection pools supported by Hibernate:
 
 .Common settings for connection pools
-[cols="37,~"]
+[%breakable,cols="37,~"]
 |===
 | `hibernate.connection.autocommit` | The default autocommit mode
 | `hibernate.connection.isolation` | The default transaction isolation level
@@ -141,7 +141,7 @@ Of these, you should almost always use outer join fetching.
 Both batch fetching and subselect fetching are disabled by default, but we may enable one or the other globally using properties.
 
 .Configuration settings to enable batch and subselect fetching
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name | Property value
 
@@ -302,7 +302,7 @@ It's an error to place it on a subclass entity.
 The `@Cache` annotation always specifies a `CacheConcurrencyStrategy`, a policy governing access to the second-level cache by concurrent transactions.
 
 .Cache concurrency
-[cols="20,30,~"]
+[%breakable,cols="20,30,~"]
 |===
 | Concurrency policy | Interpretation | Explanation
 
@@ -348,7 +348,10 @@ Unfortunately, it's almost useless to us, since:
 - it may not be used to annotate associations, and so we can't even use it to mark collection roles as eligible for storage in the second-level cache.
 ====
 
-If our entity has a <<natural-id-attributes,natural id>>, we can enable an additional cache, which holds a mapping from natural id to id, by annotating the entity `@NaturalIdCache`.
+[[natural-id-cache]]
+=== Caching by natural id
+
+If our entity has a <<natural-id-attributes,natural id>>, we can enable an additional cache, which holds cross-references from natural id to primary id, by annotating the entity `@NaturalIdCache`.
 By default, the natural id cache is stored in a dedicated region of the second-level cache, separate from the cached entity data.
 
 [source,java]
@@ -374,6 +377,8 @@ This cache is utilized when the entity is retrieved using one of the operations
 Since the natural id cache doesn't contain the actual state of the entity, it doesn't make sense to annotate an entity `@NaturalIdCache` unless it's already eligible for storage in the second-level cache, that is, unless it's also annotated `@Cache`.
 ====
 
+It's worth noticing that, unlike the primary identifier of an entity, a natural id might be mutable.
+
 We must now consider a subtlety that often arises when we have to deal with so-called "reference data", that is, data which fits easily in memory, and doesn't change much.
 
 [[caching-and-fetching]]
@@ -433,7 +438,7 @@ But in case it helps, we often test Hibernate with the following configuration,
 :ehcache-config: https://www.ehcache.org/documentation/
 
 .EHCache configuration
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name              | Property value
 
@@ -453,12 +458,12 @@ JCache automatically selects whichever implementation it finds on the classpath.
 If there are multiple implementations on the classpath, we must disambiguate using:
 
 .Disambiguating the JCache implementation
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name        | Property value
 
 | `hibernate.javax.cache.provider`   a| The implementation of `javax.cache.spiCachingProvider`, for example:
-[cols="~,20"]
+[%breakable,cols="~,20"]
 !===
 ! `org.ehcache.jsr107.EhcacheCachingProvider` ! for EHCache
 ! `com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider` ! for Caffeine
@@ -470,13 +475,13 @@ Alternatively, to use Infinispan as the cache implementation, the following sett
 :infinispan-hibernate: https://infinispan.org/docs/stable/titles/hibernate/hibernate.html
 
 .Infinispan provider configuration
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name              | Property value
 
 | `hibernate.cache.region.factory_class`   | `infinispan`
 | `hibernate.cache.infinispan.cfg`         a| Path to infinispan configuration file, for example:
-[cols="~,35"]
+[%breakable,cols="~,35"]
 !===
 ! `org/infinispan/hibernate/cache/commons/builder/infinispan-configs.xml`
 ! for a distributed cache
@@ -491,7 +496,7 @@ There's more about using Infinispan with Hibernate {infinispan-hibernate}[here].
 Finally, there's a way to globally disable the second-level cache:
 
 .Setting to disable caching
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name              | Property value
 
@@ -516,7 +521,7 @@ Hibernate also has a way to cache the result sets of queries, though this is onl
 The query cache must be enabled explicitly:
 
 .Setting to enable the query cache
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name | Property value
 
@@ -585,7 +590,7 @@ entityManager.setCacheStoreMode(CacheStoreMode.BYPASS);
 The JPA-defined cache modes come in two flavors: `CacheRetrieveMode` and `CacheStoreMode`.
 
 .JPA-defined cache retrieval modes
-[cols="30,~"]
+[%breakable,cols="30,~"]
 |===
 | Mode | Interpretation
 
@@ -596,7 +601,7 @@ The JPA-defined cache modes come in two flavors: `CacheRetrieveMode` and `CacheS
 We might select `CacheRetrieveMode.BYPASS` if we're concerned about the possibility of reading stale data from the cache.
 
 .JPA-defined cache storage modes
-[cols="30,~"]
+[%breakable,cols="30,~"]
 |===
 | Mode | Interpretation
 
@@ -605,7 +610,7 @@ We might select `CacheRetrieveMode.BYPASS` if we're concerned about the possibil
 | `CacheStoreMode.BYPASS` | Don't write data to the cache
 |===
 
-We might select `CacheStoreMode.BYPASS` if we're querying data that we don't expect to use again soon.
+We should select `CacheStoreMode.BYPASS` if we're querying data that doesn't need to be cached.
 
 [TIP]
 // .A good time to `BYPASS` the cache
@@ -638,7 +643,7 @@ List<Publisher> allpubs =
 A Hibernate `CacheMode` packages a `CacheRetrieveMode` with a `CacheStoreMode`.
 
 .Hibernate cache modes and JPA equivalents
-[cols="30,~"]
+[%breakable,cols="30,~"]
 |===
 | Hibernate `CacheMode` | Equivalent JPA modes
 
@@ -687,8 +692,8 @@ sessionFactory.getCache().evictEntityData(Book.class, bookId);
 [CAUTION]
 // .Second-level cache management is not transaction-aware
 ====
-Second-level cache management is not transaction-aware.
-None of the operations of the `Cache` interface respect any isolation or transactional semantics associated with the underlying caches. In particular, eviction via the methods of this interface causes an immediate "hard" removal outside any current transaction and/or locking scheme.
+Second-level cache management via the `Cache` interface is not transaction-aware.
+None of the operations of `Cache` respect any isolation or transactional semantics associated with the underlying caches. In particular, eviction via the methods of this interface causes an immediate "hard" removal outside any current transaction and/or locking scheme.
 ====
 
 Ordinarily, however, Hibernate automatically evicts or updates cached data after modifications, and, in addition, cached data which is unused will eventually be expired according to the configured policies.
@@ -794,7 +799,7 @@ lock mode can be used to request a pessimistic lock, or to customize the behavio
 of optimistic locking:
 
 .Optimistic and pessimistic lock modes
-[cols="26,~"]
+[%breakable,cols="26,~"]
 |===
 | `LockMode` type | Meaning
 
@@ -822,7 +827,7 @@ an entity is written to the database using
 
 We may ask Hibernate to collect statistics about its activity by setting this configuration property:
 
-[cols="35,~"]
+[%breakable,cols="35,~"]
 |===
 | Configuration property name | Property value
 

documentation/src/main/asciidoc/introduction/theme.yml

@@ -87,7 +87,7 @@ table:
   caption:
     text-align: center
     side: top
-    font-size: 0.9em
+    font-size: 0.94em
   grid:
     color: #f0f0f0
     style: solid