javadoc for @LazyToOne

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}
+ * Specifies the machinery used to handle lazy fetching of
- * or {@link jakarta.persistence.ManyToOne}) association.
+ * 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:
+ * <ul>
+ * <li>{@linkplain LazyToOneOption#FALSE eager fetching},
+ * <li>lazy fetching via interception of calls on a
+ *     {@linkplain LazyToOneOption#PROXY proxy object},
+ *     and
+ * <li>lazy fetching via interception of field access on
+ *     the {@linkplain LazyToOneOption#NO_PROXY owning side}
+ *     of the association.
+ * </ul>
+ * By default, an unfetched lazy association is represented
+ * by a <em>proxy object</em>. 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.
  * <p>
- * This is an alternative to specifying the JPA
+ * With {@code LazyToOne(NO_PROXY)}, lazy fetching occurs
- * {@link jakarta.persistence.FetchType}.
+ * 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;
 }

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.
+	 * The association is proxied and loaded lazily, by
-	 *
+	 * intercepting calls on the proxy object.
-	 * This should be the preferred option.
+	 * <ul>
+	 * <li>The program may obtain the entity identifier value
+	 *     of an unfetched proxy, without triggering lazy
+	 *     fetching.
+	 * <li>For a polymorphic association, the proxy does not
+	 *     have the concrete type of the proxied instance, and
+	 *     so {@link org.hibernate.Hibernate#getClass(Object)}
+	 *     must be used in place of {@link Object#getClass()}
+	 *     and the Java {@code instanceof} operator.
+	 * </ul>
 	 */
 	PROXY,
 	/**
-	 * Lazy, give back the real object loaded when a reference is requested.
+	 * The association is loaded lazily when the field holding
-	 *
+	 * the reference to the associated object is first accessed.
-	 * Bytecode enhancement is mandatory for this option.  Falls back to {@link #PROXY}
+	 * <ul>
-	 * if the class is not enhanced.  This option should be avoided unless you can't afford
+	 * <li>There is no way for the program to obtain the
-	 * the use of proxies
+	 *     identifier of the associated entity without triggering
+	 *     lazy fetching, and therefore this option is not
+	 *     recommended.
+	 * <li>On the other hand, {@link Object#getClass()} and the
+	 *     {@code instanceof} operator may be used even if the
+	 *     association is polymorphic.
+	 * </ul>
+	 * Bytecode enhancement is required. If the class is not
+	 * enhanced, this option is equivalent to {@link #PROXY}.
 	 */
 	NO_PROXY
 }

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 );

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;