Deploying message-driven beans to connect to the embedded messaging server

Use the message-driven beans (MDB) to connect to the embedded messaging server.

1. Configure the MDB feature.

   Enable MDB support by configuring the jmsMdb-3.1 and wasJmsClient-2.0 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>jmsMdb-3.1</feature>
        <feature>wasJmsClient-2.0</feature>
        <feature>jndi-1.0</feature>
   </featureManager>

   Configuring the wasJmsClient-2.0 feature enables you to define the required JMS resources and enables MDB to interact with the messaging engine.

   Important: The wasJmsClient-2.0 feature supports the features of both JMS 1.1 and JMS 2.0 specifications. However, you can choose to use the wasJmsClient-1.1 feature if you want to use only the features that are compliant with JMS 1.1 specification.
2. Configure a JCA activation specification that uses the JMS resource adapter so that the MDB acts as a listener on a specific JMS destination.

   Choose one of the following three options to configure the MDB to interact with the messaging engine:

   • Define activation specification properties in the server.xml file.
   • Define resource information in the EJB binding file.
   • Define resource information in the application element in the server.xml file.

   • Option 1: Define activation specification properties in the server.xml file.

     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.

     <jmsActivationSpec id="JMSSample/JMSSampleMDB">
          <properties.wasJms destinationRef="jndi/MDBQ"  />
     </jmsActivationSpec>
     
     <jmsQueue id="jndi/MDBQ" jndiName="jndi/MDBQ">
          <properties.wasJms queueName="Q1"/>
     </jmsQueue>

     The destinationRef attribute refers to the ID of the jmsQueue element. If no ID is defined for the jmsQueue element, then the destinationRef attribute must point to the jndiName value of the jmsQueue element.

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

     • 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 value defaults to the base name of the module with any file name extension removed. In an EAR file, the module-name value defaults to the path name of the module with any file name extension removed, but with any directory names included. You can override the default module-name value 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.

   • Option 2: Define resource information in the ibm-ejb-jar-bnd.xml EJB binding file.

     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 need not necessarily be in the application name/module name/bean name format.

     Define the activation specification properties in the server.xml file.

     <jmsActivationSpec id="PriceChangeAS">
          <properties.wasJms destinationRef="jms/TriggerQ" />
     </jmsActivationSpec>
     
     <jmsQueue id="jms/TriggerQ" jndiName="jms/TriggerQ">
          <properties.wasJms queueName="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 use 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.

   • Option 3: Define resource information in the application element in the server.xml file.

     You can define the server.xml configuration information in the same form as the information that is specified in the ibm-ejb-jar-bnd.xml file, as shown in the following 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: 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.
3. Optional: Provide activation configuration properties to the ActivationSpec instance by specifying annotations on the MDB.

   Liberty supports defining annotations for MDBs that can be used with the activation specification property that is defined in the server.xml file. To use the annotation, first define the activation specification property as described in the previous step. For each of the MDB, 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) {
   	 }
   }