Deploying message-driven beans to connect to a JCA resource adapter

You can connect to a JCA resource adapter by using the message-driven beans (MDB).

1. Configure the MDB feature:

   Enable MDB support in Liberty by configuring the mdb-3.1 and jca-1.6 features in the server.xml file. If you want to perform a JNDI lookup, then you must also add the jndi-1.0 feature along with the other two features.

   <featureManager>
        <feature>mdb-3.1</feature>
        <feature>jca-1.6</feature>
        <feature>jndi-1.0</feature>
   </featureManager>

   Stabilized features: The ejbLite-3.1, jca-1.6, and mdb-3.1 features are stabilized. You can continue to use the features. However, consider using later EJB, JCA, and MDB features.
2. Configure any other features required by your JCA resource adapter.
3. Configure a JCA activation specification that uses the resource adapter so that the MDB acts as a listener. The following examples show different ways that you can configure a MDB to interact with the messaging engine. These examples are specific to JMS resource adapters.
   1. Configure MDB by using the activation specification property.
      You can define the property in the server.xml file so that the MDB can use the property to listen on a specific JMS destination.

      <activationSpec id="JMSSample/JMSSampleMDB">
           <properties.wmqJms destinationRef="jndi/MDBQ" transportType="CLIENT" queueManager="myQM" hostName="myHost" port="1414"/>
      </activationSpec>
      
      <jmsQueue id="jndi/MDBQ" jndiName="jndi/MDBQ">
           <properties.wmqJms baseQueueName="MYQ" baseQueueManagerName="myQM"/>
      </jmsQueue>

      The <destinationRef> refers to the ID of the <jmsQueue>. If an ID in the <jmsQueue> is not mentioned, then <destinationRef> element must point to the <jndiName> of the <jmsQueue>.

      Note: The ID value must be in the format of application name/module name/bean name where

      • application name is the name of the application that is deployed (for example, JMSSample). The application name applies only if the bean is packaged within an EAR file. The application defaults to the base name of the EAR file with no file name extension unless specified by the application.xml deployment descriptor.
      • module name is the name of the module in which the bean is packaged. In a stand-alone ejb-jar file or WAR file, the <module-name> defaults to the base name of the module with any file name extension removed. In an EAR file, the <module-name> defaults to the path name of the module with any file name extension removed, but with any directory names included. The default <module-name> can be overridden by using the module-name element of ejb-jar.xml (for ejb-jar files) or web.xml (for WAR files).
      • bean name is the ejb-name of the enterprise bean. For enterprise beans defined through annotation, the bean name defaults to the unqualified name of the session bean class, unless specified in the contents of the name() attribute of the MessageDriven annotation. For enterprise beans defined through ejb-jar.xml, it is specified in the <ejb-name> deployment descriptor element.
   2. Configure the MDB by using annotations along with the activation specification property as defined in the server.xml file.

      Liberty supports defining annotations for message-driven beans that can be used with the activation specification property defined in the server.xml file. To use the annotation, first define the activation specification property as mentioned in the previous step. And for each of the message-driven beans, you can define the annotations as shown in the following example:

      @MessageDriven(
      		  name = "JMSSampleMDB",
      		  activationConfig = {
      		    @ActivationConfigProperty(propertyName  = "destinationType", 
      		                              propertyValue = "javax.jms.Queue"),
      		    @ActivationConfigProperty(propertyName  = "userName", 
      		                              propertyValue = "user1"),
      		    @ActivationConfigProperty(propertyName  = "password",
      		                              propertyValue = "user1pwd"),	
      		    @ActivationConfigProperty(propertyName  = "destination", 
      		                              propertyValue = "jndi_INPUT_Q")                         
      		  }
      		)
      public class JMSSampleMDB implements MessageListener{
      	
      	 @TransactionAttribute(value = TransactionAttributeType.REQUIRED)
      	  public void onMessage(Message message) {
      	 }
      }

   3. Configure the MDB by using the EJB binding file ibm-ejb-jar-bnd.xml.

      You can also use this binding file to define the resource information that is required for the MDB to connect to the messaging engine. When you are using the EJB binding file, the activation specification property ID is not required to be in the format of application name/module name/bean name as mentioned in step a.

      Add the activation specification property information in the server.xml file.

      <activationSpec id="PriceChangeAS">
           <properties.wmqJms destinationRef="jms/TriggerQ" transportType="CLIENT" queueManager="myQM" hostName="myHost" port="1414"/>
      </activationSpec>
      
      <jmsQueue id="jms/TriggerQ" jndiName="jms/TriggerQ">
           <properties.wmqJms baseQueueName="Q1"/>                  
       </jmsQueue>

      Add the following MDB binding information in the ibm-ejb-jar-bnd.xml file.

      <ejb-jar-bnd
              xmlns="http://websphere.ibm.com/xml/ns/javaee"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_1.xsd" 
      	(http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_1.xsd%27) version="1.1">
          
      	<message-driven name="PriceChangeMDBBean">
              	<jca-adapter activation-spec-binding-name="PriceChangeAS" destination-binding-name="jms/TriggerQ" />
         	</message-driven>
      </ejb-jar-bnd>

      Note: When you are using the EJB binding file, the activation-spec-binding-name attribute in the ibm-ejb-jar-bnd.xml file must point to the activation specification property ID value that is specified in the server.xml file.
   4. The resource information can also be specified in the server.xml file under the <application> element. The server.xml configuration information is in the same form as the information that is specified in the ibm-ejb-jar-bnd.xml file. For example:

      <application location="PriceChangeApp.ear">
      	<ejb-jar-bnd moduleName="PriceChangeEJB">       
      	   <message-driven name="PriceChangeMDBBean">
              	<jca-adapter activation-spec-binding-name="PriceChangeAS" destination-binding-name="jms/TriggerQ" />
      	   </message-driven>
      	</ejb-jar-bnd>
      </application>

      Note: You must specify the moduleName attribute for the <ejb-jar-bnd> element. The value is the name of the JAR file that contains the MDB without the .jar extension. For example, if the MDB is contained in PriceChangeEJB.jar, the moduleName attribute is PriceChangeEJB.