1.5. Build and Deploy the helloworld-mdb Example

Overview

In this tutorial, you will customize the helloworld-mdb quickstart example so that it works with the ActiveMQ resource adapter. You can then build and deploy the helloworld-mdb example into a standalone instance of JBoss Enterprise Application Platform (which already has an ActiveMQ resource adapter installed).
The helloworld-mdb example illustrates two kinds of integration with messaging: integration of message-driven beans; and integration of a servlet (which gets access to a JMS queue and a JMS topic using the standard JMS administered objects mechanism).

Prerequisites

The following prerequisites must be satisfied, before you can build and deploy the helloworld-mdb example:

Customizations

The version of the helloworld-mdb demonstration provided in the quickstarts distribution is integrated with the HornetQ messaging platform by default. To refactor the demonstration so that it integrates with Apache ActiveMQ, it is necessary to customize the following aspects of the helloworld-mdb code:
  • Delete the HornetQ XML configuration file (located in helloworld-mdb/src/main/webapp/WEB-INF/hornetq-jms.xml).
  • In HelloWorldQueueMDB.java, customize the annotations on the message driven bean to integrate with the ActiveMQ resource adapter.
  • In HelloWorldTopicMDB.java, customize the annotations on the message driven bean to integrate with the ActiveMQ resource adapter.
  • Add additional Maven dependencies.
These customizations are described in more detail in the rest of this section.

Steps to build and deploy the example

To build and deploy the quickstart helloworld-mdb example, perform the following steps:
  1. Delete the following HornetQ XML configuration file from the helloworld-mdb project: 
    helloworld-mdb/src/main/webapp/WEB-INF/hornetq-jms.xml
  2. Edit the annotations on the HelloWorldQueueMDB message driven bean class, so that it integrates with the ActiveMQ resource adapter (instead of HornetQ). Edit the HelloWorldQueueMDB.java file at the following location: 
    helloworld-mdb/src/main/java/org/jboss/as/quickstarts/mdb/HelloWorldQueueMDB.java
    Open the HelloWorldQueueMDB.java file using a text editor and make the modifications highlighted in the following extract: 
    import org.jboss.ejb3.annotation.ResourceAdapter;
