FISH-12307 : Add migration advice for Jakarta Persistence 3.2 EntityManager injection ambiguity (FISH-11759)

[luiseufrasio]

Summary

This PR adds migration advice to detect and help resolve the EntityManager injection ambiguity issue that occurs when migrating to Jakarta EE 11 (Jakarta Persistence 3.2).

This issue was identified in FISH-11759: Ambiguous EntityManager Injection Error in Payara 7.2025.1.Alpha3 (Works in Alpha2).

Problem Description

In Jakarta EE 11, the CDI specification now provides a default EntityManager producer through PersistenceExtension. When applications have custom @Produces methods for EntityManager without a qualifier, this causes a WELD-001409 ambiguous dependency error during deployment because CDI cannot determine which producer to use:

1. The platform's built-in producer (PersistenceExtension)
2. The application's custom producer

This pattern worked in Jakarta EE 10 and earlier but breaks in EE 11.

Changes Made

1. Detection Pattern

• File: src/main/resources/config/jakarta11/mappedPatterns/jakarta-persistence.properties
• Pattern Key: jakarta-persistence-interface-persistencecontext-cdi-ambiguous-warn
• Detects: Usage of @PersistenceContext annotation that may indicate problematic producer patterns

2. Advisory Message

• File: src/main/resources/config/jakarta11/advisorMessages/jakarta-persistence-messages.properties
• Explains:
  • The CDI ambiguity introduced by EE11's default EntityManager producer
  • Reference to WELD-001409 error
  • Impact on applications with custom producers

3. Fix Recommendations

• File: src/main/resources/config/jakarta11/advisorFix/jakarta-persistence-fix-messages.properties
• Provides three migration options:
  1. RECOMMENDED: Remove custom EntityManager producers and use @Inject EntityManager directly (EE11 supports this natively)
  2. Add a @Qualifier annotation to custom producers to make them distinct
  3. Move @PersistenceContext directly to injection points instead of using producers

Testing & Reproduction

Prerequisites

# Install the updated plugin locally
cd AdvisorTool
mvn clean install

Reproducing with Example Project

The issue can be reproduced using the example project at:
https://github.com/breakponchito/AdvisorReproducerExamples.git

# Clone the reproducer project
git clone https://github.com/breakponchito/AdvisorReproducerExamples.git
cd AdvisorReproducerExamples

# Run the advisor plugin
mvn fish.payara.advisor:advisor-maven-plugin:2.0-SNAPSHOT:advise -Dadvisor-plugin.adviseVersion=11

Example Files in Reproducer

The reproducer includes two example files demonstrating the problematic pattern:

1. EntityManagerProducer.java - Shows the OLD pattern that causes ambiguity:

   @RequestScoped
   public class EntityManagerProducer {
       @Produces
       @PersistenceContext(unitName = "myPU")
       private EntityManager em;
   }

2. EventService.java - Shows where the injection fails:

   @ApplicationScoped
   public class EventService {
       @Inject  // This will cause WELD-001409 error
       private EntityManager em;
   }

Expected Output

When running the advisor on the reproducer project, you should see warnings like:

[WARNING] Line of code: 6 | Expression: jakarta.persistence.PersistenceContext
Source file: EntityManagerProducer.java
Jakarta Persistence 3.2 (Jakarta EE 11) 
 In Jakarta EE 11, CDI now provides a default EntityManager producer through PersistenceExtension.
 If you have a custom @Produces method for EntityManager without a qualifier, this can cause an ambiguous
 dependency error (WELD-001409). The old pattern of creating EntityManager producers with @PersistenceContext
 may conflict with the platform's built-in producer.
To avoid ambiguous dependency errors, consider these options: 
 1. RECOMMENDED: Remove custom EntityManager @Produces methods and use @Inject EntityManager directly.
    Jakarta EE 11 supports direct injection without custom producers.
 2. If you need custom logic, add a @Qualifier annotation to your @Produces method to make it distinct.
 3. Move @PersistenceContext directly to the injection point instead of using a producer.
 See: https://payara.atlassian.net/browse/FISH-11759

Related Issues

• FISH-11759: Investigation: Ambiguous EntityManager Injection Error in 7.2025.1.Alpha3 (Works in Alpha2)
• Root Cause: New CDI behavior introduced in Jakarta EE 11 for JPA integration
• Reference PR: FISH-11785 Fix EntityManager template to support Payara 7.2025.1.Alpha3 ecosystem-starter#135 (shows the fix applied in Payara Starter)

Impact

• Severity: WARNING (non-blocking but important for successful EE11 migration)
• Affected Applications: Applications with custom EntityManager producers using @PersistenceContext
• Jakarta EE Version: 11+ (Jakarta Persistence 3.2+)

Migration Path

This advisory helps developers proactively identify and fix potential deployment issues before upgrading to Jakarta EE 11 / Payara 7.2025.1.Alpha3+.

[breakponchito]

I think the level for the message should need to be as error because the application won't be functional if you don't fix the ambiguity

[stian-sigvartsen]

This PR looks good overall. I agree with @breakponchito 's comment about promoting that warning to error.

[breakponchito]

LGTM