Version 5

    Overview

    This document explains how to set-up and configure Apache MQ as an embedded messaging broker within JBoss AS 7.  It was adapted from the PDF available here.

     

    Prerequisites

    At the point of writing this article you must use the nightly build of JBoss AS 7 if you would like to be able to change the persistence method used by ActiveMQ (by editing the broker config file).  You can download the latest nightly of JBoss AS 7 from https://ci.jboss.org/jenkins/job/JBoss-AS-7.x-latest/lastSuccessfulBuild/artifact/build/target/jboss-as-7.x.zip.

     

    The ActiveMQ JCA Resource Adapter 5.6 provides the embedded implementation of ActiveMQ.  Download the ActiveMQ JCA RA here: http://repo1.maven.org/maven2/org/apache/activemq/activemq-rar/

     

    Configuration Overview

    • JBoss has a configuration file standalone.xml which can be used to integrate Active MQ.
    • The JBoss configuration file needs to contain a resource-adapter configuration. Its within this resource-adapter that Apache Active MQ is integrated.
    • An MDB specification in standalone.xml can make Apache Active MQ the default messaging provider.
    • The resource adapter configuration needs to contain a connection factory, used to obtain connections to Queues and Topics.
    • For each Queue or Topic there needs to be at least an implementation class name, a JNDI name, a physical name and a pool name.
    • The MDB is attached to the queue via its destination being set to the physical-name for the topic or queue admin-object.

     

    JBoss Resource Adapter Configuration

    The configuration overview above corresponds to the XML below, showing a single queue and single topic defined as part of the resource adapter configuration. These resources are referred to as JCA Admin Objects.

     

    <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0">
      <resource-adapters>
        <resource-adapter>
            <archive>
                activemq-rar-5.7-SNAPSHOT.rar
            </archive>
            <transaction-support>XATransaction</transaction-support>
            <config-property name="UseInboundSession">
                false
            </config-property>
            <config-property name="Password">
                password
            </config-property>
            <config-property name="UserName">
                admin
            </config-property>
            <config-property name="ServerUrl">
                vm://localhost?brokerConfig=xbean:broker-config.xml
            </config-property>
            <connection-definitions>
                <connection-definition class-name="org.apache.activemq.ra.ActiveMQManagedConnectionFactory" jndiname="java:jboss/exported/ConnectionFactory" enabled="true" use-java-context="true" pool-name="ConnectionFactory"/>
            </connection-definitions>
            <admin-objects>
                <admin-object class-name="org.apache.activemq.command.ActiveMQQueue" jndi-name="java:/queue/FromETSQueue" use-java-context="true" pool-name="queue1">
                    <config-property name="PhysicalName">
                        queue1
                    </config-property>
                </admin-object>
                <admin-object class-name="org.apache.activemq.command.ActiveMQTopic" jndiname="java:jboss/eis/ao/ActiveMQTopic" use-java-context="true" pool-name="topic1">
                    <config-property name="PhysicalName">
                        topic1
                    </config-property>
                </admin-object>
            </admin-objects>
        </resource-adapter>
      </resource-adapters>
    </subsystem>
    

     

    If you wanted this configuration to point to a remote Apache MQ Messaging provider the vm://localhost needs to be changed to the IP and port of your broker. For a broker running on brokerHostName at port 3000, the stanza would look as follows:

     

    tcp://brokerHostName:3000/?brokerConfig=xbean:broker-config.xml
    

     

    If the broker-config.xml file is on the file system, then a file URL can be used, as follows:

     

    tcp://brokerHostName:3000/?brokerConfig=xbean:file:///broker-config.xml
    

     

    Active MQ will run in embedded mode with:

     

    vm://localhost
    

     

    Changing the default resource adapter for MDBs

    By default, JBoss AS 7 will use the HornetQ JCA RA for MDBs.  However, this can be changed by modifying the <mdb> configuration of the "ejb3" subsystem in standalone.xml.  For example, you can change the default to the ActiveMQ JCA RA:

     

    <mdb>
         <resource-adapter-ref resource-adapter-name="activemq-rar-5.7-SNAPSHOT.rar"/>
         <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
    </mdb>
    

     

    JCA registers the admin objects

    Registration of the Connection Factory by JCA looks as follows.

     

    12:33:45,420 INFO [org.jboss.as.deployment.connector] (MSC service thread 1-8) JBAS010406: Registered connection factory java:jboss/exported/ConnectionFactory
    

     

    Registration of the Topics and Queues by JCA looks as follows.

     

    12:33:45,423 INFO [org.jboss.as.deployment.connector] (MSC service thread 1-8) JBAS010405: Registered admin object at java:jboss/queue/fromSomeWhereQueue
    

     

    MDB Configuration with Apache ActiveMQ

    An MDB is typically deployed within an EAR or JAR.  It needs to be bound to the physical name provided from standalone.xml.  For example:

     

    @MessageDriven( activationConfig = { 
       @ActivationConfigProperty(propertyName="destinationType", propertyValue="javax.jms.Queue"),
       @ActivationConfigProperty(propertyName="destination", propertyValue="fromSomewhereQueue"),
       @ActivationConfigProperty(propertyName="acknowledgeMode", propertyValue="Auto-acknowledge"), 
     })
    @ResourceAdapter("activemq-rar-5.7-SNAPSHOT.rar")
    

     

    Note: The @ResourceAdapter annotation is only required when the default JCA RA is not Apache Active MQ's (as described above).

     

    Example JMS Client Code

    Most will be familiar with this code. Here we send a JMS message onto a queue.

     

    oConnectionFactory = (QueueConnectionFactory) oInitialContext.lookup(“java:jboss/exported/ConnectionFactory”);
    Connection oConnection = oConnectionFactory.createConnection();
    Session oSession = oConnection.createSession(false, Session.AUTO_ACKNOWLEDGE);
    Destination oDestination = (Queue) oInitialContext.lookup("java:jboss/queue/fromSomeWhereQueue");
    MessageProducer oMessageProducer = oSession.createProducer((Queue) oDestination);
    TextMessage oTextMessage = oSession.createTextMessage();
    oTextMessage.setText("Hello Apache MQ Guru's");
    oMessageProducer.send(oTextMessage);
    

     

    Output when the MDB OnMessage() method fires

    On a successful message reception the message captured by the MDB will look as follows.

     

    16:27:36,655 INFO [stdout] (default-threads - 3) ActiveMQTextMessage {commandId = 13, responseRequired = true, messageId = ID:SWEETCORN-52564-1343230036458-5:1:2:1:1, originalDestination = null, originalTransactionId = null, producerId = ID:SWEETCORN-52564-1343230036458-5:1:2:1, destination = queue://FromETSQueue, transactionId = null, expiration = 0, timestamp = 1343230056646, arrival = 0, brokerInTime = 1343230056649, brokerOutTime = 1343230056651, correlationId = null, replyTo = null, persistent = true, type = null, priority = 4, groupID = null, groupSequence = 0, targetConsumerId = null, compressed = false, userID = null, content = org.apache.activemq.util.ByteSequence@163a3c40, marshalledProperties = null, dataStructure = null, redeliveryCounter = 0, size = 1052, properties = null, readOnlyProperties = true, readOnlyBody = true, droppable = false, text = Hello Apache MQ Guru's} 
    

     

    Database Persistence

    For a general discussion of the persistence capabilities of ActiveMQ see http://activemq.apache.org/persistence.html

     

    For any persistence option which requires JAR files which do not appear in the ActiveMQ JCA RA (e.g. JDBC drivers) you will need to create a JBoss module containing those JARs and then modify the manifest.mf of the ActiveMQ JCA RA to depend upon that module.  Here is a simple, generic example of how to create a module:

     

    1. Create a directory under <JBOSS_HOME>/modules, e.g. com/example/main.
    2. Put your JAR(s) in this new directory, e.g. foo.jar.
    3. Create a file named module.xml in this directory, e.g.:  

     

    <module xmlns="urn:jboss:module:1.1" name="com.example">
          <resources>
             <resource-root path="foo.jar"/>
         </resources>
     </module>
    

     

    1. Add the dependency in the manifest.mf of the ActiveMQ JCA RA, e.g.:  

     

    Dependencies: com.example