<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" xml:lang="en" xml:id="WebSphereMQ"><info><title>Using WebSphere MQ JMS guide</title></info>
  
  <para>
    This document explains how WebSphere MQ (formerly MQSeries) can be used as JMS provider within a JOnAS application server.
  </para>
  <para>
    WebSphere MQ is the messaging platform developed by IBM. It provides Java and JMS interfaces. Documentation is located at 
    <link xlink:href="http://www-3.ibm.com/software/integration/mqfamily/library/manualsa/">
       http://www-3.ibm.com/software/integration/mqfamily/library/manualsa/
    </link>
    .
  </para>
  <para>
    This document was written after integration work done with JOnAS 3.3 and 3.3.1 and WebSphere MQ 5.3.
  </para>
  <para>
    This document may be used only when working with JOnAS 3.3
  </para>
  <para>
    Since JOnAS 4.8 a specific resource adaptor JCA JOnAS-MQ is available for accessing to WebSphere MQ. The corresponding documentation is currently being written and will be available soon.
  </para>
  <section xml:id="WebSphereMQ-Architecture"><info><title>Architectural rules</title></info>
    
    <para>
      WebSphere MQ, contrary to JORAM or SwiftMQ, cannot run collocated with JOnAS. WebSphere MQ is an external software which must be independently administered and configured.
    </para>
    <para>
      Administering WebSphere MQ consists of the following:
    </para>
    <itemizedlist>
      <listitem><para>
        Creating and configuring resources (such as queues) through the     WebSphere MQ Explorer tool.
      </para></listitem>
      <listitem><para>
        Creating the corresponding JMS objects (
        <literal>
          javax.jms.Queue
        </literal>
        ,     
        <literal>
          javax.jms.Topic
        </literal>
        , 
        <literal>
          javax.jms.QueueConnectionFactory
        </literal>
        ,     etc.), and binding them to a registry.
      </para></listitem>
    </itemizedlist>
    <para>
      The link between JOnAS and WebSphere MQ is established via the registry. WebSphere MQ JMS objects are bound to the JOnAS registry. JMS lookups will then return the WebSphere MQ JMS objects, and messaging will take place through these objects.
    </para>
    <para>
      Given the complex configuration of WebSphere MQ JMS objects, it is not possible to create these objects from JOnAS. Therefore, during the starting phase, a JOnAS server expects that WebSphere MQ JMS objects have already been bound to the registry. Thus it is necessary to start an independent registry to which WebSphere MQ can bind its JMS objects, and which can also be used by the starting JOnAS server. The start-up sequence looks like the following:
    </para>
    <orderedlist>
      <listitem><para>
        Starting a registry.
      </para></listitem>
      <listitem><para>
        Creating and binding WebSphere MQ JMS objects.
      </para></listitem>
      <listitem><para>
        Launching the JOnAS server.
      </para></listitem>
    </orderedlist>
    <para>
      The following architecture is proposed:
    </para>
    <itemizedlist>
      <listitem><para>
        A JOnAS server (e.g., called "Registry") providing only a registry.
      </para></listitem>
      <listitem><para>
        A JOnAS server (e.g., called "EJB") using the registry service of     server "Registry."
      </para></listitem>
      <listitem><para>
        A WebSphere MQ server running locally.
      </para></listitem>
    </itemizedlist>
  </section>
  <section xml:id="WebSphereMQ-Environment"><info><title>Setting the JOnAS Environment</title></info>
    
    <para>
      The proposed architecture requires running two JOnAS server instances. For this, the following steps are proposed:
    </para>
    <orderedlist>
      <listitem><para>
        Create two base directories: e.g., 
        <literal>
          JONAS_REGISTRY
        </literal>
         and     
        <literal>
          JONAS_EJB
        </literal>
        .
      </para></listitem>
      <listitem><para>
        Set the JONAS_BASE environment variable so that it points to the     
        <literal>
          JONAS_REGISTRY
        </literal>
         directory.
      </para></listitem>
      <listitem><para>
        In the $JONAS_ROOT directory, type: 
        ant create_jonasbase.
      </para></listitem>
      <listitem><para>
        Set the JONAS_BASE environment variable so that it points to the     
        <literal>
          JONAS_EJB
        </literal>
         directory.
      </para></listitem>
      <listitem><para>
        In the $JONAS_ROOT directory, type: 
        ant create_jonasbase.
      </para></listitem>
    </orderedlist>
    <para>
      The JOnAS servers can now be configured independently.
    </para>
    <section xml:id="WebSphereMQ-Registry"><info><title>Configuring the "Registry" server</title></info>
      
      <para>
        The "Registry" server is the JOnAS server that will host the registry service. Its configuration files are in 
        <literal>
          JONAS_REGISTRY/conf
        </literal>
        .
      </para>
      <para>
        In the 
        <literal>
          jonas.properties
        </literal>
         files, declare only the registry and jmx services:
      </para>
      <para>
        <literal>
          jonas.services registry,jmx
        </literal>
      </para>
      <para>
        In the carol.properties file, declare the jeremie protocol:
      </para>
      <para>
        <literal>
          carol.protocols=jeremie
        </literal>
      </para>
      <para>
        Its port can also be configured:
      </para>
      <para>
        <literal>
          carol.jeremie.url=jrmi://localhost:2000
        </literal>
      </para>
    </section>
    <section xml:id="WebSphereMQ-EJB"><info><title>Configuring the "EJB" server</title></info>
      
      <para>
        The "EJB" server is the JOnAS server that will be used as the application server. Its configuration files are in 
        <literal>
          JONAS_EJB/conf
        </literal>
        . Libraries must be added in 
        <literal>
          JONAS_EJB/lib/ext
        </literal>
        .
      </para>
      <para>
        In the jonas.properties files, set the registry service as remote:
      </para>
      <para>
        <literal>
          jonas.service.registry.mode remote
        </literal>
      </para>
      <para>
        ... and the JMS service as WebSphere MQ:
      </para>
      <para>
        <literal>
          jonas.service.jms.mom org.objectweb.jonas_jms.JmsAdminForWSMQ
        </literal>
      </para>
      <para>
        In the carol.properties file, declare the jeremie protocol and set the correct port:
      </para>
      <para>
        <literal>
          carol.protocols=jeremie
        </literal>
        <literal>
          carol.jeremie.url=jrmi://localhost:2000
        </literal>
      </para>
      <para>
        In 
        <literal>
          lib/ext
        </literal>
        , the following libraries must be added:
      </para>
      <itemizedlist>
        <listitem><para>
          <literal>
            com.ibm.mqjms.jar
          </literal>
          , including WebSphere MQ JMS classes.
        </para></listitem>
        <listitem><para>
          <literal>
            com.ibm.mq.jar
          </literal>
          , also a WebSphere MQ library.
        </para></listitem>
      </itemizedlist>
    </section>
  </section>
  <section xml:id="WebSphereMQ-ConfiguringWebSphereMQ"><info><title>Configuring WebSphere MQ</title></info>
    
    <para>
      WebSphere MQ JMS administration is documented in chapter 5 of the 
      <link xlink:href="http://www-3.ibm.com/software/integration/mqfamily/library/manualsa/manuals/crosslatest.html">
         "WebSphere MQ Using Java"
      </link>
       document.
    </para>
    <para>
      The configuration file of the JMS administration tool must be edited so that the JOnAS registry is used for binding the JMS objects. This file is the 
      <literal>
        JMSAdmin.config
      </literal>
       file located in WebSphereMQ's 
      <literal>
        Java/bin
      </literal>
       directory. Set the factory and provider URL as follows:
    </para>
    <para>
      <literal>
        INITIAL_CONTEXT_FACTORY=org.objectweb.jeremie.libs.services.registry.
      </literal>
      <literal>
          jndi.JRMIInitialContextFactory
      </literal>
      <literal>
        PROVIDER_URL=jrmi://localhost:2000
      </literal>
    </para>
    <para>
      The JOnAS's 
      <literal>
        client.jar
      </literal>
       library must also be added to the classpath for WebSphere MQ.
    </para>
    <para>
      When starting, JOnAS expects JMS objects to have been created and bound to the registry. Those objects are connection factories, needed for connecting to WebSphere MQ destinations, and destinations.
    </para>
    <para>
      JOnAS automatically tries to access the following factories:
    </para>
    <itemizedlist>
      <listitem><para>
        An 
        <literal>
          XAConnectionFactory
        </literal>
        , bound with name "wsmqXACF".
      </para></listitem>
      <listitem><para>
        An 
        <literal>
          XAQueueConnectionFactory
        </literal>
        , bound with name "wsmqXAQCF".
      </para></listitem>
      <listitem><para>
        An 
        <literal>
          XATopicConnectionFactory
        </literal>
        , bound with name "wsmqXATCF".
      </para></listitem>
      <listitem><para>
        A 
        <literal>
          ConnectionFactory
        </literal>
        , bound with name "JCF".
      </para></listitem>
      <listitem><para>
        A 
        <literal>
          QueueConnectionFactory
        </literal>
        , bound with name "JQCF".
      </para></listitem>
      <listitem><para>
        A 
        <literal>
          TopicConnectionFactory
        </literal>
        , bound with name "JTCF".
      </para></listitem>
    </itemizedlist>
    <para>
      If one of these objects cannot be found, JOnAS will print a message that looks like the following:
    </para>
    <para>
      
      JmsAdminForWSMQ.start : WebSphere MQ XAConnectionFactory could not be retrieved from JNDI
    </para>
    <para>
      This does not prevent JOnAS from working. However, if there is no connection factory available, no JMS operations will be possible from JOnAS.
    </para>
    <para>
      If destinations have been declared in the 
      <literal>
        jonas.properties
      </literal>
       file, JOnAS will also expect to find them. For example, if the following destinations are declared:
    </para>
    <para>
      <literal>
        jonas.service.jms.topics sampleTopic
      </literal>
      <literal>
        jonas.service.jms.queues sampleQueue
      </literal>
    </para>
    <para>
      The server expects to find the following JMS objects in the registry:
    </para>
    <itemizedlist>
      <listitem><para>
        A 
        <literal>
          Queue
        </literal>
        , bound with name "sampleQueue".
      </para></listitem>
      <listitem><para>
        A 
        <literal>
          Topic
        </literal>
        , bound with name "sampleTopic".
      </para></listitem>
    </itemizedlist>
    <para>
      If one of the declared destination cannot be retrieved, the following message appears and the server stops:
    </para>
    <para>
      
      JOnAS error: org.objectweb.jonas.service.ServiceException : Cannot init/start service jms': org.objectweb.jonas.service.ServiceException : JMS Service Cannot create administered object: java.lang.Exception: WebSphere MQ Queue creation impossible from JOnAS
    </para>
    <para>
      Contrary to connection factories, the JOnAS administration tool allows destinations to be created. Since it is not possible to create WebSphere MQ JMS objects from JOnAS, this will work only if the destinations are previously created and bound to the registry.
    </para>
    <para>
      For example, if you want to create a queue named "myQueue" through the JonasAdmin tool, this will only work if:
    </para>
    <itemizedlist>
      <listitem><para>
        A queue has been created through the WebSphere MQ Explorer tool.
      </para></listitem>
      <listitem><para>
        The corresponding JMS 
        <literal>
          Queue
        </literal>
         has been created and bound to the     registry with the name "myQueue".
      </para></listitem>
    </itemizedlist>
    <para>
      To launch WebSphere MQ administration tool, type: 
      JMSAdmin
    </para>
    <para>
      The following prompt appears: 
      InitCtx&gt;
    </para>
    <para>
      To create a 
      <literal>
        QueueConnectionFactory
      </literal>
       and binding it with name "JQCF", type:
    </para>
    <para>
      
      InitCtx&gt; DEF QCF(JQCF)
    </para>
    <para>
      More parameters can be entered (for example for specifying the queue manager).
    </para>
    <para>
      To create a 
      <literal>
        Queue
      </literal>
       that represents a WebSphere MQ queue named "myWSMQqueue", and to bind it with name "sampleQueue", type:
    </para>
    <para>
      
      InitCtx&gt; DEF Q(sampleQueue) QUEUE(myWSMQqueue)
    </para>
    <para>
      Objects bound in the registry can be viewed by typing:
    </para>
    <para>
      
      InitCtx&gt; DIS CTX
    </para>
  </section>
  <section xml:id="WebSphereMQ-Starting"><info><title>Starting the application</title></info>
    
    <para>
      To start the registry server:
    </para>
    <orderedlist>
      <listitem><para>
        Clean the local CLASSPATH: 
        set/export CLASSPATH="".
      </para></listitem>
      <listitem><para>
        Set the JONAS_BASE variable so that it points to     
        <literal>
          JONAS_REGISTRY
        </literal>
        .
      </para></listitem>
      <listitem><para>
        Start the JOnAS server: 
        jonas start -n Registry.
      </para></listitem>
    </orderedlist>
    <para>
      To administer WebSphere MQ:
    </para>
    <orderedlist>
      <listitem><para>
        In WebSphere MQ's 
        <literal>
          Java/bin
        </literal>
         directory, launch the JMSAdmin     tool: 
        JMSAdmin.
      </para></listitem>
      <listitem><para>
        Create the needed JMS objects.
      </para></listitem>
    </orderedlist>
    <para>
      To start the EJB server:
    </para>
    <orderedlist>
      <listitem><para>
        Clean the local CLASSPATH: 
        set/export CLASSPATH="".
      </para></listitem>
      <listitem><para>
        Set the JONAS_BASE variable so that it points to   
        <literal>
          JONAS_EJB
        </literal>
        .
      </para></listitem>
      <listitem><para>
        Start the JOnAS server: 
        jonas start -n EJB.
      </para></listitem>
    </orderedlist>
    <para>
      To start an EJB client:
    </para>
    <orderedlist>
      <listitem><para>
        Add in the jclient classpath the 
        <literal>
          ibm.com.mq.jar
        </literal>
         and     
        <literal>
          ibm.com.mqjms.jar
        </literal>
         libraries.
      </para></listitem>
      <listitem><para>
        Launch the client: 
        jclient ...
      </para></listitem>
    </orderedlist>
  </section>
  <section xml:id="WebSphereMQ-Limitations"><info><title>Limitations</title></info>
    
    <para>
      Using WebSphere MQ as JMS transport within JOnAS has some limitations, as compared with using JORAM or SwiftMQ.
    </para>
    <para>
      First of all, WebSphere MQ is compliant with the old 1.0.2b JMS specifications. Code that is written following the JMS 1.1 latest spec (such as the jms samples provided with JOnAS) will not work with WebSphere MQ.
    </para>
    <para>
      Depending on the WebSphere MQ distribution, JMS Publish/Subscribe may not be available. In this case, the message-driven bean samples provided with JOnAS will not work. For this reason, a 
      <link xlink:href="WebSphereMQsample.tar">
        specific sample
      </link>
       is provided.
    </para>
    <para>
      Finally, for an unknown reason, asynchronous consumption of messages (through message-driven beans) does not work in transactional mode. Further inquiry is needed to resolve this issue.
    </para>
  </section>
</chapter>