...
@MessageDriven(name = "HelloWorldQueueMDB", activationConfig = {
		@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
		@ActivationConfigProperty(propertyName = "destination", propertyValue = "HELLOWORLDMDBQueue"),
		@ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge") })
@ResourceAdapter(value="activemq-rar.rar")
public class HelloWorldQueueMDB implements MessageListener {
    ...
    Where the following changes are made to the code:
    • The @ResourceAdapter annotation explicitly associates the message driven bean with the ActiveMQ resource adapter. You must include this annotation, if you want to use the ActiveMQ resource adapter.
    • You need to add an import statement for the @ResourceAdapter annotation.
    • The value of the destination property is changed to HELLOWORLDMDBQueue, which is the physical name of the corresponding ActiveMQ queue that this message driven bean subscribes to. The physical name of the queue is the queue identifier used by the JBoss A-MQ broker.
      Note
      You must specify the queue's physical name here. In contrast to the case of HornetQ, the ActiveMQ messaging integration does not allow you to use a JNDI name for the destination value.
  3. Edit the annotations on the HelloWorldTopicMDB message driven bean class, so that it integrates with the ActiveMQ resource adapter (instead of HornetQ). Edit the HelloWorldTopicMDB.java file at the following location: 
    helloworld-mdb/src/main/java/org/jboss/as/quickstarts/mdb/HelloWorldTopicMDB.java
    Open the HelloWorldTopicMDB.java file using a text editor and make the modifications highlighted in the following extract: 
    import org.jboss.ejb3.annotation.ResourceAdapter;
...
@MessageDriven(name = "HelloWorldQTopicMDB", activationConfig = {
		@ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Topic"),
		@ActivationConfigProperty(propertyName = "destination", propertyValue = "HELLOWORLDMDBTopic"),
		@ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge") })
@ResourceAdapter(value="activemq-rar.rar")
public class HelloWorldTopicMDB implements MessageListener {
    ...
  4. Add the Maven dependency for the jboss-ejb3-ext-api artifact, which is needed for the @ResourceAdapter annotation. Open the helloworld-mdb/pom.xml file using a text editor and add the following dependency element as a child of the dependencies element in the POM file: 
    <project ...>
    ...
    <dependencies>
        ...
        <dependency>
            <groupId>org.jboss.ejb3</groupId>
            <artifactId>jboss-ejb3-ext-api</artifactId>
            <!-- to get the right version, look in the EAP offline Maven repo -->
            <version>2.1.0.redhat-1</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    ...
</project>
    The provided scope value implies there is no need to embed the jboss-ejb3-ext-api JAR file in the generated WAR, because this library is already provided by the JBoss EAP container.
    Note
    If you ever need to update the version of the jboss-ejb3-ext-api artifact, you can discover which version to use by drilling down to the org/jboss/ejb3/jboss-ejb3-ext-api subdirectory of the Maven repository you downloaded and installed in Section 1.4, “Install JBoss AS Quickstarts”.
  5. Build the helloworld-mdb example as follows. Open a new command prompt, change directory to the helloworld-mdb directory, and enter the following Maven command: 
    mvn clean package
    If the build is successful, you should find the jboss-as-helloworld-mdb.war WAR file in the helloworld-mdb/target directory.
  6. If you have not already done so, register the administered objects for the queues and topics used by the example, by editing the JBoss EAP configuration.
    In your JBoss EAP installation, open the standalone/configuration/standalone-full.xml configuration file with a text editor, and add the following highlighted administered objects to the activemq-rar.rar resource adapter: 
    <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">
                    ...
                    <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>
    Where the preceding configuration adds the following entries to the JNDI registry:
    java:/queue/HELLOWORLDMDBQueue
    References a javax.jms.Queue object that connects to the HELLOWORLDMDBQueue ActiveMQ queue (where the queue name on the JBoss A-MQ broker is specified by the PhysicalName config property).
    java:/queue/HELLOWORLDMDBTopic
    References a javax.jms.Topic object that connects to the HELLOWORLDMDBTopic ActiveMQ topic (where the topic name on the JBoss A-MQ broker is specified by the PhysicalName config property).
    In the helloworld-mdb example, these administered objects are accessed by the servlet class, HelloWorldMDBServletClient (but not by the message driven bean classes). For example, the HelloWorldMDBServletClient class injects these JNDI entries, using the @Resource annotation, as follows: 
    import javax.annotation.Resource;
...
import javax.jms.ConnectionFactory;
...
import javax.jms.Queue;
import javax.jms.Topic;
...
public class HelloWorldMDBServletClient extends HttpServlet {
    ...
	@Resource(mappedName = "java:/ConnectionFactory")
	private ConnectionFactory connectionFactory;

	@Resource(mappedName = "java:/queue/HELLOWORLDMDBQueue")
	private Queue queue;

	@Resource(mappedName = "java:/topic/HELLOWORLDMDBTopic")
	private Topic topic;
    ...
  7. Deploy the helloworld-mdb example to the running Web server. Manually copy the jboss-as-helloworld-mdb.war WAR file from the helloworld-mdb/target directory to the Web server's deployment directory, standalone/deployments.

Access the helloworld-mdb service

You can now test the helloworld-mdb service, as follows:
  1. If you have not already started the JBoss EAP standalone container, do so by entering the following commands at the command line: 
    cd EAPInstallDir/bin
./standalone.sh
  2. You should now be able to access the helloworld-mdb service from your browser, by navigating to the following URL: 
    http://localhost:8080/jboss-helloworld-mdb/HelloWorldMDBServletClient
    When you navigate to the preceding URL, the servlet sends five messages to the HelloWorldQueueMDB message-driven bean. If you look at the container console window, you should see some output like the following: 
    14:41:20,739 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (default-threads - 7) Received Message from queue: This is message 5
14:41:20,739 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (default-threads - 5) Received Message from queue: This is message 3
14:41:20,739 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (default-threads - 4) Received Message from queue: This is message 2
14:41:20,741 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (default-threads - 6) Received Message from queue: This is message 4
14:41:20,742 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (default-threads - 3) Received Message from queue: This is message 1
    These console messages are written by the HelloWorldQueueMDB message-driven bean, thus demonstrating that the messages have successfully propagated from the servlet, through the JBoss A-MQ broker, to the message-driven bean.
  3. To send messages to the HelloWorldTopicMDB message-driven bean, navigate to the following URL: 
    http://localhost:8080/jboss-helloworld-mdb/HelloWorldMDBServletClient?topic
    When you navigate to the preceding URL, the servlet sends five messages to the HelloWorldTopicMDB message-driven bean. If you look at the container console window, you should see some output like the following: 
    14:53:02,464 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (default-threads - 9) Received Message from topic: This is message 2
14:53:02,466 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (default-threads - 10) Received Message from topic: This is message 3
14:53:02,468 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (default-threads - 8) Received Message from topic: This is message 1
14:53:02,471 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (default-threads - 11) Received Message from topic: This is message 4
14:53:02,472 INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (default-threads - 12) Received Message from topic: This is message 5
    These console messages are written by the HelloWorldTopicMDB message-driven bean, thus demonstrating that the messages have successfully propagated from the servlet, through the JBoss A-MQ broker, to the message-driven bean.