From 9a48ce4040bda6af752862c69b5d1e741a29f1eb Mon Sep 17 00:00:00 2001 From: Gavin King Date: Mon, 11 Sep 2023 19:25:27 +0200 Subject: [PATCH] add some links to doc --- .../src/main/asciidoc/introduction/Advanced.adoc | 16 ++++++++-------- .../src/main/asciidoc/introduction/Entities.adoc | 6 +++--- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/documentation/src/main/asciidoc/introduction/Advanced.adoc b/documentation/src/main/asciidoc/introduction/Advanced.adoc index cc52e24e4d..eea3c46f5e 100644 --- a/documentation/src/main/asciidoc/introduction/Advanced.adoc +++ b/documentation/src/main/asciidoc/introduction/Advanced.adoc @@ -19,7 +19,7 @@ Examples of well-defined filters might include: - a filter that restricts to data associated with a certain geographical region. A filter must be declared somewhere. -A package descriptor is as good a place as any: +A package descriptor is as good a place as any for a link:{doc-javadoc-url}org/hibernate/annotations/FilterDef.html[`@FilterDef`]: [source,java] ---- @@ -48,7 +48,7 @@ package org.hibernate.example; The restriction must contain a reference to the parameter of the filter, specified using the usual syntax for named parameters. -Any entity or collection which is affected by a filter must be annotated `@Filter`: +Any entity or collection which is affected by a filter must be annotated link:{doc-javadoc-url}org/hibernate/annotations/Filter.html[`@Filter`]: [source,java] ---- @@ -243,7 +243,7 @@ class Account { } ---- -The `@TenantId` annotation is used to indicate an attribute of an entity which holds the tenant id. +The link:{doc-javadoc-url}org/hibernate/annotations/TenantId.html[`@TenantId`] annotation is used to indicate an attribute of an entity which holds the tenant id. Within a given session, our data is automatically filtered so that only rows tagged with the tenant id of the current tenant are visible in that session. [CAUTION] @@ -330,7 +330,7 @@ For example: One way to deal with this situation is to explicitly call `refresh()` at appropriate moments, forcing the session to reread the state of the entity. But this is annoying. -The `@Generated` annotation relieves us of the burden of explicitly calling `refresh()`. +The link:{doc-javadoc-url}org/hibernate/annotations/Generated.html[`@Generated`] annotation relieves us of the burden of explicitly calling `refresh()`. It specifies that the value of the annotated entity attribute is generated by the database, and that the generated value should be automatically retrieved using a SQL `returning` clause, or separate `select` after it is generated. A useful example is the following mapping: @@ -362,7 +362,7 @@ When a value is generated by both inserts _and_ updates, use `@Generated(event={ [TIP] ==== -For columns which should be generated using a SQL `generated always as` clause, prefer the `@GeneratedColumn` annotation, so that Hibernate automatically generates the correct DDL. +For columns which should be generated using a SQL `generated always as` clause, prefer the link:{doc-javadoc-url}org/hibernate/annotations/GeneratedColumn.html[`@GeneratedColumn`] annotation, so that Hibernate automatically generates the correct DDL. ==== Actually, the `@Generated` and `@GeneratedColumn` annotations are defined in terms of a more generic and user-extensible framework for handling attribute values generated in Java, or by the database. @@ -827,8 +827,8 @@ We do this by annotating the entity class. |=== | Annotation | Purpose -| `@DynamicInsert` | Specifies that an `insert` statement should be generated each time an entity is made persistent -| `@DynamicUpdate` | Specifies that an `update` statement should be generated each time an entity is modified +| link:{doc-javadoc-url}org/hibernate/annotations/DynamicInsert.html[`@DynamicInsert`] | Specifies that an `insert` statement should be generated each time an entity is made persistent +| link:{doc-javadoc-url}org/hibernate/annotations/DynamicUpdate.html[`@DynamicUpdate`] | Specifies that an `update` statement should be generated each time an entity is modified |=== It's important to realize that, while `@DynamicInsert` has no impact on semantics, the more useful `@DynamicUpdate` annotation _does_ have a subtle side effect. @@ -899,7 +899,7 @@ Since it's expensive to retrieve the full book-length text, we've mapped the fie [TIP] ==== By default, Hibernate fetches all lazy fields of a given entity at once, in a single `select`, when any one of them is accessed. -Using the `@LazyGroup` annotation, it's possible to assign fields to distinct "fetch groups", so that different lazy fields may be fetched independently. +Using the link:{doc-javadoc-url}org/hibernate/annotations/LazyGroup.html[`@LazyGroup`] annotation, it's possible to assign fields to distinct "fetch groups", so that different lazy fields may be fetched independently. ==== Similarly, interception lets us implement lazy fetching for non-polymorphic associations without the need for a separate proxy object. diff --git a/documentation/src/main/asciidoc/introduction/Entities.adoc b/documentation/src/main/asciidoc/introduction/Entities.adoc index 67155d9011..9b296e8bd3 100644 --- a/documentation/src/main/asciidoc/introduction/Entities.adoc +++ b/documentation/src/main/asciidoc/introduction/Entities.adoc @@ -468,8 +468,8 @@ Version attributes are automatically assigned by Hibernate when an entity is mad // .Optimistic locking in Hibernate ==== If an entity doesn't have a version number, which often happens when mapping legacy data, we can still do optimistic locking. -The `@OptimisticLocking` annotation lets us specify that optimistic locks should be checked by validating the values of `ALL` fields, or only the `DIRTY` fields of the entity. -And the `@OptimisticLock` annotation lets us selectively exclude certain fields from optimistic locking. +The link:{doc-javadoc-url}org/hibernate/annotations/OptimisticLocking.html[`@OptimisticLocking`] annotation lets us specify that optimistic locks should be checked by validating the values of `ALL` fields, or only the `DIRTY` fields of the entity. +And the link:{doc-javadoc-url}org/hibernate/annotations/OptimisticLock.html[`@OptimisticLock`] annotation lets us selectively exclude certain fields from optimistic locking. ==== The `@Id` and `@Version` attributes we've already seen are just specialized examples of _basic attributes_. @@ -490,7 +490,7 @@ If an entity doesn't have a meaningful unique key, then it's impossible to say w ==== Since it's _extremely_ common to retrieve an entity based on its natural key, Hibernate has a way to mark the attributes of the entity which make up its natural key. -Each attribute must be annotated `@NaturalId`. +Each attribute must be annotated link:{doc-javadoc-url}org/hibernate/annotations/NaturalId.html[`@NaturalId`]. [source,java] ----