HHH-19661 - Deprecate enhancement support for "extended" enhancement

Signed-off-by: Jan Schatteman <[email protected]>

Author: jrenaat

documentation/src/main/asciidoc/introduction/Advanced.adoc

@@ -1055,6 +1055,10 @@ Interception is able to detect writes to the `image` field, that is, replacement
 It's not able to detect modifications made directly to the _elements_ of the array, and so such modifications may be lost.
 ====
 
+[IMPORTANT]
+Hibernate's extended bytecode enhancement feature has been deprecated, primarily because it relies on assumptions and behaviors that often require a broader runtime scope than what Hibernate alone can reliably provide, similar to container-based environments such as Quarkus or WildFly.
+Applications which make use of this feature should instead use proper object-oriented encapsulation, exposing managed state via getters and setters.
+
 [[fetch-profiles]]
 === Named fetch profiles
 

documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc

@@ -308,7 +308,7 @@ Hibernate is able to map Object and primitive arrays as collections.  Mapping an
 the same as mapping a <<collection-list,list>>.
 
 There is a major limitation of mapping arrays to be aware of - the array cannot be lazy using
-<<collection-wrapper,wrappers>>.  It can, however, be lazy via <<bytecode-enhancement-guide,bytecode enhancement>>
+<<collection-wrapper,wrappers>>.  It can, however, be lazy via <<chapters/pc/BytecodeEnhancement.adoc#BytecodeEnhancement, bytecode enhancement>>
 of its owner.
 
 Note that Jakarta Persistence does not define support for arrays as plural attributes; according to the specification,

documentation/src/main/asciidoc/userguide/chapters/pc/BytecodeEnhancement.adoc

@@ -58,6 +58,10 @@ If your application does not need to care about "internal state changing data-ty
 In this approach Hibernate will manipulate the bytecode of your classes to add "dirty tracking" directly to the entity, allowing the entity itself to keep track of which of its attributes have changed.
 During the flush time, Hibernate asks your entity what has changed rather than having to perform the state-diff calculations.
 
+[IMPORTANT]
+Hibernate's extended bytecode enhancement feature has been deprecated, primarily because it relies on assumptions and behaviors that often require a broader runtime scope than what Hibernate alone can reliably provide, similar to container-based environments such as Quarkus or WildFly.
+Applications which make use of this feature should instead use proper object-oriented encapsulation, exposing managed state via getters and setters.
+
 [[BytecodeEnhancement-dirty-tracking-bidirectional]]
 ==== Bidirectional association management
 

hibernate-core/src/main/java/org/hibernate/bytecode/enhance/spi/EnhancementContext.java

@@ -90,7 +90,9 @@ public interface EnhancementContext {
 	 *
 	 * @return {@code true} indicates that any direct access to fields of entities should be routed to the enhanced
 	 *         getter / setter  method.
+	 * @deprecated Will be removed without replacement. See HHH-19661
 	 */
+	@Deprecated(forRemoval = true)
 	boolean doExtendedEnhancement(UnloadedClass classDescriptor);
 
 	/**

tooling/hibernate-ant/src/main/java/org/hibernate/tool/enhance/EnhancementTask.java

@@ -32,6 +32,7 @@
 import java.util.List;
 
 import static org.hibernate.bytecode.internal.BytecodeProviderInitiator.buildDefaultBytecodeProvider;
+import static org.hibernate.internal.log.DeprecationLogger.DEPRECATION_LOGGER;
 
 /**
  * Ant task for performing build-time enhancement of entity objects.
@@ -200,7 +201,7 @@ public boolean doExtendedEnhancement(UnloadedClass classDescriptor) {
 		};
 
 		if ( enableExtendedEnhancement ) {
-			log( "Extended enhancement is enabled. Classes other than entities may be modified. You should consider access the entities using getter/setter methods and disable this property. Use at your own risk.", Project.MSG_WARN );
+			DEPRECATION_LOGGER.deprecatedSettingForRemoval("extended enhancement", "false");
 		}
 
 		final BytecodeProvider bytecodeProvider = buildDefaultBytecodeProvider();

tooling/hibernate-gradle-plugin/src/main/java/org/hibernate/orm/tooling/gradle/enhance/EnhancementHelper.java

@@ -50,6 +50,9 @@ public static void enhance(
 		if ( !enhancementDsl.getEnableDirtyTracking().get() ) {
 			logger.warn( "The 'enableDirtyTracking' configuration is deprecated and will be removed. Set the value to 'true' to get rid of this warning" );
 		}
+		if ( enhancementDsl.getEnableExtendedEnhancement().get() ) {
+			logger.warn("Extended enhancement is deprecated and will be removed. Set the value to 'false' to get rid of this warning" );
+		}
 		final Enhancer enhancer = generateEnhancer( classLoader, enhancementDsl );
 
 		discoverTypes( classesDir, classesDir, enhancer, ormDsl.getFileOperations() );

tooling/hibernate-maven-plugin/src/main/java/org/hibernate/orm/tooling/maven/EnhancementContext.java

@@ -8,6 +8,8 @@
 import org.hibernate.bytecode.enhance.spi.UnloadedClass;
 import org.hibernate.bytecode.enhance.spi.UnloadedField;
 
+import static org.hibernate.internal.log.DeprecationLogger.DEPRECATION_LOGGER;
+
 public class EnhancementContext extends DefaultEnhancementContext {
 
 	private ClassLoader classLoader = null;
@@ -56,6 +58,9 @@ public boolean isLazyLoadable(UnloadedField field) {
 
 	@Override
 	public boolean doExtendedEnhancement(UnloadedClass classDescriptor) {
+		if (enableExtendedEnhancement) {
+			DEPRECATION_LOGGER.deprecatedSettingForRemoval("extended enhancement", "false");
+		}
 		return enableExtendedEnhancement;
 	}