Installing the resource adapter in Liberty

To connect to IBM MQ from WebSphere Liberty, or other Java EE application servers, we must use the IBM MQ resource adapter. Since Liberty does not contain the IBM MQ resource adapter, we must obtain it separately from Fix Central.

Before starting

Before you start this task, make sure that we have a Java runtime environment (JRE) installed on your machine and that the JRE has been added to the system path.

The Java installer that is used in this installation process does not require running as root or any specific user. The only requirement is that the user it is run as has access write to the directory that we want the files to go in.

The JAR file for the resource adapter that we can download from Fix Central is executable. When you run this executable file, it displays the IBM MQ license agreement, which must be accepted. It asks for a directory in which to install the IBM MQ resource adapter. The resource adapter RAR file and installation verification test (IVT) program are then installed in that directory. We can either accept the default or specify another directory, which might be the resource adapters directory of an application server, or any other directory on the system. The directory is created as part of the installation if it does not exist.

Before IBM MQ Version 9.0, the name of the file to be downloaded was in the format of V.R.M.F-WS-MQ-Java-InstallRA.jar, for example 8.0.0.6-WS-MQ-Java-InstallRA.jar. From IBM MQ Version 9.0, the format of the file name is V.R.M.F-IBM-MQ-Java-InstallRA.jar, for example 9.0.0.0-IBM-MQ-Java-InstallRA.jar.

After you have downloaded and installed the resource adapter, we are ready to configure it in WebSphere Liberty.

Procedure

1. Download the IBM MQ resource adapter from Fix Central.
   1. Click this link: IBM MQ Resource Adapter.
   2. Find the resource adapter for the version of IBM MQ in the displayed list of available fixes. For example:

      release level: 9.1.4.0-IBM-MQ-Java-InstallRA
      Continuous Delivery Release: 9.1.4 IBM MQ Resource Adapter for use with Application Servers 
          

      Then click the resource adapter file name and follow the download process.

2. Start the installation by entering the following command from the directory to which you downloaded the file. From IBM MQ Version 9.0, the format of the command is as follows:

   java -jar V.R.M.F-IBM-MQ-Java-InstallRA.jar
   

   where V.R.M.F is the Version, Release, Modification, and Fix Pack number and V.R.M.F-IBM-MQ-Java-InstallRA.jar is the name of the file that was downloaded from Fix Central. For example, to install the IBM MQ resource adapter for the Version 9.1.4.0 release, you would use the following command:

   java -jar 9.1.4.0-IBM-MQ-Java-InstallRA.jar
   

   Note: To carry out this installation, we must have a JRE installed on your machine and added to the system path. When you enter the command, the following information is displayed:

   Before we can use, extract, or install IBM MQ V9.1, we must accept
   the terms of 1. IBM International License Agreement for Evaluation of
   Programs 2. IBM International Program License Agreement and additional
   license information. Please read the following license agreements carefully.
   
   The license agreement is separately viewable using the
   --viewLicenseAgreement option.
   Press Enter to display the license terms now, or 'x' to skip.

3. Review and accept the license terms:
   1. To display the license, press Enter. Alternatively, pressing x skips the display of the license. After display of the license or immediately after selecting x, the following message appears to tell you that we can choose to display additional license terms:

      Additional license information is separately viewable using the
      --viewLicenseInfo option.
      Press Enter to display additional license information now, or 'x' to skip.

   2. To display the additional license terms, press Enter. Alternatively, pressing x skips the display of the additional license terms. After display of the additional license terms or immediately after selecting x, the following message is displayed asking you to accept the license agreement:

      By choosing the "I Agree" option below, you agree to the terms of the
      license agreement and non-IBM terms, if applicable. If we do not
      agree, select "I do not Agree".
      
      Select [1] I Agree, or [2] I do not Agree:

   3. To accept the license agreement and continue with selecting the installation directory, select 1. Alternatively, if you select 2 the installation terminates immediately. If you selected 1, the following message appears, asking you to select a target installation directory:

      Enter directory for product files or leave blank to accept the default value.
      The default target directory is H:\Liberty\WMQ
      Target directory for product files?

4. Specify the installation directory for the resource adapter:
   • To install the resource adapter in the default location, press Enter without specifying a value.
   • To install the resource adapter in a different location from the default, specify the name of the directory in which we want to install the resource adapter and then press Enter.

   After the files have been installed in the selected location, a confirmation message is displayed as shown in the following example:

   Extracting files to H:\Liberty\WMQ\wmq
   Successfully extracted all product files.

   During the installation, a new directory with the name wmq is created within the selected installation directory, and the following files are then installed in the wmq directory:
   • The installation verification test program, wmq.jmsra.ivt.
   • The IBM MQ RAR file, wmq.jmsra.rar.

5. Configure the resource adapter in WebSphere Liberty. The steps that we must take to configure the resource adapter in Liberty are as follows. For more information, see the WebSphere Application Server product documentation.
   1. Add the wmqJmsClient-2.0 feature to the server.xml file to allow working with the IBM MQ Version 9.1 resource adapter. For more information, see Which version of the resource adapter to use.
   2. Add a reference to the wmq.jmsra.rar file that we have installed.

   Note: For Liberty versions up to Version 8.5.5, Fix Pack 1, if an EJB is deployed using solely the configuration within the ejb-jar.xml, the version of WebSphere Application Server that the Liberty Profile is using must have APAR PM89890 applied. This method of configuration is used for the resource adapter's installation verification program (IVT), so this APAR is required in order for the IVT to run. An example configuration to support servlets and MDBs, with JNDI might look like this:

    <featureManager>         
       <feature>wmqJmsClient-2.0</feature>       
       <feature>servlet-3.0</feature>       
       <feature>jmsMdb-3.1</feature>          
       <feature>jndi-1.0</feature>                     
       </featureManager>
   
   <variable name="wmqJmsClient.rar.location"                    
         value="H:\Liberty\WMQ\wmq\wmq.jmsra.rar"/>

Parent topic: Installing the IBM MQ resource adapter