Deploying a Web service client to Axis2 to use WebSphere MQ transport for SOAP

Prepare a deployment directory and Axis2 configuration file for the client. Provide the client proxies and client class, and set up the CLASSPATH. Configure WebSphere® MQ queues and channels, start the service and test the client.

Before you begin

Tip: Deploy the service to HTTP. Develop and test the client for HTTP, and then modify the URL to reference the service using WebSphere MQ transport for SOAP.
The task shows how to deploy an unmanaged Axis2 client to Java Standard Edition. You might want to deploy an Axis2 client to a Web container. In Developing a JAX-WS client for WebSphere transport for SOAP using Eclipse, you developed a client in a Web container and deployed it to WebSphere Application Server Community Edition. As part of the server configuration, you enabled the Axis2 facet and included the facet in the configuration of the Web container. To configure Web containers on other application servers, refer to the Axis2 documentation, http://ws.apache.org/axis2/1_4_1/installationguide.html#servlet_container, or the documentation supplied with the Web server.
Note: Axis2 use the term, Servlet container. A Servlet container is the same as a Web container.

About this task

Deploying an Axis2 client to use WebSphere MQ transport for SOAP is like deploying an Axis2 client to use HTTP. Additional steps are required to provide a classpath to the WebSphere MQ JAR files, and to modify the Axis2 configuration file. The Axis2 configuration file requires an additional entry for JMS. The entry refers to the WebSphere MQ transport for SOAP JAR file that implements the JMS transportSender.

Axis2 provides a script, axis2.bat or axis2.sh, which simplifies client deployment; see the examples in Figure 4 and Figure 5.

Note:
  1. axis2.bat has a bug that must be corrected. The string -Djava.ext.dirs="%AXIS2_HOME%\lib\" must be changed to -Djava.ext.dirs="%AXIS2_HOME%\lib\\".

  2. In axis2.bat and axis2.sh, -Djava.ext.dirs is used as a quick way to reference all the Axis2 JAR files, instead of adding them separately to the classpath. Unfortunately this approach is flawed, and only works with some JREs. It does not work with the IBM® JREs.

    The JVM parameter, -Djava.ext.dirs="%AXIS2_HOME%\lib\\", makes the Axis JAR files available to the JVM. The JVM attempts to instantiate some of the Axis JAR files, and leads to an error, the details of which depend on the JVM. Typically, you might see one of the following lines in the stack trace: 
    org.apache.axiom.om.util.UUIDGenerator.getInitialUUID(UUIDGenerator.java:76)
    or org.apache.axis2.deployment.DeploymentException: java.security.NoSuchAlgorithmException: MD5 MessageDigest not available

    The correct way to run an unmanaged Axis2 client is to add the Axis2 JAR files to the classpath. The classpath is available only to the client application and not to the JVM.

The procedure describes the general steps to run an unmanaged Axis2 client without using the axis2 script. The examples in Figure 2 and Figure 3 are scripts for Windows and Linux®.

Procedure

  1. Download Axis2 1.4.1 from http://ws.apache.org/axis2/download/1_4_1/download.cgi and unpack into a folder, Axis2-1.4.1.
  2. Update axis2.xml in Axis2-1.4.1\conf.
    1. Update axis2.xml in Axis2-1.4.1\conf. Add WebSphere MQ transport for SOAP as a transportSender: 
      <transportSender name="jms" 
class="com.ibm.mq.axis2.transport.jms.WMQJMSTransportSender"/>
    2. If required, alter the size of the connection pool from the default of 10. 
      <transportSender name="jms" 
