javadoc for @NaturalId, @NaturalIdCache, @ListIndexBase

hibernate-core/src/main/java/org/hibernate/annotations/ListIndexBase.java

@@ -11,13 +11,19 @@ import java.lang.annotation.Retention;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Defines the start index value for a list index as stored on the database.  This base is subtracted from the
- * incoming database value on reads to determine the List position; it is added to the List position index when
- * writing to the database.
- *
- * By default list indexes are stored starting at zero.
- *
- * Generally used in conjunction with {@link jakarta.persistence.OrderColumn}.
+ * Specifies the base value for the {@link jakarta.persistence.OrderColumn
+ * order column} of a persistent list or array, that is, the order column
+ * value of the first element of the list or array.
+ * <ul>
+ * <li>When a row is read from the database, this base value is subtracted
+ *     from the order column value to determine an index in the list or array.
+ * <li>When an element is written to the database, the base value is added to
+ *     the list or array index to determine the order column value.
+ *</ul>
+ * By default, the base value for an order column is zero, as required by JPA.
+ * <p>
+ * This annotation is usually used in conjunction with the JPA-defined
+ * {@link jakarta.persistence.OrderColumn}.
  *
  * @see jakarta.persistence.OrderColumn
  *

hibernate-core/src/main/java/org/hibernate/annotations/Loader.java

@@ -24,7 +24,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention( RUNTIME )
 public @interface Loader {
 	/**
-	 * THe named query to use for loading the entity.
+	 * The named query to use for loading the entity.
 	 */
 	String namedQuery() default "";
 }

hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java

@@ -14,7 +14,22 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * This specifies that a property is part of the natural id of the entity.
+ * Specifies that a field or property of an entity class is part of
+ * the natural id of the entity. This annotation is very useful when
+ * the primary key of an entity class is a surrogate key, that is,
+ * a {@linkplain jakarta.persistence.GeneratedValue system-generated}
+ * synthetic identifier, with no domain-model semantics. Then should
+ * always be some other field or combination of fields which uniquely
+ * identifies an instance of the entity from the point of view of the
+ * user of the system. This is the <em>natural id</em> of the entity.
+ * <p>
+ * The {@link org.hibernate.Session} interface offers several methods
+ * that allow an entity instance to be retrieved by its
+ * {@linkplain org.hibernate.Session#bySimpleNaturalId(Class) simple}
+ * or {@linkplain org.hibernate.Session#byNaturalId(Class) composite}
+ * natural id value. If the entity is also marked for {@linkplain
+ * NaturalIdCache natural id caching}, then these methods may be able
+ * to avoid a database round trip.
  *
  * @author Nicol<EFBFBD>s Lichtmaier
  *
@@ -24,8 +39,10 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention( RUNTIME )
 public @interface NaturalId {
 	/**
-	 * Whether the natural id is mutable (or immutable)?  {@code false} (the default) indicates it is immutable;
-	 * {@code true} indicates it is mutable.
+	 * Specifies whether the natural id is mutable or immutable.
+	 *
+	 * @return {@code false} (the default) indicates it is immutable;
+	 *         {@code true} indicates it is mutable.
 	 */
 	boolean mutable() default false;
 }

hibernate-core/src/main/java/org/hibernate/annotations/NaturalIdCache.java

@@ -13,8 +13,15 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Specifies that the natural id values associated with the annotated
- * entity should be cached in the shared second-level cache.
+ * Specifies that mappings from the natural id values of the annotated
+ * entity to the corresponding entity id values should be cached in the
+ * shared second-level cache. This allows Hibernate to sometimes avoid
+ * round trip to the database when a cached entity is retrieved by its
+ * natural id.
+ * <p>
+ * This annotation is usually used in combination with {@link Cache},
+ * since a round trip may only be avoided if the entity itself is
+ * also available in the cache.
  *
  * @author Eric Dalquist
  * @author Steve Ebersole

hibernate-core/src/main/java/org/hibernate/cache/spi/DomainDataRegion.java

@@ -17,7 +17,7 @@ import org.hibernate.metamodel.model.domain.NavigableRole;
  * <ul>
  * <li>the destructured state of entity instances and collections, and
  * <li>mappings from natural id to primary key.
- *</ul>
+ * </ul>
  * This type of data has:
  * <ul>
  * <li>key and value wrapping that should to be applied, and