HHH-15739 deprecate @LazyToOne and @LazyCollection + introduce @Proxyless

- @Proxyless replaces @LazyToOne
- static methods of Hibernate replace @LazyCollection

Author: gavinking

hibernate-core/src/main/java/org/hibernate/Hibernate.java

@@ -59,6 +59,9 @@
  * the Hibernate metamodel, to write such generic code for any given serialization
  * library, but the details depend on what facilities the library itself offers for
  * the program to intervene in the process of serialization and of deserialization.
+ * <p>
+ * See {@linkplain org.hibernate.annotations.Proxyless this discussion of proxies in
+ * Hibernate}.
  *
  * @author Gavin King
  */

hibernate-core/src/main/java/org/hibernate/annotations/LazyCollection.java

@@ -10,6 +10,8 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import java.util.Collection;
+import java.util.Map;
 
 /**
  * Specify the laziness of a collection, either a
@@ -22,7 +24,19 @@
  * extra-lazy collection fetching}.
  *
  * @author Emmanuel Bernard
+ *
+ * @deprecated
+ * <ul>
+ * <li>Use the JPA-defined {@link jakarta.persistence.FetchType#EAGER}
+ *     instead of {@code LazyCollection(FALSE)}.
+ * <li>Use static methods of {@link org.hibernate.Hibernate},
+ *     for example {@link org.hibernate.Hibernate#size(Collection)},
+ *     {@link org.hibernate.Hibernate#contains(Collection, Object)},
+ *     or {@link org.hibernate.Hibernate#get(Map, Object)} instead
+ *     of {@code LazyCollection(EXTRA)}.
+ * </ul>
  */
