From 2e99811dd4011af4de46a7a47a34153cdc57884e Mon Sep 17 00:00:00 2001 From: Gavin Date: Mon, 21 Nov 2022 14:35:57 +0100 Subject: [PATCH] javadoc for @LazyToOne --- .../org/hibernate/annotations/LazyToOne.java | 43 +++++++++++++++--- .../annotations/LazyToOneOption.java | 44 ++++++++++++++----- .../java/org/hibernate/cfg/ToOneBinder.java | 2 +- .../descriptor/java/spi/JavaTypeRegistry.java | 1 - 4 files changed, 73 insertions(+), 17 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOne.java b/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOne.java index 21503e59dd..486c66df7e 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOne.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOne.java @@ -12,11 +12,43 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Specify the laziness of a {@link jakarta.persistence.OneToOne} - * or {@link jakarta.persistence.ManyToOne}) association. + * Specifies the machinery used to handle lazy fetching of + * the annotated {@link jakarta.persistence.OneToOne} or + * {@link jakarta.persistence.ManyToOne} association. This + * is an alternative to specifying only the JPA + * {@link jakarta.persistence.FetchType}. This annotation + * is occasionally useful, since there are observable + * differences in semantics between: + * + * By default, an unfetched lazy association is represented + * by a proxy object. This approach comes with the + * major advantage that the program may obtain the identifier + * (foreign key) of the associated entity instance without + * fetching it from the database. Since a proxy carries a + * foreign key, it's even possible to set an association + * using an unfetched proxy. On the other hand, for a + * polymorphic association, the concrete type of the entity + * instance represented by a proxy is unknown, and so + * {@link org.hibernate.Hibernate#getClass(Object)} must + * be used to obtain the concrete type, fetching the entity + * by side effect. *

- * This is an alternative to specifying the JPA - * {@link jakarta.persistence.FetchType}. + * With {@code LazyToOne(NO_PROXY)}, lazy fetching occurs + * when the field holding the reference to the associated + * entity is accessed. With this approach, it's impossible + * to obtain the identifier of the associated entity without + * fetching the entity from the database. On the other hand, + * {@code instanceof} and {@link Object#getClass()} work as + * normal, since the concrete type of the entity instance is + * known immediately. This is usually bad tradeoff. * * @author Emmanuel Bernard */ @@ -24,7 +56,8 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.RUNTIME) public @interface LazyToOne { /** - * The laziness of the association. + * A {@link LazyToOneOption} which determines how lazy + * fetching should be handled. */ LazyToOneOption value() default LazyToOneOption.PROXY; } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java b/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java index b577d9fc54..015f1f8dd8 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java @@ -7,27 +7,51 @@ package org.hibernate.annotations; /** - * Lazy options available for a ToOne association. + * Enumerates the options for lazy loading of a + * {@linkplain jakarta.persistence.ManyToOne many to one} + * or {@linkplain jakarta.persistence.OneToOne one to one} + * association. * * @author Emmanuel Bernard + * + * @see LazyToOne */ public enum LazyToOneOption { /** - * Eagerly load the association. + * The association is always loaded eagerly. The identifier + * and concrete type of the associated entity instance are + * always known immediately. */ FALSE, /** - * Lazy, give back a proxy which will be loaded when the state is requested. - * - * This should be the preferred option. + * The association is proxied and loaded lazily, by + * intercepting calls on the proxy object. + *

*/ PROXY, /** - * Lazy, give back the real object loaded when a reference is requested. - * - * Bytecode enhancement is mandatory for this option. Falls back to {@link #PROXY} - * if the class is not enhanced. This option should be avoided unless you can't afford - * the use of proxies + * The association is loaded lazily when the field holding + * the reference to the associated object is first accessed. + * + * Bytecode enhancement is required. If the class is not + * enhanced, this option is equivalent to {@link #PROXY}. */ NO_PROXY } diff --git a/hibernate-core/src/main/java/org/hibernate/cfg/ToOneBinder.java b/hibernate-core/src/main/java/org/hibernate/cfg/ToOneBinder.java index fc8bf80175..43f8716cec 100644 --- a/hibernate-core/src/main/java/org/hibernate/cfg/ToOneBinder.java +++ b/hibernate-core/src/main/java/org/hibernate/cfg/ToOneBinder.java @@ -306,7 +306,7 @@ public class ToOneBinder { } else if ( lazy != null ) { toOne.setLazy( lazy.value() != LazyToOneOption.FALSE ); - toOne.setUnwrapProxy( ( lazy.value() == LazyToOneOption.NO_PROXY ) ); + toOne.setUnwrapProxy( lazy.value() == LazyToOneOption.NO_PROXY ); } else { toOne.setLazy( fetchType == FetchType.LAZY ); diff --git a/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/JavaTypeRegistry.java b/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/JavaTypeRegistry.java index b16a6fcd79..8be9a45e14 100644 --- a/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/JavaTypeRegistry.java +++ b/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/JavaTypeRegistry.java @@ -16,7 +16,6 @@ import org.hibernate.type.descriptor.java.ArrayJavaType; import org.hibernate.type.descriptor.java.JavaType; import org.hibernate.type.descriptor.java.MutabilityPlan; import org.hibernate.type.descriptor.java.MutableMutabilityPlan; -import org.hibernate.type.descriptor.jdbc.JdbcType; import org.hibernate.type.spi.TypeConfiguration; import org.hibernate.type.spi.TypeConfigurationAware;