Apache/activemq-artemis
1
0
Fork 0
mirror of https://github.com/apache/activemq-artemis.git synced 2025-02-13 21:46:07 +00:00
Code Issues Packages Projects Releases Wiki Activity
activemq-artemis/docs/user-manual/resource-adapter.adoc
Justin Bertram 3a4b421d2e ARTEMIS-4383 migrate user docs to AsciiDoc 
Markdown, which is currently used for user-facing documentation, is good
for a lot of things. However, it's not great for the kind of complex
documentation we have and our need to produce both multi-page HTML and
single-page PDF output via Maven.

Markdown lacks features which would make the documentation easier to
read, easier to navigate, and just look better overall.

The current tool-chain uses honkit and a tool called Calibre. Honkit is
written in TypeScript and is installed via NPM. Calibre is a native tool
so it must be installed via an OS-specific package manager. All this
complexity makes building, releasing, uploading, etc. a pain.

AsciiDoc is relatively simple like Markdown, but it has more features
for presentation and navigation not to mention Java-based Maven tooling
to generate both HTML and PDF. Migrating will improve both the
appearance of the documentation as well as the processes to generate and
upload it.

This commit contains the following changes:
 - Convert all the Markdown for the User Manual, Migration Guide, and
   Hacking guide to AsciiDoc via kramdown [1].
 - Update the `artemis-website` build to use AsciiDoctor Maven tooling.
 - Update `RELEASING.md` with simplified instructions.
 - Update Hacking Guide with simplified instructions.
 - Use AsciiDoc link syntax in Artemis Maven doc plugin.
 - Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
   Guide. All docs will be HTML only except for the User Manual which
   will have PDF.
 - Move all docs up out of their respective "en" directory. This was a
   hold-over from when we had docs in different languages.
 - Migration & Hacking Guides are now single-page HTML since they are
   relatively short.
 - Refactor README.md to simplify and remove redundant content.

Benefits of the change:
 - Much simplified tooling. No more NPM packages or native tools.
 - Auto-generated table of contents for every chapter.
 - Auto-generated anchor links for every sub-section.
 - Overall more appealing presentation.
 - All docs will use the ActiveMQ favicon.
 - No more manual line-wrapping! AsciiDoc recommends one sentence per
   line and paragraphs are separated by a blank line.
 - AsciiDoctor plugins for IDEA are quite good.
 - Resulting HTML is less than *half* of the previous size.

All previous links/bookmarks should continue to work.

[1] https://github.com/asciidoctor/kramdown-asciidoc
2023-08-02 16:21:06 -04:00

145 lines
5.3 KiB
Plaintext
Raw Blame History

= JCA Resource Adapter
:idprefix:
:idseparator: -
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:
* *Pooled* - 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).
* *Automatic enlistment into JTA transactions* - 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 `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).
== Versions
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
|===
== Building the RA
To use the RA you have to build it.
The simplest way to do this is with the examples is shipped with the distribution.
[,shell]
----
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.
== Configuration
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 https://github.com/apache/activemq-artemis/blob/{{ 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.
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.
=== ResourceAdapter
Config options https://github.com/apache/activemq-artemis/blob/{{ config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/ActiveMQRAProperties.java[ActiveMQRAProperties]
connectionParameters::
key value pairs, like host=localhost;port=61616,host=anotherHost;port=61617
userName::
userName
password::
password
clientID::
clientID
=== ConnectionFactory
Config options for the outbound `ManagedConnectionFactory`: https://github.com/apache/activemq-artemis/blob/{{ config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/ActiveMQRAMCFProperties.java[ActiveMQRAMCFProperties] The connection for the `ManagedConnectionFactory` is specified by the RA.
Config options for the inbound `ConnectionFactory` https://github.com/apache/activemq-artemis/blob/{{ config.version }}/artemis-jms-client/src/main/java/org/apache/activemq/artemis/jms/client/ActiveMQConnectionFactory.java[ActiveMQConnectionFactory]
brokerUrl::
url to broker
cacheDestinations::
by the jms session
==== ConnectionManager
You can't configure any properties.
=== ActivationSpec
Config options https://github.com/apache/activemq-artemis/blob/{{ config.version }}/artemis-ra/src/main/java/org/apache/activemq/artemis/ra/inflow/ActiveMQActivationSpec.java[ActiveMQActivationSpec]
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=f`
destination::
name or JNDI reference of the JMS destination
destinationType::
`[javax|jakarta].jms.Queue` or `[javax|jakarta].jms.Topic`
messageSelector::
JMS selector to filter messages to your MDB
maxSession::
to consume messages in parallel from the broker
==== Only for topic message consumption
subscriptionDurability::
Durable / NonDurable
subscriptionName::
Artemis holds all messages for this name if you use durable subscriptions
== Logging
With the package `org.apache.activemq.artemis.ra` you catch all ResourceAdapter logging statements.
Reference in New Issue View Git Blame Copy Permalink