Deploying message-driven beans to connect to IBM MQ

You can connect to IBM® MQ by using the message-driven beans (MDB).

Procedure

  1. Configure the MDB feature:

    Enable MDB support in the Liberty server by configuring the jmsMdb-3.2 and wmqJmsClient-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.2</feature>
         <feature>wmqJmsClient-2.0</feature>
         <feature>jndi-1.0</feature>
    </featureManager>

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

    Note: The wmqJmsClient-2.0 feature supports the features of both JMS 1.1 and JMS 2.0 specifications. However, you can choose to use the wmqJmsClient-1.1 feature if you want to use only the features that are compliant with JMS 1.1 specification.
  2. Specify the location of the IBM MQ Resource Adapter by adding the following entry to the server.xml file:
    <variable name="wmqJmsClient.rar.location" value="/path/to/wmq/rar/wmq.jmsra.rar"/>
    where the value attribute specifies the absolute path to the IBM MQ Resource Adapter file, wmq.jmsra.rar.

    For details about the supported versions and obtaining the wmq.jmsra.rar file, refer to the IBM MQ resource adapter for Liberty information. Obtain the wmq.jmsra.rar file and install it from Fix central.

  3. Configure a JCA activation specification that uses the JMS resource adapter so that the MDB acts as a listener on a specific JMS destination. The following are different ways in which an MDB can be configured to interact with the messaging engine.
    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.
      <jmsActivationSpec id="JMSSample/JMSSampleMDB">
           <properties.wmqJms destinationRef="jndi/MDBQ" transportType="CLIENT" queueManager="myQM" hostName="myHost" port="1414"/>
      </jmsActivationSpec>
      
      <jmsQueue id="jndi/MDBQ" jndiName="jndi/MDBQ">
           <properties.wmqJms baseQueueName="MYQ" baseQueueManagerName="myQM"/>
      </jmsQueue>

      The <destinationRef> refers to the ID of <jmsQueue>. If an ID in <jmsQueue> is not mentioned, then <destinationRef> 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. Using annotations along with the activation specification property defined in the server.xml file.

      Liberty supports defining annotations for MDBs that can be used with the activation specification property defined in the server.xml file. In order to use the annotation, first define the activation specification property as mentioned in the previous step. And for each of the MDB, user 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. 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 need not necessarily be in the format of application name/module name/bean name as mentioned in step 1.

      Add the activation specification property information in the server.xml.
      <jmsActivationSpec id="PriceChangeAS">
           <properties.wmqJms destinationRef="jms/TriggerQ" transportType="CLIENT" queueManager="myQM" hostName="myHost" port="1414"/>
      </jmsActivationSpec>
      
      <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 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.