From 908630a7f2bb3cc63c6fa06a32c59e27f6a2014f Mon Sep 17 00:00:00 2001 From: Gavin Date: Thu, 25 May 2023 11:46:10 +0200 Subject: [PATCH] more accurate cross-links in doc --- documentation/src/main/asciidoc/introduction/Advanced.adoc | 2 +- documentation/src/main/asciidoc/introduction/Entities.adoc | 4 +++- .../src/main/asciidoc/introduction/Interacting.adoc | 5 ++--- documentation/src/main/asciidoc/introduction/Tuning.adoc | 2 +- 4 files changed, 7 insertions(+), 6 deletions(-) diff --git a/documentation/src/main/asciidoc/introduction/Advanced.adoc b/documentation/src/main/asciidoc/introduction/Advanced.adoc index d75754cf40..825e91d128 100644 --- a/documentation/src/main/asciidoc/introduction/Advanced.adoc +++ b/documentation/src/main/asciidoc/introduction/Advanced.adoc @@ -819,5 +819,5 @@ session.enableFetchProfile("org.hibernate.defaultProfile"); Then ``outer join``s for such associations will _automatically_ be added to every HQL or criteria query. This is nice if you can't be bothered typing out those ``join fetch``es explicitly. -And in principle it even helps partially mitigate the <> of JPA having specified the wrong default for the `fetch` member of `@ManyToOne`. +And in principle it even helps partially mitigate the <> of JPA having specified the wrong default for the `fetch` member of `@ManyToOne`. ==== diff --git a/documentation/src/main/asciidoc/introduction/Entities.adoc b/documentation/src/main/asciidoc/introduction/Entities.adoc index 67b35beed7..a04757d7c4 100644 --- a/documentation/src/main/asciidoc/introduction/Entities.adoc +++ b/documentation/src/main/asciidoc/introduction/Entities.adoc @@ -996,6 +996,7 @@ class Book { Here, the `Book` table has a foreign key column holding the identifier of the associated `Publisher`. +[[lazy-problem]] [TIP] // .Almost all associations should be lazy ==== @@ -1037,6 +1038,7 @@ Set books; ---- We're going to use this approach for the rest of the Introduction. +[[bidirectional-problem]] [WARNING] // .To modify a bidirectional association, you must change the _owning side_! ==== @@ -1120,7 +1122,7 @@ Here, the `Author` table has a foreign key column holding the identifier of the ==== A one-to-one association often models a "type of" relationship. In our example, an `Author` is a type of `Person`. -An alternative—and often more natural—way to represent "type of" relationships in Java is via <>. +An alternative—and often more natural—way to represent "type of" relationships in Java is via <>. ==== We can make this association bidirectional by adding a reference back to the `Author` in the `Person` entity: diff --git a/documentation/src/main/asciidoc/introduction/Interacting.adoc b/documentation/src/main/asciidoc/introduction/Interacting.adoc index 489bf56ba3..4f62e21893 100644 --- a/documentation/src/main/asciidoc/introduction/Interacting.adoc +++ b/documentation/src/main/asciidoc/introduction/Interacting.adoc @@ -332,7 +332,7 @@ Now for the gotchas: We're getting a bit ahead of ourselves here, but let's quickly mention the general strategy we recommend to navigate past these gotchas: - All associations should be set `fetch=LAZY` to avoid fetching extra data when it's not needed. - As we mentioned in <>, this setting is not the default for `@ManyToOne` associations, and must be specified explicitly. + As we mentioned <>, this setting is not the default for `@ManyToOne` associations, and must be specified explicitly. - But strive to avoid writing code which triggers lazy fetching. Instead, fetch all the data you'll need upfront at the beginning of a unit of work, using one of the techniques described in <>, usually, using _join fetch_ in HQL or an `EntityGraph`. ==== @@ -1035,10 +1035,9 @@ In this section we'll quickly sketch some general strategies for avoiding "quagm Hibernate is not about "transparent persistence" for Java objects. It's about making two excellent technologies work smoothly together. - <> executed by Hibernate. -// Look, this seems obvious, until you've met users who didn't realize it was possible or useful. You cannot know that your persistence logic is correct until you've actually inspected the SQL that's being executed. Even when everything seems to be "working", there might be a lurking <>. -- Be careful when <>. +- Be careful when <>. In principle, you should update _both ends_ of the association. But Hibernate doesn't strictly enforce that, since there are some situations where such a rule would be too heavy-handed. Whatever the case, it's up to you to maintain consistency across your model. diff --git a/documentation/src/main/asciidoc/introduction/Tuning.adoc b/documentation/src/main/asciidoc/introduction/Tuning.adoc index ce3ab408bc..a2e247f940 100644 --- a/documentation/src/main/asciidoc/introduction/Tuning.adoc +++ b/documentation/src/main/asciidoc/introduction/Tuning.adoc @@ -424,7 +424,7 @@ Therefore, we arrive at this rule of thumb: ==== Many-to-one associations to "reference data", or to any other data that will almost always be available in the cache, should be mapped `EAGER`,`SELECT`. -Other associations, as we've <>, should be `LAZY`. +Other associations, as we've <>, should be `LAZY`. ==== Once we've marked an entity or collection as eligible for storage in the second-level cache, we still need to set up an actual cache.