Javadoc for @LazyGroup

This commit is contained in:
Gavin King 2022-11-09 09:45:05 +01:00
parent d8fcade838
commit d00b92259f
1 changed files with 28 additions and 6 deletions

View File

@ -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
*/