Ticket 1.5: Verify DirectCopyClassTransformer compatibility with Hibernate 6

[devin-ai-integration]

Brief Overview

Investigation of whether the Javassist-based DirectCopyClassTransformer load-time weaving infrastructure is compatible with Hibernate 6's refactored metamodel scanner and bytecode enhancement. The codebase currently uses Hibernate 5.6.15.Final; these changes prepare and document the weaving pipeline for a future Hibernate 6 migration.

Labels: Enhancement, Status: ready-for-code-review

Changes

Documentation (majority of diff): Added Hibernate 6 compatibility Javadoc to DirectCopyClassTransformer, BroadleafHibernateEnhancingClassTransformerImpl, BroadleafCommonConfig, and ConditionalDirectCopyTransformersManager explaining transformation ordering guarantees and known integration points with Hibernate internals.

getNewCacheAnnotation() — Hibernate 6 Javadoc: Added documentation noting that @org.hibernate.annotations.Cache is deprecated in Hibernate 6.2+ in favor of @jakarta.persistence.Cacheable, but is still fully processed by Hibernate 6. No behavioral change to the method — the Javadoc documents what would need to change if templates migrate to @Cacheable in the future.

BroadleafHibernateEnhancingClassTransformerImpl — narrowed defensive try/catch: Wraps super.transform() with targeted exception handling: IllegalClassFormatException (checked) is re-thrown so genuine class format problems still abort class loading, while RuntimeException (e.g., ASM/Javassist bytecode incompatibilities) is caught, logged at WARN with full stack trace, and skipped to prevent application crash.

DirectCopyTransformHibernate6CompatibilityValidator (new): A Spring bean (lazy-init="false") that eagerly validates at startup that woven attributes (e.g. archiveStatus) are visible in Hibernate's JPA metamodel. Registered in bl-common-applicationContext.xml.

⚠️ Items Requiring Careful Review

1. RuntimeException swallowing in enhancer — the new catch (RuntimeException e) returns null and logs at WARN with full stack trace. IllegalClassFormatException is properly re-thrown. This is still a behavioral change from the original code where all exceptions would propagate. Reviewers should confirm this fail-open behavior for runtime exceptions is acceptable.

2. Validator persistence unit name — the validator uses @PersistenceContext(unitName = "blPU"). Since the bean is now eagerly initialized (lazy-init="false"), a mismatched persistence unit name would cause a startup failure rather than a silent no-op. Confirm "blPU" matches the actual persistence unit name used in deployments.

3. Validator checks only archiveStatus — the COMMON_WOVEN_ATTRIBUTES array contains only one attribute. This provides a basic smoke test but won't catch issues with other woven fields like sandBoxDiscriminator or multiTenantDiscriminator. Consider whether additional attributes should be checked.

4. No runtime verification possible yet — the codebase is still on Hibernate 5.6.15.Final, so all compatibility analysis is theoretical. These changes cannot be validated against an actual Hibernate 6 runtime until the version is bumped.

Human Review Checklist

• Verify that catching RuntimeException while re-throwing IllegalClassFormatException is the right boundary for fail-open behavior
• Confirm @PersistenceContext(unitName = "blPU") matches the actual persistence unit name used in deployments
• Decide whether COMMON_WOVEN_ATTRIBUTES should include additional woven field names beyond archiveStatus

Additional Context

• Entities verified: ProductImpl, CategoryImpl, SkuImpl, CustomerImpl, OrderImpl, AdminUserImpl, PageImpl, StructuredContentImpl — all carry @DirectCopyTransform annotations and will receive woven fields.
• Key architectural finding: MergePersistenceUnitManager force-loads all managed classes before EntityManagerFactory creation, guaranteeing Javassist weaving completes before Hibernate's metamodel build. This ordering holds for both Hibernate 5.x and 6.x.
• ConditionalDirectCopyTransformersManager operates purely at the Spring configuration level with no Hibernate API dependency — confirmed compatible without changes.
• No DirectCopy infrastructure was removed or replaced per ticket constraints (that's Phase 3).

Link to Devin session: https://app.devin.ai/sessions/bd15110a14d449b5b66f5ab802995018
Requested by: @Colhodm

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring