1.2. Install the ActiveMQ Resource Adapter

Overview

This section describes how to find, install, and configure the ActiveMQ resource adapter into a standalone instance of the JBoss EAP.
A resource adapter is a kind of plug-in for a Java EE container. The Java EE standard defines the resource adapter framework, which makes it possible to expand the core Java EE container, adding new features and functionality. By installing the ActiveMQ resource adapter, you make it possible for message driven beans and servlets to communicate through an external JBoss A-MQ broker instance. The JBoss A-MQ broker can thus be used as the underlying messaging system in the container.
Note
Running an embedded ActiveMQ broker in JBoss EAP is not supported. The use of the resource adapter is restricted to connect to external broker instances only.

Resource adapter location

You can find the ActiveMQ resource adapter archive file, activemq-rar-5.11.0.redhat-630187.rar, at either of the following locations:
  • In the following Zip archive file:
    InstallDir/extras/apache-activemq-5.11.0.redhat-630187-bin.zip
    After expanding the archive, the resource adapter file can be found in the following sub-directory:
    apache-activemq-5.11.0.redhat-630187/lib/optional
  • Directly from the Red Hat JBoss Fuse Maven repository, at the following URL:
    https://maven.repository.redhat.com/ga/org/apache/activemq/activemq-rar/
    Download the .rar archive file from the appropriately versioned sub-directory, 5.11.0.redhat-630187.

Configuration files

The following configuration files are needed for the the ActiveMQ resource adapter (when installed in a standalone instance of the JBoss EAP):
InstallDir/standalone/configuration/standalone-full.xml
The standalone-full.xml file is the default (bare bones) configuration for the JBoss EAP container. You must edit this file to complete the installation of the ActiveMQ resource adapter.
Note
It is assumed that this file does not already configure the HornetQ messaging system (which would conflict with the ActiveMQ messaging system).
Note
JBoss EAP can be figured either as a standalone container, using standalone/configuration/standalone-full.xml, or as a managed domain, using domain/configuration/domain.xml. Throughout this section, we describe explicitly how to configure the standalone container, but it is understood that a similar approach could be used to configure a managed domain.

Steps to install the resource adapter

Perform the following steps to install the Apache ActiveMQ resource adapter into JBoss EAP (assuming that you will be running the container in standalone mode):
  1. Extract the Apache ActiveMQ community distribution. You can find an archive of the Apache ActiveMQ distribution in the following location:
    InstallDir/extras/apache-activemq-5.11.0.redhat-630187-bin.zip
    Using a suitable archive utility, extract the archive file to a convenient location on your filesystem. The root of the extracted directory tree is called apache-activemq-5.11.0.redhat-630187 by default.
  2. The ActiveMQ resource adapter archive file can now be found under the /lib/optional sub-directory of the extracted archive.
    If you need to use the ActiveMQXAConnectionFactory, you need to add extra details to the ActiveMQ resource adapter file at this point. Extract the resource adapter archive, activemq-rar-5.11.0.redhat-630187.rar to a work space. In the expanded resource adapter archive, edit META_INF/ra.xml.
    Add the following entry to the adminobjects in the ra.xml file.
    <adminobject>
    <adminobject-interface>javax.jms.XAConnectionFactory</adminobject-interface>
    <adminobject-class>org.apache.activemq.ActiveMQXAConnectionFactory</adminobject-class>
    <config-property>
    <config-property-name>brokerURL</config-property-name>
    <config-property-type>java.lang.String</config-property-type>
    </config-property>
    </adminobject>
    Zip up the resource adapter archive, and save it to a temporary location.
  3. Rename the updated and saved resource adapter archive file. The new file name should be the same as the original name, but without the version number in the filename. For example, on a UNIX or Linux platform, you can rename the activemq-rar-5.11.0.redhat-630187.rar archive file to activemq-rar.rar
    Note
    Renaming the resource adapter archive in this way is not strictly necessary. But because the resource adapter file name appears in the resource adapter configuration, using a versionless filename makes it easier to upgrade the resource adapter at a later date.
  4. Install the ActiveMQ resource adapter by copying the resource adapter archive, activemq-rar.rar, to the relevant JBoss EAP deployment directory. For example, on a UNIX or Linux platform, you could copy the resource adapter archive to a standalone JBoss Enterprise Application Platform as follows:
    cp activemq-rar.rar EAPInstallDir/standalone/deployments/
  5. Add the requisite resource adapter configuration to the urn:jboss:domain:resource-adapters:1.1 subsystem in the JBoss EAP configuration, as follows.
    Open the EAPInstallDir/standalone/configuration/standalone-full.xml file using a text editor and paste the resource-adapter element from Example 1.1, “ActiveMQ Resource Adapter Configuration in standalone-full.xml” into the urn:jboss:domain:resource-adapters:1.1 subsystem, as a child of the resource-adapters element.

    Example 1.1. ActiveMQ Resource Adapter Configuration in standalone-full.xml

    <server xmlns="urn:jboss:domain:1.4">
        ...
        <profile>
            ...
            <subsystem xmlns="urn:jboss:domain:resource-adapters:1.1">
                <resource-adapters>
                    <resource-adapter id="activemq-rar.rar">
                        <archive>
                            activemq-rar.rar
                        </archive>
                        <transaction-support>XATransaction</transaction-support>
                        <config-property name="UserName">
                            defaultUser
                        </config-property>
                        <config-property name="Password">
                            defaultPassword
                        </config-property>
                        <config-property name="ServerUrl">
                            tcp://localhost:61616?jms.rmIdFromConnectionId=true
                        </config-property>
                        <connection-definitions>
                            <connection-definition
                                  class-name="org.apache.activemq.ra.ActiveMQManagedConnectionFactory"
                                  jndi-name="java:/ConnectionFactory"
                                  enabled="true"
                                  pool-name="ConnectionFactory"
    			      tracking="false">
                                <xa-pool>
                                    <min-pool-size>1</min-pool-size>
                                    <max-pool-size>20</max-pool-size>
                                    <prefill>false</prefill>
                                    <is-same-rm-override>false</is-same-rm-override>
                                </xa-pool>
                                <recovery>  
                                    <recover-credential>  
                                        <user-name>defaultUser</user-name>
                                        <password>defaultPassword</password>
                                    </recover-credential>
                                </recovery>
                            </connection-definition>
                        </connection-definitions>
                        <admin-objects>
                            <admin-object
                                  class-name="org.apache.activemq.command.ActiveMQQueue"
                                  jndi-name="java:/queue/HELLOWORLDMDBQueue"
                                  use-java-context="true"
                                  pool-name="HELLOWORLDMDBQueue">
                                <config-property name="PhysicalName">
                                    HELLOWORLDMDBQueue
                                </config-property>
                            </admin-object>
                            <admin-object
                                  class-name="org.apache.activemq.command.ActiveMQTopic"
                                  jndi-name="java:/topic/HELLOWORLDMDBTopic"
                                  use-java-context="true"
                                  pool-name="HELLOWORLDMDBTopic">
                                <config-property name="PhysicalName">
                                    HELLOWORLDMDBTopic
                                </config-property>
                            </admin-object>
                        </admin-objects>
                    </resource-adapter>
                    ...
                </resource-adapters>
            </subsystem>
            ...
        </profile>
        ...
    </server>
    If you need to use the ActiveMQXAConnectionFactory, you must also add the following information to the admin-object section of standalone-full.xml.
    <admin-object class-name="org.apache.activemq.ActiveMQXAConnectionFactory" jndi-name="java:/AMQXAConnectionFactory" enabled="true" use-java-context="true" pool-name="AMQXAConnectionFactory">
    <config-property name="brokerURL">
    tcp://localhost:61616?jms.rmIdFromConnectionId=true
    </config-property>
    </admin-object>
    
    If your resource adapter archive filename differs from activemq-rar.rar, you must change the content of the archive element in the preceding configuration to match the name of your archive file.
    The values of the UserName and Password configuration properties must be chosen to match the credentials of a valid user in the external broker.
    You might need to change the value of the ServerUrl configuration property to match the actual hostname and port exposed by the external broker.
    Important
    In order to ensure that JMS transactions are integrated correctly, it is essential to include the jms.rmIdFromConnectionId=true option setting on the ServerUrl configuration property and to include the <is-same-rm-override>false</is-same-rm-override> setting in the xa-pool element, as shown above.
    Note
    The JMS administrative objects defined in the admin-objects element do not need to be defined yet. They serve as examples to show how you can define administrative objects for the ActiveMQ resource adapter (they are used later in the message-driven bean demonstration).
  6. Add the requisite message driven bean configuration to the urn:jboss:domain:ejb3:1.5 subsystem in the JBoss EAP configuration (where the subsystem version might vary, depending on which version of JBoss EAP you are using).
    Open the EAPInstallDir/standalone/configuration/standalone-full.xml file using a text editor and paste the mdb element from Example 1.2, “Message Driven Bean Configuration in standalone-full.xml” into the urn:jboss:domain:ejb3:1.5 subsystem.

    Example 1.2. Message Driven Bean Configuration in standalone-full.xml

    <server xmlns="urn:jboss:domain:1.4">
        ...
        <profile>
            ...
            <subsystem xmlns="urn:jboss:domain:ejb3:1.5">
                ...
                <mdb>
                    <resource-adapter-ref resource-adapter-name="activemq-rar.rar"/>
                    <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
                </mdb>
                <pools>
                    <bean-instance-pools>
                        <strict-max-pool name="slsb-strict-max-pool" max-pool-size="20" instance-acquisition-timeout="5" instance-acquisition-timeout-unit="MINUTES"/>
                        <strict-max-pool name="mdb-strict-max-pool" max-pool-size="20" instance-acquisition-timeout="5" instance-acquisition-timeout-unit="MINUTES"/>
                    </bean-instance-pools>
                </pools>
                ...
            </subsystem>
            ...
        </profile>
        ...
    </server>
  7. Before starting the broker, check the broker configuration to make sure that there are valid user credentials defined in the broker's InstallDir/etc/users.properties file. For example, to match the UserName and Password credentials configured in Example 1.1, “ActiveMQ Resource Adapter Configuration in standalone-full.xml”, the users.properties file should contain an entry like the following:
    defaultUser=defaultPassword,admin
  8. Start the external A-MQ broker. For example, on a UNIX or Linux platform, you can start the JBoss A-MQ broker instance as follows:
    cd InstallDir/bin
    ./amq
  9. Start the standalone instance of JBoss EAP. For example, on a UNIX or Linux platform, you can start the standalone instance as follows:
    cd EAPInstallDir/bin
    ./standalone-full.sh

Steps to secure the resource adapter with SSL/TLS

The following steps describe how to modify the configuration of the ActiveMQ resource adapter to enable it to connect to a broker that is secured by an SSL/TLS protocol:
  1. It is assumed that the remote broker is already configured with an SSL/TLS endpoint. For details of how to configure an OpenWire/SSL endpoint on the broker, see section "Setting Security Context for the Openwire/SSL Protocol" in "Security Guide".
  2. Open the EAPInstallDir/standalone/configuration/standalone-full.xml file using a text editor and modify the ServerUrl property setting of the activemq-rar.rar resource adapter to point at the remote broker's OpenWire/SSL endpoint. For example:
    <resource-adapter id="activemq-rar.rar">
        ...
        <config-property name="ServerUrl">
            ssl://localhost:61617?jms.rmIdFromConnectionId=true
        </config-property>
        ...
    </resource-adapter>
    Where the ssl scheme selects the OpenWire/SSL protocol and localhost:61617 should be customized to the host and port value of the remote broker's secure endpoint.
  3. Specify the location and password for a trust store file, which will be used to verify the broker's certificate during the SSL/TLS handshake. Add the following property settings to the activemq-rar.rar resource adapter configuration and the org.apache.activemq.ra.ActiveMQManagedConnectionFactory connection definition configuration. Customize the settings as appropriate:
    <resource-adapter id="activemq-rar.rar">
        ...
        <config-property name="TrustStore">
            /opt/apache-activemq-5.11.0.redhat-630187/conf/truststore.ks
        </config-property>
        <config-property name="TrustStorePassword">
            password
        </config-property>
        ...
        <connection-definitions>
           <connection-definition class-name="org.apache.activemq.ra.ActiveMQManagedConnectionFactory" 
                 jndi-name="java:/ConnectionFactory" enabled="true" tracking="false" 
                 pool-name="ConnectionFactory">
                 ...
               <config-property name="TrustStore">
                   /opt/apache-activemq-5.11.0.redhat-630187/conf/truststore.ks
               </config-property>
               <config-property name="TrustStorePassword">
                   password
               </config-property>
               ...
          </connection-definition>
        </connection-definitions>
      </resource-adapter>
      ...
    
    
    
  4. (Optional) If the remote broker has also been configured to require a client certificate, then it is necessary to configure the ActiveMQ resource adapter with a key store file containing a public/private key pair. In this case, you need to add the following property settings to the activemq-rar.rar resource adapter configuration and the org.apache.activemq.ra.ActiveMQManagedConnectionFactory connection definition configuration. Customize the settings as appropriate:
    <resource-adapter id="activemq-rar.rar">
        ...
        <config-property name="KeyStore">
            /opt/apache-activemq-5.11.0.redhat-630187/conf/keystore.ks
        </config-property>
        <config-property name="KeyStorePassword">
            password
        </config-property>
        ...
          <connection-definitions>
              <connection-definition class-name="org.apache.activemq.ra.ActiveMQManagedConnectionFactory" 
                    jndi-name="java:/ConnectionFactory" enabled="true" tracking="false" 
                    pool-name="ConnectionFactory">
                  ...
                  <config-property name="KeyStore">
                    /opt/apache-activemq-5.11.0.redhat-630187/conf/keystore.ks
                  </config-property>
                  <config-property name="KeyStorePassword">
                    password
                  </config-property>
              </connection-definition>
          </connection-definitions>
        ...
    </resource-adapter>
    Note
    In order for the resource adapter's certificate (the public key from the key store) to be accepted by the broker it is necessary for this certificate to be trusted by the broker. This can be achieved either by adding the resource adapter's certificate to the broker's trust store or by arranging to have the resource adapter's certificate signed by one of the certificates in the broker's trust store. For more background information on certificate signing and trust, see appendix "Managing Certificates" in "Security Guide".

