8.4. Message-Driven Beans

8.4.1. Message-Driven Beans

Message-driven Beans (MDBs) provide an event driven model for application development. The methods of MDBs are not injected into or invoked from client code but are triggered by the receipt of messages from a messaging service such as a Java Messaging Service (JMS) server. The Java EE 6 specification requires that JMS is supported but other messaging systems can be supported as well.

8.4.2. Resource Adapters

A resource adapter is a deployable Java EE component that provides communication between a Java EE application and an Enterprise Information System (EIS) using the Java Connector Architecture (JCA) specification. A resource adapter is often provided by EIS vendors to allow easy integration of their products with Java EE applications.
An Enterprise Information System can be any other software system within an organization. Examples include Enterprise Resource Planning (ERP) systems, database systems, e-mail servers and proprietary messaging systems.
A resource adapter is packaged in a Resource Adapter Archive (RAR) file which can be deployed to JBoss EAP 6. A RAR file may also be included in an Enterprise Archive (EAR) deployment.

8.4.3. Create a JMS-based Message-Driven Bean in Red Hat JBoss Developer Studio

This procedure shows how to add a JMS-based Message-Driven Bean to a project in Red Hat JBoss Developer Studio. This procedure creates an EJB 3.x Message-Driven Bean that uses annotations.

Prerequisites:

  1. You must have an existing project open in Red Hat JBoss Developer Studio.
  2. You must know the name and type of the JMS destination that the bean will be listening to.
  3. Support for Java Messaging Service (JMS) must be enabled in the JBoss EAP 6 configuration to which this bean will be deployed.

Procedure 8.6. Add a JMS-based Message-Driven Bean in Red Hat JBoss Developer Studio

  1. Open the Create EJB 3.x Message-Driven Bean Wizard

    Go to FileNewOther. Select EJB/Message-Driven Bean (EJB 3.x) and click the Next button.
    Create EJB 3.x Message-Driven Bean Wizard

    Figure 8.9. Create EJB 3.x Message-Driven Bean Wizard

  2. Specify class file destination details

    There are three sets of details to specify for the bean class here: Project, Java class, and message destination.
    Project
    • If multiple projects exist in the Workspace, ensure that the correct one is selected in the Project menu.
    • The folder where the source file for the new bean will be created is ejbModule under the selected project's directory. Only change this if you have a specific requirement.
    Java class
    • The required fields are: Java package and class name.
    • It is not necessary to supply a Superclass unless the business logic of your application requires it.
    Message Destination
    These are the details you must supply for a JMS-based Message-Driven Bean:
    • Destination name. This is the queue or topic name that contains the messages that the bean will respond to.
    • By default the JMS checkbox is selected. Do not change this.
    • Set Destination type to Queue or Topic as required.
    Click the Next button.
  3. Enter Message-Driven Bean specific information

    The default values here are suitable for a JMS-based Message-Driven bean using Container-managed transactions.
    • Change the Transaction type to Bean if the Bean will use Bean-managed transactions.
    • Change the Bean name if a different bean name than the class name is required.
    • The JMS Message Listener interface will already be listed. You do not need to add or remove any interfaces unless they are specific to your applications business logic.
    • Leave the checkboxes for creating method stubs selected.
    Click the Finish button.
Result: The Message-Driven Bean is created with stub methods for the default constructor and the onMessage() method. A Red Hat JBoss Developer Studio editor window opened with the corresponding file.

8.4.4. Specifying a Resource Adapter in jboss-ejb3.xml for an MDB

In the jboss-ejb3.xml deployment descriptor you can specify a resource adapter for an MDB to use. Alternatively, to configure a JBoss EAP 6 server-wide default resource adapter for MDBs, see Configuring Message-Driven Beans in the Administration and Configuration Guide.
To specify a resource adapter in jboss-ejb3.xml for an MDB, use the following example.

Example 8.1. jboss-ejb3.xml Configuration for an MDB Resource Adapter

<jboss xmlns="http://www.jboss.com/xml/ns/javaee"
  xmlns:jee="http://java.sun.com/xml/ns/javaee"
  xmlns:mdb="urn:resource-adapter-binding">
  <jee:assembly-descriptor>  
    <mdb:resource-adapter-binding>  
      <jee:ejb-name>MyMDB</jee:ejb-name>  
      <mdb:resource-adapter-name>MyResourceAdapter.rar</mdb:resource-adapter-name>  
    </mdb:resource-adapter-binding>  
  </jee:assembly-descriptor>
</jboss>
For a resource adapter located in an EAR, you must use the following syntax for <mdb:resource-adapter-name>:
  • For a resource adapter that is in another EAR:
    <mdb:resource-adapter-name>OtherDeployment.ear#MyResourceAdapter.rar</mdb:resource-adapter-name>
  • For a resource adapter that is in the same EAR as the MDB, you can omit the EAR name:
    <mdb:resource-adapter-name>#MyResourceAdapter.rar</mdb:resource-adapter-name>

8.4.5. Enable EJB and MDB Property Substitution in an Application

A new feature in Red Hat JBoss Enterprise Application Platform allows you to enable property substitution in EJBs and MDBs using the @ActivationConfigProperty and @Resource annotations. Property substitution requires the following configuration and code changes.
  • You must enable property substitution in the JBoss EAP server configuration file.
  • You must define the system properties in the server configuration file or pass them as arguments when you start the JBoss EAP server.
  • You must modify the code to use the substitution variables.

Procedure 8.7. Implement Property Substitution in an MDB Application

