HHH-19660 - Deprecate enhancement support for automatic association management

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

Author: jrenaat

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

@@ -95,6 +95,10 @@ include::{example-dir-enhancement}/BytecodeEnhancementTest.java[tags=BytecodeEnh
 
 Bytecode-enhanced bi-directional association management makes that first example work by managing the "other side" of a bi-directional association whenever one side is manipulated.
 
+[IMPORTANT]
+Bytecode-enhanced bi-directional association management has been deprecated as of Hibernate v7.1, and will be removed in a future release. Users are encouraged to move away from this functionality and instead adopt
+correct Java usage as outlined in the <<BytecodeEnhancement-dirty-tracking-bidirectional-correct-usage-example, example>> above.
+
 [[BytecodeEnhancement-dirty-tracking-optimizations]]
 ==== Internal performance optimizations
 

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

@@ -68,7 +68,9 @@ public interface EnhancementContext {
 	 * @return {@code true} indicates that the field is enhanced so that for bi-directional persistent fields
 	 * 			the association is managed, i.e. the associations are automatically set; {@code false} indicates that
 	 * 			the management is handled by the user.
+	 * @deprecated Will be removed without replacement. See HHH-19660
 	 */
+	@Deprecated(forRemoval = true)
 	boolean doBiDirectionalAssociationManagement(UnloadedField field);
 
 	/**

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.
@@ -203,6 +204,10 @@ public boolean doExtendedEnhancement(UnloadedClass classDescriptor) {
 			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 );
 		}
 
+		if ( enableAssociationManagement ) {
+			DEPRECATION_LOGGER.deprecatedSettingForRemoval( "management of bi-directional association persistent attributes", "false" );
+		}
+
 		final BytecodeProvider bytecodeProvider = buildDefaultBytecodeProvider();
 		try {
 			Enhancer enhancer = bytecodeProvider.getEnhancer( enhancementContext );

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

@@ -47,6 +47,9 @@ public static void enhance(
 		if ( !enhancementDsl.getEnableLazyInitialization().get() ) {
 			logger.warn( "The 'enableLazyInitialization' configuration is deprecated and will be removed. Set the value to 'true' to get rid of this warning" );
 		}
+		if ( enhancementDsl.getEnableAssociationManagement().get() ) {
+			logger.warn("Management of bi-directional association persistent attributes is deprecated and will be removed. Set the value to 'false' to get rid of this warning" );
+		}
 		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" );
 		}

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;
@@ -36,6 +38,9 @@ public ClassLoader getLoadingClassLoader() {
 
 	@Override
 	public boolean doBiDirectionalAssociationManagement(UnloadedField field) {
+		if ( enableAssociationManagement ) {
+			DEPRECATION_LOGGER.deprecatedSettingForRemoval( "management of bi-directional persistent association attributes", "false" );
+		}
 		return enableAssociationManagement;
 	}