diff --git a/hibernate-core/src/main/java/org/hibernate/NaturalIdLoadAccess.java b/hibernate-core/src/main/java/org/hibernate/NaturalIdLoadAccess.java index 5024ff7a80..6a19f9923f 100644 --- a/hibernate-core/src/main/java/org/hibernate/NaturalIdLoadAccess.java +++ b/hibernate-core/src/main/java/org/hibernate/NaturalIdLoadAccess.java @@ -103,20 +103,26 @@ public interface NaturalIdLoadAccess { NaturalIdLoadAccess using(Object... mappings); /** - * For entities with mutable natural ids, should natural ids be - * synchronized prior to executing a query? The default, for - * correctness, is to synchronize. + * Determines if cached natural id cross-references are synchronized + * before query execution with unflushed modifications made in memory + * to {@linkplain org.hibernate.annotations.NaturalId#mutable mutable} + * natural ids . + *

+ * By default, every cached cross-reference is updated to reflect any + * modification made in memory. *

* Here "synchronization" means updating the natural id to * primary key cross-reference maintained by the session. When - * enabled, prior to performing the lookup, Hibernate will check - * all entities of the given type associated with the session to - * see if any natural id values have changed and, if so, update - * the cross-reference. There is a performance penalty associated - * with this, so if it is completely certain the no natural id in - * play has changed, this setting can be disabled to circumvent - * that impact. Disabling this setting when natural id values - * have changed can lead to incorrect results! + * enabled, before performing the lookup, Hibernate will check + * all entities associated with the session of the given type to + * determine if any natural id values have changed and, if so, + * update the cross-references. + *

+ * There's some cost associated with this synchronization, so if + * it's completely certain the no natural ids have been modified, + * synchronization may be safely disabled to avoid that cost. + * Disabling this setting when natural id values have + * been modified may lead to incorrect results. * * @param enabled Should synchronization be performed? * {@code true} indicates synchronization will be performed; diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java b/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java index 1b69bce81d..a86eedee85 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java @@ -67,6 +67,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * } * *

+ * Unlike the {@linkplain jakarta.persistence.Id primary identifier} + * of an entity, a natural id may be {@linkplain #mutable}. + *

* 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}