Document XA transaction limitations with MessageListener and provide correct consumption patterns

[Copilot]

Issue #372 reports messages "disappearing" when exceptions occur in a MessageListener with XA transactions enabled. This is not a bug—MessageListener.onMessage() callbacks execute on JMS provider threads outside managed transaction boundaries. Combined with AUTO_ACKNOWLEDGE mode, messages are acknowledged before processing, so exceptions cannot trigger rollback.

Changes

Documentation (index.adoc)

• Added "Consuming Messages with XA Transactions" section explaining MessageListener limitations
• Documented correct synchronous consumption pattern using @Transactional with SESSION_TRANSACTED
• Provided three alternative approaches: synchronous consumption (recommended), manual transaction management, and scheduled polling
• Added warning about AUTO_ACKNOWLEDGE bypassing transaction control

Testing (PooledXAMessageListenerTest.java)

• Integration test demonstrating correct XA message consumption pattern
• Validates transaction rollback behavior and message redelivery

Correct Usage Pattern

@ApplicationScoped
public class MessageProcessor {
    @Inject ConnectionFactory connectionFactory;
    
    @Scheduled(every = "1s")
    @Transactional
    public void processMessages() {
        try (JMSContext context = connectionFactory.createContext(Session.SESSION_TRANSACTED);
             JMSConsumer consumer = context.createConsumer(context.createQueue("myQueue"))) {
            
            Message message = consumer.receiveNoWait();
            if (message != null) {
                // Exception here triggers XA rollback and message redelivery
                processMessage(message);
            }
        }
    }
}

For true async processing with automatic transaction management, users should use quarkus-artemis-jms-ra (JCA-based MDB support).

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• 172.19.0.1
  • Triggering command: REDACTED, pid is -1 (packet block)
• 172.20.0.1
  • Triggering command: REDACTED, pid is -1 (packet block)
• repo.gradle.org
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --enable-native-access=ALL-UNNAMED -classpath /usr/share/apache-maven-3.9.12/boot/plexus-classworlds-2.9.0.jar -Dclassworlds.conf=/usr/share/apache-maven-3.9.12/bin/m2.conf -Dmaven.home=/usr/share/apache-maven-3.9.12 -Dlibrary.jansi.path=/usr/share/apache-maven-3.9.12/lib/jansi-native -Dmaven.multiModuleProjectDirectory=/home/REDACTED/work/quarkus-pooled-jms/quarkus-pooled-jms/integration-tests/artemis-jms org.codehaus.plexus.classworlds.launcher.Launcher test -Dtest=PooledXAMessageListenerTest (dns block)
• repository.jboss.org
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --enable-native-access=ALL-UNNAMED -classpath /usr/share/apache-maven-3.9.12/boot/plexus-classworlds-2.9.0.jar -Dclassworlds.conf=/usr/share/apache-maven-3.9.12/bin/m2.conf -Dmaven.home=/usr/share/apache-maven-3.9.12 -Dlibrary.jansi.path=/usr/share/apache-maven-3.9.12/lib/jansi-native -Dmaven.multiModuleProjectDirectory=/home/REDACTED/work/quarkus-pooled-jms/quarkus-pooled-jms/integration-tests/artemis-jms org.codehaus.plexus.classworlds.launcher.Launcher test -Dtest=PooledXAMessageListenerTest (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.