For using Apache ActiveMQ Artemis in a Java EE or Jakarta EE environment, you can use the JCA Resource Adapter.
A JCA-based JMS connection factory has 2 big advantages over a plain JMS connection factory:
onMessage
) happens within a JTA transaction. If a JCA-based JMS connection factory is used in the course of the MDB's processing (e.g. to send a message) then the JCA logic will automatically enlist the session into the JTA transaction so that the consumption of the message and the sending of the message are an atomic operation (assuming that the JCA-based connection factory is XA capable). This is also true for operations involving other transactional resources (e.g. a database).Pick the right version of the resource adapter depending on your environment.
artemis-ra-rar | ||
---|---|---|
Java EE | JCA | JMS |
8 | 1.7 | 2.0 |
artemis-jakarta-ra-rar | ||
---|---|---|
Jakarta EE | JCA | JMS |
>= 9 | 2.0 | 3.0 |
To use the RA you have to build it. The simplest way to do this is with the examples is shipped with the distribution.
cd examples/features/sub-modules/{artemis-jakarta-ra-rar,artemis-ra-rar} mvn clean install cd target mv artemis*.rar artemis.rar
Follow the manual of your application server to install the artemis.rar
JCA RA archive.
The configuration is split into two parts. First the config to send messages to a destination (outbound), and second the config to get messages consumed from a destination (inbound). Each can be configured separately or both can use the ResourceAdapter settings.
Here are a few options listed. If you want an overview of all configuration options, consider [ConnectionFactoryProperties](https://github.com/apache/activemq-artemis/blob/{{ config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/ConnectionFactoryProperties.java) as a base and additionally the specific classes for your object.
Consider also the rar.xml
file for options and explanations in your artemis.rar
. There you can set the default options for your ResourceAdapter. With the configuration of the ResourceAdapter in your application server, you are overriding rar.xml
defaults. With the configuration of the ConnectionFactory or the ActivationSpec, you can override the ResourceAdapter config.
Config options [ActiveMQRAProperties](https://github.com/apache/activemq-artemis/blob/{{ config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/ActiveMQRAProperties.java)
connectionParameters
key value pairs, like host=localhost;port=61616,host=anotherHost;port=61617userName
userNamepassword
passwordclientID
clientIDConfig options for the outbound ManagedConnectionFactory
: [ActiveMQRAMCFProperties](https://github.com/apache/activemq-artemis/blob/{{ config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/ActiveMQRAMCFProperties.java) The connection for the ManagedConnectionFactory
is specified by the RA.
Config options for the inbound ConnectionFactory
[ActiveMQConnectionFactory](https://github.com/apache/activemq-artemis/blob/{{ config.version }}/artemis-jms-client/src/main/java/org/apache/activemq/artemis/jms/client/ActiveMQConnectionFactory.java)
brokerUrl
url to broker.cacheDestinations
by the jms sessionYou can't configure any properties.
Config options [ActiveMQActivationSpec](https://github.com/apache/activemq-artemis/blob/{{ config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/inflow/ActiveMQActivationSpec.java)
In the activation spec you can configure all the things you need to get messages consumed from ActiveMQ Artemis.
useJndi
true if you want lookup destinations via jndi.connectionFactoryLookup
the jndiName of the connectionFactory, used by this activation spec. You can reference an existing ManagedConnectionFactory or specify another.jndiParams
for the InitialContext. key value pairs, like a=b;c=d;e=fdestination
name or JNDI reference of the JMS destinationdestinationType
javax/jakarta.jms.Queue or javax/jakarta.jms.TopicmessageSelector
JMS selector to filter messages to your MDBmaxSession
to consume messages in parallel from the brokersubscriptionDurability
Durable / NonDurablesubscriptionName
artemis hold all messages for this name if you use durable subscriptionsWith the package org.apache.activemq.artemis.ra
you catch all ResourceAdapter logging statements.