Installing the resource adapter in Liberty

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

Before you begin

Note: The information in this topic does not apply to WebSphere Application Server traditional 9.0. The IBM MQ 9.0 resource adapter is preinstalled within WebSphere Application Server traditional 9.0. Therefore, there is no requirement to install a new resource adapter in this case.

Before you start this task, make sure that you 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 you want the files to go in.

About this task

The JAR file for the resource adapter that you 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. You 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 your system. The directory is created as part of the installation if it does not exist.

Before IBM MQ 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 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, you 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 your 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 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, you 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 you can use, extract, or install IBM MQ V9.1, you 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 you 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 you 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:
    • If you want to install the resource adapter in the default location, press Enter without specifying a value.
    • If you want to install the resource adapter in a different location from the default, specify the name of the directory in which you 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 you 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 9.1 resource adapter.
    2. Add a reference to the wmq.jmsra.rar file that you have installed.
    Note: For Liberty versions up to WebSphere Liberty 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"/>