class="com.ibm.mq.axis2.transport.jms.WMQJMSTransportSender">
<parameter name="ResourcePoolCapacity">20</parameter>
</transportSender>

      ResourcePoolCapacity defines how many service endpoint entries are kept in the cache. The value must be at least 1. If the number of service endpoint entries exceeds the cache size, entries are deleted to make room for new entries. The size of an endpoint entry varies. Set a number that is large enough to avoid the cache thrashing.

    See step 3 in Developing a JAX-WS client for WebSphere transport for SOAP using Eclipse.
  3. Create a directory deployDir. Under this directory copy the folder structure containing the client and client proxies. deployDir is equivalent to the project\bin folder in an Eclipse Java project.
  4. Open a command window on Windows, or a command shell using X Window System on UNIX and Linux systems, in deployDir.
  5. Update the classpath to include the current directory, Axis2 JAR files, com.ibm.mqjms.jar and com.ibm.mq.axis2.jar.
    com.ibm.mqjms.jar references all the other WebSphere MQ JAR files that are required.
  6. Use the Java command to start the client program.

Examples

Four example of running an Axis2 client are listed in Figure 3 to Figure 5. Figure 1 shows the output from running the asynchronous client listed in Figure 2.
Figure 1. Output from running SQA2AsyncClient
cd C:\IBM\ID\Workspaces\Axis2docs\StockQuoteAxis2PojoClient\bin>
runpojo soap/client/SQA2AsyncClient

HTTP Sync: 55.25
Callback constructor
Waiting for HTTP callback
Result in Callback 55.25
HTTP poll: 55.25
JMS: Sync: 55.25
Callback constructor
Waiting for JMS callback
Result in Callback 55.25
JMS poll: 55.25
Press any key to continue . . .
Figure 2. runpojo.bat: Windows, using a classpath
@echo off
set AXIS2_HOME=C:\OpenSource\axis2-1.4.1
set JAVA_HOME=C:\IBM\Java50
set WMQ_HOME=C:\IBM\MQ\java\lib

setlocal EnableDelayedExpansion
set CLASSPATH=
set AXIS2_CLASS_PATH=
FOR %%c in ("%AXIS2_HOME%\lib\*.jar") DO set AXIS2_CLASS_PATH=!AXIS2_CLASS_PATH!;%%c

"%JAVA_HOME%\bin\java" -Daxis2.repo="%AXIS2_HOME%\repository" 
-Daxis2.xml="%AXIS2_HOME%\conf\axis2.xml" -cp 
".;%WMQ_HOME%\com.ibm.mqjms.jar;%WMQ_HOME%\com.ibm.mq.axis2.jar;%AXIS2_CLASS_PATH%" %1

pause
Figure 3. runpojo.sh: Linux, using a classpath.
export AXIS2_HOME=/home/OpenSource/axis2-1.4.1
export JAVA_HOME=/usr/lib/j2sdk1.5-ibm
# update classpath
AXIS2_CLASSPATH=""
for f in "$AXIS2_HOME"/lib/*.jar
do
  AXIS2_CLASSPATH="$AXIS2_CLASSPATH":$f
done
AXIS2_CLASSPATH="$AXIS2_HOME":"$JAVA_HOME/lib/tools.jar":"$AXIS2_CLASSPATH":"$CLASSPATH"
java -cp /home/alex/dev/sandbox/Soap/axis2:/opt/mqm/java/lib/com.ibm.mqjms.jar:
/opt/mqm/java/lib/com.ibm.mq.axis2.jar:$AXIS2_CLASSPATH 
-Daxis2.xml=/home/alex/dev/sandbox/axis2-1.4.1/conf/axis2.xml %1
Figure 4. runaxis2.bat: Windows, using axis2.bat
@echo off
set AXIS2_HOME=C:\OpenSource\axis2-1.4.1
set JAVA_HOME=C:\IBM\Java50
set WMQ_HOME=C:\IBM\MQ\java\lib

%AXIS2_HOME%\bin\axis2 -cp .;%WMQ_HOME%\com.ibm.mqjms.jar;%WMQ_HOME%\com.ibm.mq.axis2.jar; %1
pause
Note
Figure 5. runaxis2.sh: Linux, using axis2.sh
export AXIS2_HOME=/home/OpenSource/axis2-1.4.1
export JAVA_HOME=/usr/lib/j2sdk1.5-ibm

%AXIS2_HOME%\bin\axis2 -cp .;%WMQ_HOME%\com.ibm.mqjms.jar;%WMQ_HOME%\com.ibm.mq.axis2.jar; %1
Note