| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.18"> |
| <link rel="icon" type="image/png" href="images/favicon.png"> |
| <title>JCA Resource Adapter</title> |
| <link rel="stylesheet" href="css/asciidoctor.css"> |
| <link rel="stylesheet" href="css/font-awesome.css"> |
| <link rel="stylesheet" href="css/rouge-github.css"> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>JCA Resource Adapter</h1> |
| <div id="toc" class="toc2"> |
| <div id="toctitle"><a href="index.html">User Manual for 2.32.0</a></div> |
| <ul class="sectlevel1"> |
| <li><a href="#versions">1. Versions</a></li> |
| <li><a href="#building-the-ra">2. Building the RA</a></li> |
| <li><a href="#configuration">3. Configuration</a> |
| <ul class="sectlevel2"> |
| <li><a href="#resourceadapter">3.1. ResourceAdapter</a></li> |
| <li><a href="#connectionfactory">3.2. ConnectionFactory</a></li> |
| <li><a href="#activationspec">3.3. ActivationSpec</a></li> |
| </ul> |
| </li> |
| <li><a href="#logging">4. Logging</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>For using Apache ActiveMQ Artemis in a Java EE or Jakarta EE environment, you can use the JCA Resource Adapter.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A JCA-based JMS connection factory has 2 big advantages over a plain JMS connection factory:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Pooled</strong> - Generally speaking, when a connection is "created" from a JCA-based JMS connection factory the underlying physical connection is taken out of a pool and when the connection is "closed" the underlying physical connection is returned to the pool. |
| This eliminates the performance penalty of actually creating and destroying the physical connection which allows clients to be written in ways that would normally be considered an anti-pattern (e.g. "creating" and "closing" a connection for every sent message).</p> |
| </li> |
| <li> |
| <p><strong>Automatic enlistment into JTA transactions</strong> - Most of the time applications which consume JMS messages in a Java/Jakarta EE context do so via an MDB. |
| By default, the consumption of the message in an MDB (i.e. the execution of <code>onMessage</code>) 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).</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="versions"><a class="anchor" href="#versions"></a><a class="link" href="#versions">1. Versions</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Pick the right version of the resource adapter depending on your environment.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3334%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"></th> |
| <th class="tableblock halign-left valign-top">artemis-ra-rar</th> |
| <th class="tableblock halign-left valign-top"></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Java EE</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">JCA</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">JMS</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">1.7</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">2.0</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3334%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"></th> |
| <th class="tableblock halign-left valign-top">artemis-jakarta-ra-rar</th> |
| <th class="tableblock halign-left valign-top"></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Jakarta EE</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">JCA</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">JMS</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">>= 9</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">2.0</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">3.0</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="building-the-ra"><a class="anchor" href="#building-the-ra"></a><a class="link" href="#building-the-ra">2. Building the RA</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>To use the RA you have to build it. |
| The simplest way to do this is with the <a href="examples.html">examples</a>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="shell"><span class="nb">cd </span>examples/features/sub-modules/<span class="o">{</span>artemis-jakarta-ra-rar,artemis-ra-rar<span class="o">}</span> |
| mvn clean <span class="nb">install |
| cd </span>target |
| <span class="nb">mv </span>artemis<span class="k">*</span>.rar artemis.rar</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Follow the manual of your application server to install the <code>artemis.rar</code> JCA RA archive.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="configuration"><a class="anchor" href="#configuration"></a><a class="link" href="#configuration">3. Configuration</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Here are a few options listed. |
| If you want an overview of all configuration options, consider <a href="https://github.com/apache/activemq-artemis/blob/{{" class="bare">https://github.com/apache/activemq-artemis/blob/{{</a> config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/ConnectionFactoryProperties.java[ConnectionFactoryProperties] as a base and additionally the specific classes for your object.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Consider also the <code>rar.xml</code> file for options and explanations in your <code>artemis.rar</code>. |
| There you can set the default options for your ResourceAdapter. |
| With the configuration of the ResourceAdapter in your application server, you are overriding <code>rar.xml</code> defaults. |
| With the configuration of the ConnectionFactory or the ActivationSpec, you can override the ResourceAdapter config.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="resourceadapter"><a class="anchor" href="#resourceadapter"></a><a class="link" href="#resourceadapter">3.1. ResourceAdapter</a></h3> |
| <div class="paragraph"> |
| <p>Config options <a href="https://github.com/apache/activemq-artemis/blob/{{" class="bare">https://github.com/apache/activemq-artemis/blob/{{</a> config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/ActiveMQRAProperties.java[ActiveMQRAProperties]</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">connectionParameters</dt> |
| <dd> |
| <p>key value pairs, like host=localhost;port=61616,host=anotherHost;port=61617</p> |
| </dd> |
| <dt class="hdlist1">userName</dt> |
| <dd> |
| <p>userName</p> |
| </dd> |
| <dt class="hdlist1">password</dt> |
| <dd> |
| <p>password</p> |
| </dd> |
| <dt class="hdlist1">clientID</dt> |
| <dd> |
| <p>clientID</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="connectionfactory"><a class="anchor" href="#connectionfactory"></a><a class="link" href="#connectionfactory">3.2. ConnectionFactory</a></h3> |
| <div class="paragraph"> |
| <p>Config options for the outbound <code>ManagedConnectionFactory</code>: <a href="https://github.com/apache/activemq-artemis/blob/{{" class="bare">https://github.com/apache/activemq-artemis/blob/{{</a> config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/ActiveMQRAMCFProperties.java[ActiveMQRAMCFProperties] The connection for the <code>ManagedConnectionFactory</code> is specified by the RA.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Config options for the inbound <code>ConnectionFactory</code> <a href="https://github.com/apache/activemq-artemis/blob/{{" class="bare">https://github.com/apache/activemq-artemis/blob/{{</a> config.version }}/artemis-jms-client/src/main/java/org/apache/activemq/artemis/jms/client/ActiveMQConnectionFactory.java[ActiveMQConnectionFactory]</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">brokerUrl</dt> |
| <dd> |
| <p>url to broker</p> |
| </dd> |
| <dt class="hdlist1">cacheDestinations</dt> |
| <dd> |
| <p>by the jms session</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="sect3"> |
| <h4 id="connectionmanager"><a class="anchor" href="#connectionmanager"></a><a class="link" href="#connectionmanager">3.2.1. ConnectionManager</a></h4> |
| <div class="paragraph"> |
| <p>You can’t configure any properties.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="activationspec"><a class="anchor" href="#activationspec"></a><a class="link" href="#activationspec">3.3. ActivationSpec</a></h3> |
| <div class="paragraph"> |
| <p>Config options <a href="https://github.com/apache/activemq-artemis/blob/{{" class="bare">https://github.com/apache/activemq-artemis/blob/{{</a> config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/inflow/ActiveMQActivationSpec.java[ActiveMQActivationSpec]</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the activation spec you can configure all the things you need to get messages consumed from ActiveMQ Artemis.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">useJndi</dt> |
| <dd> |
| <p>true if you want lookup destinations via jndi.</p> |
| </dd> |
| <dt class="hdlist1">connectionFactoryLookup</dt> |
| <dd> |
| <p>the jndiName of the connectionFactory, used by this activation spec. |
| You can reference an existing ManagedConnectionFactory or specify another.</p> |
| </dd> |
| <dt class="hdlist1">jndiParams</dt> |
| <dd> |
| <p>for the InitialContext. |
| key value pairs, like <code>a=b;c=d;e=f</code></p> |
| </dd> |
| <dt class="hdlist1">destination</dt> |
| <dd> |
| <p>name or JNDI reference of the JMS destination</p> |
| </dd> |
| <dt class="hdlist1">destinationType</dt> |
| <dd> |
| <p><code>[javax|jakarta].jms.Queue</code> or <code>[javax|jakarta].jms.Topic</code></p> |
| </dd> |
| <dt class="hdlist1">messageSelector</dt> |
| <dd> |
| <p>JMS selector to filter messages to your MDB</p> |
| </dd> |
| <dt class="hdlist1">maxSession</dt> |
| <dd> |
| <p>to consume messages in parallel from the broker</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="sect3"> |
| <h4 id="only-for-topic-message-consumption"><a class="anchor" href="#only-for-topic-message-consumption"></a><a class="link" href="#only-for-topic-message-consumption">3.3.1. Only for topic message consumption</a></h4> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">subscriptionDurability</dt> |
| <dd> |
| <p>Durable / NonDurable</p> |
| </dd> |
| <dt class="hdlist1">subscriptionName</dt> |
| <dd> |
| <p>Artemis holds all messages for this name if you use durable subscriptions</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="logging"><a class="anchor" href="#logging"></a><a class="link" href="#logging">4. Logging</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>With the package <code>org.apache.activemq.artemis.ra</code> you catch all ResourceAdapter logging statements.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