The following code examples are based on the helloworld-mdb quickstart that ships with JBoss EAP 6.3 or later. This topic shows you how to modify that quickstart to enable property substitution.
  1. Configure the JBoss EAP server to enable property substitution.

    The JBoss EAP server must be configured to enable property substitution. To do this, set the <annotation-property-replacement> attribute in the ee subsystem of the server configuration file to true.
    1. Back up the server configuration file. The helloworld-mdb quickstart example requires the full profile for a standalone server, so this is the standalone/configuration/standalone-full.xml file. If you are running your server in a managed domain, this is the domain/configuration/domain.xml file.
    2. Start the JBoss EAP server with the full profile.
      For Linux:
      EAP_HOME/bin/standalone.sh -c standalone-full.xml
      For Windows:
      EAP_HOMEbin\standalone.bat -c standalone-full.xml
    3. Launch the Management CLI using the command for your operating system.
      For Linux:
      EAP_HOME/bin/jboss-cli.sh --connect
      For Windows:
      EAP_HOME\bin\jboss-cli.bat --connect
    4. Type the following command to enable annotation property substitution.
      /subsystem=ee:write-attribute(name=annotation-property-replacement,value=true) 
    5. You should see the following result:
      {"outcome" => "success"}
    6. Review the changes to the JBoss EAP server configuration file. The ee subsystem should now contain the following XML.
      <subsystem xmlns="urn:jboss:domain:ee:1.2">
          <spec-descriptor-property-replacement>false</spec-descriptor-property-replacement>
          <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement>
          <annotation-property-replacement>true</annotation-property-replacement>
      </subsystem>
  2. Define the system properties.

    You can specify the system properties in the server configuration file or you can pass them as command line arguments when you start the JBoss EAP server. System properties defined in the server configuration file take precedence over those passed on the command line when you start the server.
    • Define the system properties in the server configuration file.
      1. Start the JBoss EAP server and Management API as described in the previous step.
      2. Use the following command syntax to configure a system property in the JBoss EAP server:
        /system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE) 
        For the helloworld-mdb quickstart, we configure the following system properties:
        /system-property=property.helloworldmdb.queue:add(value=java:/queue/HELLOWORLDMDBPropQueue)
        /system-property=property.helloworldmdb.topic:add(value=java:/topic/HELLOWORLDMDBPropTopic)
        /system-property=property.connection.factory:add(value=java:/ConnectionFactory)
      3. Review the changes to the JBoss EAP server configuration file. The following system properties should now appear in the after the <extensions>.
        <system-properties>
            <property name="property.helloworldmdb.queue" value="java:/queue/HELLOWORLDMDBPropQueue"/>
            <property name="property.helloworldmdb.topic" value="java:/topic/HELLOWORLDMDBPropTopic"/>
            <property name="property.connection.factory" value="java:/ConnectionFactory"/>
        </system-properties>
    • Pass the system properties as arguments on the command line when you start the JBoss EAP server in the form of -DPROPERTY_NAME=PROPERTY_VALUE. The following is an example of how to pass the arguments for the system properties defined in the previous step.
      EAP_HOME/bin/standalone.sh -c standalone-full.xml -Dproperty.helloworldmdb.queue=java:/queue/HELLOWORLDMDBPropQueue -Dproperty.helloworldmdb.topic=java:/topic/HELLOWORLDMDBPropTopic -Dproperty.connection.factory=java:/ConnectionFactory
  3. Modify the code to use the system property substitutions.

    Replace hard-coded @ActivationConfigProperty and @Resource annotation values with substitutions for the newly defined system properties. The following are examples of how to change the helloworld-mdb quickstart to use the newly defined system property substitutions within the annotations in the source code.
    1. Change the @ActivationConfigProperty destination property value in the HelloWorldQueueMDB class to use the substitution for the system property. The @MessageDriven annotation should now look like this:
      @MessageDriven(name = "HelloWorldQueueMDB", activationConfig = {
          @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
          @ActivationConfigProperty(propertyName = "destination", propertyValue = "${property.helloworldmdb.queue}"),   
          @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge") })
      
    2. Change the @ActivationConfigProperty destination property value in the HelloWorldTopicMDB class to use the substitution for the system property. The @MessageDriven annotation should now look like this:
      @MessageDriven(name = "HelloWorldQTopicMDB", activationConfig = {
          @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Topic"),
          @ActivationConfigProperty(propertyName = "destination", propertyValue = "${property.helloworldmdb.topic}"),   
          @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge") })
    3. Change the @Resource annotations in the HelloWorldMDBServletClient class to use the system property substitutions. The code should now look like this:
      @Resource(mappedName = "${property.connection.factory}")
      private ConnectionFactory connectionFactory;
      
      @Resource(mappedName = "${property.helloworldmdb.queue}")   
      private Queue queue;
      
      @Resource(mappedName = "${property.helloworldmdb.topic}")
      private Topic topic;
      
    4. Modify the hornetq-jms.xml file to use the system property substitution values.
      <?xml version="1.0" encoding="UTF-8"?>
      <messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
          <hornetq-server>
              <jms-destinations>
                  <jms-queue name="HELLOWORLDMDBQueue">
                      <entry name="${property.helloworldmdb.queue}"/>
                  </jms-queue>
                  <jms-topic name="HELLOWORLDMDBTopic">
                      <entry name="${property.helloworldmdb.topic}"/>
                  </jms-topic>
              </jms-destinations>
          </hornetq-server>
      </messaging-deployment>
  4. Deploy the application. The application will now use the values specified by the system properties for the @Resource and @ActivationConfigProperty property values.