An Example WebSphere Configuration With MQ and DCS

Transcription

1 An Example WebSphere Configuration With MQ and DCS Scope: This document outlines example steps to implement DCS-1.6 in a WebSphere 6.1 AS and MQ 7 environment. It is by no means, definitive, as there are as many ways to achieve this, as there are individual deployment scenarios. Audience: This document is targetted at personnel required to deploy DOC1 DCS-1.6 into an existing WebSphere/MQ network topology. It is recommended that such personnel have access to experienced WebSphere and MQ resource. Example Topology: This example was configured on a single virtual machine for demonstration purposes, but would normally be expected to reside on multiple hosts. Whilst the Application Server-side code will run on any Websphere supported host platform, the DCS Adapter must reside on one of the DOC1 supported hosts as documented in the Release Notes. Software Platform: HostOS: Windows 2003 Server SP2 WAS: (Without Webservices or EJB3 Feature Packs) MQ: DCS: 1.6 Configuration Details: The key elements of the configuration are: Setup of the MQ resources. Setup of the WebSphere AS and DCS Manager. Setup of the JNDI resource. Setup of the DCS Adapter. Sample MQ Setup: Two Queue Managers were created within the MQ Server. These were called and TEST02. For illustration purposes, is considered the server-side QMGR and TEST02 is considered the Adapter-side QMGR. In, a RequestQueue was created to run via an MQ Channel to TEST02. A similar ResponseQueue was created from TEST02 to. Finally, a Topic was created on each QMGR. These Topics need to have the same 'Topic String' in order to create a 'Cluster Topic' when the two QMGRs are clustered. This, effectively, connects the Topic across the QMGRs to allow the Adapter to advertise itself to the DCS Manager. Sample WebSphere Setup: For new WebSphere installations, an environment variable needs to be modified to link it to the MQ installation. This is done in the Admin Console by navigating to the 'Environment->WebSphere Variables' page and selecting the 'Node' scope. There is a variable called 'MQ_INSTALL_ROOT' which is configured for WebSphere's internal MQ libraries. This is changed to refer to the root directory of the MQ installation. In a similar way to the installation guide, the Queue/Topic ConnectionFactories, Queues and Topic were created to match the naming convention as documented. Note that the steps to configure the Service Integration Bus are no longer required as this is replaced by MQ. Configuration also differs from the documentation, in that, the 'Default Messaging Provider' is replaced by 'WebSphere MQ Messaging Provider'.

2 QueueConnectionFactory: Queue Manager: Transport type: DCS..QCF DCS//QCF CLIENT TopicConnectionFactory: Queue Manager: Transport type: Broker subscription queue: Broker CC subscription queue: Broker version: DCS..TCF DCS//TCF CLIENT SYSTEM..ND.SUBSCRIBER.QUEUE SYSTEM..ND.CC.SUBSCRIBER.QUEUE BASIC Queues: Base queue name: Base queue manager name: Base queue name: Base queue manager name: DCS..RequestQueue DCS//RequestQueue as per the MQ RequestQueue DCS..ResponseQueue DCS//ResponseQueue as per the MQ ResponseQueue Topic: Base topic name: Broker durable subscription queue: Broker CC durable subscription queue: DCS..Bus DCS//Bus 'Topic String' as per MQ SYSTEM..D.SUBSCRIBER.QUEUE SYSTEM..D.CC.SUBSCRIBER.QUEUE