+@Deprecated
 @Target({ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface LazyCollection {

hibernate-core/src/main/java/org/hibernate/annotations/LazyCollectionOption.java

@@ -6,6 +6,9 @@
  */
 package org.hibernate.annotations;
 
+import java.util.Collection;
+import java.util.Map;
+
 /**
  *  Enumerates the options for lazy loading of a
  *  {@linkplain jakarta.persistence.ElementCollection collection},
@@ -15,7 +18,19 @@
  * @author Emmanuel Bernard
  *
  * @see LazyCollection
+ *
+ * @deprecated
+ * <ul>
+ * <li>Use the JPA-defined {@link jakarta.persistence.FetchType#EAGER}
+ *     instead of {@code LazyCollection(FALSE)}.
+ * <li>Use static methods of {@link org.hibernate.Hibernate},
+ *     for example {@link org.hibernate.Hibernate#size(Collection)},
+ *     {@link org.hibernate.Hibernate#contains(Collection, Object)},
+ *     or {@link org.hibernate.Hibernate#get(Map, Object)} instead
+ *     of {@code LazyCollection(EXTRA)}.
+ * </ul>
  */
+@Deprecated
 public enum LazyCollectionOption {
 	/**
 	 * The collection is always loaded eagerly, and all its

hibernate-core/src/main/java/org/hibernate/annotations/LazyToOne.java

@@ -59,7 +59,10 @@
  * and instead falls back to using a proxy!</strong>
  *
  * @author Emmanuel Bernard
+ *
+ * @deprecated use {@link Proxyless @Proxyless}
  */
+@Deprecated
 @Target({ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface LazyToOne {

hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java

@@ -15,7 +15,10 @@
  * @author Emmanuel Bernard
  *
  * @see LazyToOne
+ *
+ * @deprecated use {@link Proxyless @Proxyless}
  */
+@Deprecated
 public enum LazyToOneOption {
 	/**
 	 * The association is always loaded eagerly. The identifier
@@ -38,7 +41,8 @@ public enum LazyToOneOption {
 	 * <li>The proxy does not have the same concrete type as the
 	 *     proxied delegate, and so
 	 *     {@link org.hibernate.Hibernate#getClass(Object)}
-	 *     must be used in place of {@link Object#getClass()}.
+	 *     must be used in place of {@link Object#getClass()},
+	 *     and this method fetches the entity by side-effect.
 	 * <li>For a polymorphic association, the concrete type of
 	 *     the proxied entity instance is not known until the
 	 *     delegate is fetched from the database, and so

hibernate-core/src/main/java/org/hibernate/annotations/Proxyless.java

@@ -0,0 +1,73 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Specifies that the program should not be exposed to a
+ * synthetic proxy object when the annotated lazily-fetched
+ * {@linkplain jakarta.persistence.OneToOne one to one} or
+ * {@linkplain jakarta.persistence.ManyToOne many to one}
+ * association is unfetched. This annotation has no effect
+ * on eager associations.
+ * <p>
+ * By default, that is, when an association is <em>not</em>
+ * annotated {@code Proxyless}, an unfetched lazy association
+ * is represented by a <em>proxy object</em> which holds the
+ * identifier (foreign key) of the associated entity instance.
+ * <ul>
+ * <li>The identifier property of the proxy object is set
+ *     when the proxy is instantiated.
+ *     The program may obtain the entity identifier value
+ *     of an unfetched proxy, without triggering lazy
+ *     fetching, by calling the corresponding getter method.
+ *     (It's even possible to set an association to reference
+ *     an unfetched proxy.)
+ * <li>A delegate entity instance is lazily fetched when any
+ *     other method of the proxy is called.
+ * <li>The proxy does not have the same concrete type as the
+ *     proxied delegate, and so
+ *     {@link org.hibernate.Hibernate#getClass(Object)}
+ *     must be used in place of {@link Object#getClass()},
+ *     and this method fetches the entity by side-effect.
+ * <li>For a polymorphic association, the concrete type of
+ *     the proxied entity instance is not known until the
+ *     delegate is fetched from the database, and so
+ *     {@link org.hibernate.Hibernate#unproxy(Object, Class)}}
+ *     must be used to perform typecasts, and
+ *     {@link org.hibernate.Hibernate#getClass(Object)}
+ *     must be used instead of the Java {@code instanceof}
+ *     operator.
+ * </ul>
+ * When an association is annotated {@code Proxyless}, there
+ * is no such indirection, but the associated entity instance
+ * is initially in an unloaded state, with only its identifier
+ * field set.
+ * <ul>
+ * <li>The identifier field of an unloaded entity instance is
+ *     set when the unloaded instance is instantiated.
+ *     The program may obtain the identifier of an unloaded
+ *     entity, without triggering lazy loading, by accessing
+ *     the field containing the identifier.
+ * <li>The remaining non-lazy state of the entity instance is
+ *     loaded lazily when any other field is accessed.
+ * <li>Typecasts, the Java {@code instanceof} operator, and
+ *     {@link Object#getClass()} may be used as normal.
+ * <li>Bytecode enhancement is required.
+ * </ul>
+ * <strong>Currently, Hibernate does not support {@code
+ * Proxyless} for polymorphic associations </strong>
+ *
+ */
+@Target({ElementType.METHOD, ElementType.FIELD})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Proxyless {
+}

hibernate-core/src/main/java/org/hibernate/cfg/ToOneBinder.java

@@ -32,6 +32,7 @@
 import org.hibernate.annotations.NotFoundAction;
 import org.hibernate.annotations.OnDelete;
 import org.hibernate.annotations.OnDeleteAction;
+import org.hibernate.annotations.Proxyless;
 import org.hibernate.annotations.common.reflection.XClass;
 import org.hibernate.annotations.common.reflection.XProperty;
 import org.hibernate.boot.spi.MetadataBuildingContext;
@@ -304,11 +305,16 @@ static void defineFetchingStrategy(
 
 		final LazyToOne lazy = property.getAnnotation( LazyToOne.class );
 		final NotFound notFound = property.getAnnotation( NotFound.class );
+		final boolean proxyless = property.isAnnotationPresent( Proxyless.class );
 		if ( notFound != null ) {
 			toOne.setLazy( false );
 			toOne.setUnwrapProxy( true );
 		}
 		else if ( lazy != null ) {
+			if ( proxyless ) {
+				throw new AnnotationException("Association '" + getPath( propertyHolder, inferredData )
+						+ "' is annotated '@Proxyless' and '@LazyToOne'");
+			}
 			boolean lazyFalse = lazy.value() == LazyToOneOption.FALSE;
 			if ( fetchType == FetchType.LAZY && lazyFalse ) {
 				throw new AnnotationException("Association '" + getPath( propertyHolder, inferredData )
@@ -319,7 +325,7 @@ else if ( lazy != null ) {
 		}
 		else {
 			toOne.setLazy( fetchType == FetchType.LAZY );
-			toOne.setUnwrapProxy( fetchType != FetchType.LAZY );
+			toOne.setUnwrapProxy( proxyless || fetchType == FetchType.EAGER );
 			toOne.setUnwrapProxyImplicit( true );
 		}