From d00b92259f51f86675892d354d54c768dda55a34 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Wed, 9 Nov 2022 09:45:05 +0100
Subject: [PATCH] Javadoc for @LazyGroup

---
 .../org/hibernate/annotations/LazyGroup.java  | 34 +++++++++++++++----
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/LazyGroup.java b/hibernate-core/src/main/java/org/hibernate/annotations/LazyGroup.java
index cc683c0a6d..4424f594d6 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/LazyGroup.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/LazyGroup.java
@@ -11,12 +11,34 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * For use with bytecode-enhanced lazy-loading support.
- * <p/>
- * Identifies grouping for performing lazy attribute loading.  By default all
- * non-collection attributes are loaded in one group named {@code "DEFAULT"}.
- * This annotation allows defining different groups of attributes to be
- * initialized together when access one attribute in the group.
+ * Specifies the <em>fetch group</em> for a persistent attribute of an entity
+ * class. This annotation has no effect unless bytecode enhancement is used,
+ * and field-level lazy fetching is enabled.
+ * <ul>
+ * <li>When bytecode enhancement is not used, declaring a field as
+ *     {@link jakarta.persistence.Basic#fetch() @Basic(fetch=LAZY)} has no
+ *     effect on the runtime behavior of Hibernate. All fields of an entity
+ *     are loaded at the same time, as if they all belonged to the same fetch
+ *     group.
+ * <li>But when bytecode enhancement is used, a field declared
+ *     {@code @Basic(fetch=LAZY)}} is loaded lazily when it is first accessed,
+ *     using a separate SQL {@code select} statement. Since this trip to the
+ *     database is generally expensive, Hibernate will, by default, load all
+ *     lazy fields at once. This annotation provides control over that
+ *     behavior.
+ * </ul>
+ * A fetch group identifies a set of related attributes that should be loaded
+ * together when any one of them is accessed. By default, all non-collection
+ * attributes belong to a single fetch group named {@code "DEFAULT"}. The
+ * fetch group for a given lazy attribute may be explicitly specified using
+ * the {@link #value()} member of this annotation.
+ * <p>
+ * For example, a field annotated {@code @Basic(fetch=LAZY) @LazyGroup("extra")}
+ * belongs to the fetch group named {@code "extra"}, and is loaded whenever an
+ * attribute belonging to the {@code "extra"} fetch group is accessed.
+ * <p>
+ * Note that field-level lazy fetching is usually of dubious value, and most
+ * projects using Hibernate don't even bother enabling the bytecode enhancer.
  *
  * @author Steve Ebersole
  */