3 At this point, the DCS Manager code was deployed as normal. Sample JNDI Setup: This example is slightly complicated by the fact that it is running on a single host with two distinct QMGR names. Potentially, with separate hosts and identical QMGR names, it could have used the same JNDI names as the server-side and by using 'localhost' in the above configuration, a simplified configuration could be achieved. This section does, however, show some of the flexibility gained from the SpringFramework used within DCS. In MQ 7, there is the ability to 'convert' the configured queues and topics to JNDI resources. In this example, a simple file-based JNDI source was configured to contain the client-side structures. This uses additional libraries from the MQ installation to provide the 'com.sun.jndi.fscontext.reffscontextfactory' class required for a file-based JNDI system. The JNDI source was created to contain entries for the Queue/Topic ConnectionFactories, Queues and Topic required for the adapter configuration later. Also, in this example, the adapter BootstrapPort was configured so as to still use the Application Server as it's JNDI source. To overcome this complication, the Application Server was configured with 'indirect' JNDI references back to the MQ configured file-based resource. This was done via the 'Environment->Naming->Name space binding' page. Each reference was created as an indirect binding type and the following attributes: Binding identifier: Name in name space: Provider URL: Initial context factory name: file:/c:/jndi (also as per MQ) com.sun.jndi.fscontext.reffscontextfactory Sample Adapter Setup: Before the adapter setup could be completed, the WebSphere 'launchclient' script had to be modified to incorporate the MQ jar libraries. There is an environment variable, _PATH, in this script which contains the paths to the original WebSphere versions of these libraries. These were updated accordingly. Note: With this example, it was later found that WebSphere would not populate the classpath correctly when exploding the Adapter ear file. To compensate for this, the ear file was manually exploded and the jar files added to the _PATH, manually. Also, some additional libraries, from MQ, were added to incorporate the file-based JNDI lookup. Specifically, fscontext.jar, jndi.jar and providerutil.jar. Before exploding the ear file, the configclient tool was run to fixup it's internal resource references. This is similar to the installation guide except that 'Websphere MQ' is configured instead of 'Default Messaging'. The final step was to modify the doc1gen-adapter.xml file to resolve the MQ connections: <!-- These are the JNDI references that will be used for the requests and responses. Note that the IDs --> <!-- for these must remain as specified here because they are referenced by the application code. --> <jee:jndi-lookup id="connectionconnectionfactory" jndi-name="file:/c:/jndi/queueconnectionfactory"/> <jee:jndi-lookup id="connectioninbounddestination" jndi-name="file:/c:/jndi/jms_requestqueue"/> <jee:jndi-lookup id="connectionoutbounddestination" jndi-name="file:/c:/jndi/jms_responsequeue"/> <!-- These are the JNDI references that will be used for the bus between managers and adapters. Note the --> <!-- IDs for these must remain the same as they are referenced by the application code. --> <jee:jndi-lookup id="busconnectionfactory" jndi-name="file:/c:/jndi/busconnectionfactory"/> <jee:jndi-lookup id="busdestination" jndi-name="file:/c:/jndi/dcs Bus"/>

4 Note that the 'jndi-name' is effectively the concatenation of the 'Provider URL' and the JNDI name from the Application Server 'indirect' name lookup. This tells Spring how to deal with this reference using the 'com.sun.jndi.fscontext.reffscontextfactory' class. Further footnote: The WebSphere BootstrapPort can be overriden completely with the launchclient parameter: '-CCproviderURL='. As per the above sample: -CCproviderURL=file:/C:/JNDI This negates the need for the complex JNDI setup through the Application Server and allows the adapter to startup without the server running as long as MQ is up. Websphere Now tested and working with WAS 7/MQ 7. Configuration is similar, if not easier, with WAS 7. It is no longer necessary to manually explode or include the Adapter jar files. LaunchClient no longer has a _PATH environment variable. It can be added if additional JNDI options are required, as per the previous example, and appended to the classpath. NB: Follow these links for some important information regarding the updating of the Resource Adapter in WAS 7: topic=/com.ibm.websphere.nd.multiplatform.doc/info/ae/ae/tmm_mig.html Late Breaking News It is possible to completely decouple the adapter from Websphere. Using the MQ JNDI utilities libraries and JAVA runtime, the adapter will run without a need for the Websphere client launcher. The following steps illustrate the setup: 1. Create a directory called provider in the adapter's lib directory. 2. Copy the required jar files from the MQ_INSTALL_ROOT\java\lib directory to the provider directory. 3. Set JAVA_HOME to point to the MQ_INSTALL_ROOT\java\jre. 4. Copy the bin\adapter-under-jboss.bat to bin\adapter.bat. 5. Create a copy of or rename the example.log4j.properties in the config directory as log4j.properties. 6. Edit the config\jndi.properties file to use the correct JNDI settings as follows: # These are the JNDI properties for JBoss java.naming.factory.initial=com.sun.jndi.fscontext.reffscontextfactory java.naming.provider.url=file:c:/jndi j2ee.clientname=documentcompositionadapter

5 The required jar files in step 2 when using file based JNDI are: com.ibm.mq.jar com.ibm.mq.jmqi.jar com.ibm.mqjms.jar dhbcore.jar fscontext.jar (for the file based JNDI) or ldap.jar (for LDAP based JNDI) jms.jar jndi.jar providerutil.jar This setup is similar to the JBoss configuration but requires no application server jar files. MQ Configuration with two Queue Managers Remote Queue: REQ.REM TXQ: REQ.TX Local Queue: REQ.REM Sender DCS.REQ Conn host(port) Receiver DCS.REQ QMGR01 QMGR02 Receiver DCS.RSP Sender DCS.RSP Conn host(port) Local Queue: RSP.REM TXQ: RSP.TX Remote Queue: RSP.REM Additionally requires a Cluster Topic shared between the two Queue Managers. Create triggers on each TX Queue using SYSTEM.CHANNEL.INITQ and data DCS.REQ and DCS.RSP respectively.