Resource adapter configuration

In the configuration shown in Example 1.1, “ActiveMQ Resource Adapter Configuration in standalone-full.xml”, you use the config-property element to set resource adapter properties. The ActiveMQ resource adapter supports the following basic properties:
UserName
(Optional) Specifies the client username when connecting to the JBoss A-MQ broker (not required in this example, because the JBoss A-MQ broker configuration does not enable authentication).
Password
(Optional) Specifies the client password when connecting to the JBoss A-MQ broker (not required in this example, because the JBoss A-MQ broker configuration does not enable authentication).
ServerUrl
Specifies the URL used to connect to the JBoss A-MQ broker instance. This value must match one of the endpoints specified by a transportConnector element in the JBoss A-MQ broker configuration.
BrokerXmlConfig
(Optional) Specifies the location of an embedded broker's XML configuration file. To specify a location on the file system, use the format, xbean:file://AbsolutePath, where the path, AbsolutePath, should be specified as an absolute pathname.
Note
This property is used to run an embedded ActiveMQ broker within resource adapter. Please note that running an embedded ActiveMQ broker in JBoss EAP is currently not supported.
UseInboundSession
(Optional) Sets a flag that specifies whether outbound connections should reuse the inbound connection's session for sending messages (useful for connections going through a firewall). Defaults to false.
Clientid
(Optional) Specifies a JMS client ID, which the resource adapter uses for the connection from the JBoss EAP container.
TrustStore
Specifies the location of a trust store file, using an absolute pathname. The trust store is required, if the ActiveMQ resource adapter connects to the broker using an SSL/TLS protocol. The trust store is provided in the form of a Java keystore file, which can contain one or multiple trusted certificates.
TrustStorePassword
Specifies the password for accessing the trust store file.
KeyStore
Specifies the location of a key store file, using an absolute pathname. The key store is required, if the ActiveMQ resource adapter connects to the broker using and SSL/TLS protocol and the remote broker is also configured to require a client certificate. The key store is provided in the form of a Java keystore file, which contains a single public/private key pair.
KeyStorePassword
Specifies the password that is used both for accessing the key store file and for unencrypting the private key entry (it is a common convention to use the same password for locking the keystore file and for encrypting the private key entry).

JBoss A-MQ broker configuration

Most of the options for customizing the ActiveMQ broker are provided by the JBoss A-MQ broker configuration file, at the following location:
InstallDir/etc/activemq.xml
This configuration file supports a huge range of features and settings which are beyond the scope of this guide. To learn more about JBoss A-MQ broker configuration, see the following guides from the Red Hat JBoss A-MQ documentation library:
  • Configuring Broker Persistence
  • Tuning Guide
  • Security Guide
  • XML Configuration Reference