Developing a JAX-RPC client for WebSphere transport for SOAP using Eclipse

Develop an Axis 1.4 web service client to run using the IBM MQ transport for SOAP.

Before you begin

The task shows the development of three types of client for the sample StockQuoteAxis service using Eclipse running on Windows. The clients are a static and dynamic client developed using the client proxy, and a DII client.

1. Generating client proxies using amqwdeployWMQService.
2. Importing WSDL into Eclipse, and using the web service wizard to generate the client proxies.

Procedure

1. Start the Eclipse IDE for Java EE developers.
2. Create a Java project called StockQuoteAxisClient:
   1. Switch to the Java perspective > File > New > Java Project. In the Project name field of the Create a Java Project page type, StockQuoteAxisEclipseClient. Make sure that the execution environment is either J2SE1-1.4 or J2SE-1.5 > Next.
   2. On the Java Settings page, select the Libraries tab > Add External JARs...
   3. Browse to MQ_INSTALLATION_PATH/java/lib and select all the .jar files > Open. MQ_INSTALLATION_PATH is the directory where IBM MQ is installed.
   4. Browse to MQ_INSTALLATION_PATH/java/lib/soap and select all the .jar files > Open. You must have installed axis.jar from the IBM MQ installation media into this directory. MQ_INSTALLATION_PATH is the directory where IBM MQ is installed.
   5. The Library tab now references all the .jar files needed to build the client> Finish.
3. Follow one of these two approaches to create proxies in Eclipse for the sample StockQuoteAxis web service:
   • Generate the client proxies using amqwdeployWMQService.
     1. Create a queue manager. For the task create QM1 as the default queue manager.
     2. Create a working directory, samples. Copy the StockQuoteAxis.java sample program into samples/soap/server.
     3. Modify amqwsetcp.cmd in MQ_INSTALLATION_PATH/bin to include the current directory in the classpath. MQ_INSTALLATION_PATH is the directory where IBM MQ is installed.
     4. Open a command window in samples and run the modified amqwsetcp command
     5. Create WSDL for the StockQuoteAxis service by running the command,

        amqwdeployWMQService -f soap/server/StockQuoteAxis.java -c genAxisWsdl
        -u "jms:/queue?destination=REQUESTAXIS
        &initialContextFactory=com.ibm.mq.jms.Nojndi
        &connectionFactory=(connectQueueManager(QM1)binding(auto))"

        Remember: Use /, rather than . or \ when using Java commands. Tip: Rather than import the generated proxies into Eclipse, we can import the generated WSDL from .samples/generated. The resulting proxies differ in two ways:
        1. The package names are different - which we can refactor.
        2. The Eclipse generated proxies include an additional helper class, StockQuoteAxisProxy.java
     6. Create the client proxies for the StockQuoteAxis service by running the command:

        amqwdeployWMQService -f soap/server/StockQuoteAxis.java -c genProxiestoAxis
        -u "jms:/queue?destination=REQUESTAXIS
        &initialContextFactory=com.ibm.mq.jms.Nojndi
        &connectionFactory=(connectQueueManager(QM1)binding(auto))"

     7. Import the client proxies into StockQuoteAxisClient:
        1. Right click StockQuoteAxisClient\src > Select File System > Next > Browse... > find the folder .\samples\generated\client\remote\soap\server > OK.
        2. Check server in the Import page > Finish.
     8. Refactor the package name to soap.server.
        1. Right click the package containing the client proxies > Refactor > Rename. Type the New name: soap.server > leave the selected defaults for the other choices > OK. All the errors are fixed.
   • Generate the client proxies using Eclipse.

     You have a choice of ways of obtaining the WSDL for the service. In this example, the service has been deployed to the Liberty profile and you obtain the WSDL from the Web server.

     1. In Eclipse, switch to the Web perspective, and check that the Liberty profile is running and StockQuoteAxis is deployed and synchronized.
     2. Import the WSDL into Web Services Explorer:
        1. Click the Web Services Explorer icon in the action-bar, or click Run > Launch the Web Services Explorer.
        2. Click the WSDL page icon in the Web Services Explorer to switch to the WSDL page.
        3. Click WSDL Main in the Navigator window of the Web Services Explorer.
        4. Type in the URL of the web service, followed by ?WSDL. The URL for StockQuoteAxis, deployed in the Liberty profile, is:

           http://localhost:8080/StockQuoteAxis/services/StockQuoteAxis?wsdl

     3. Generate the client proxies:
        1. In the Web Services Explorer navigator, click http://localhost:8080/StockQuoteAxis/services/StockQuoteAxis?wsdl.
        2. In the Actions window, click Launch Web Service Wizard > leave Web Service Client selected > Go.
        3. On the first page of the wizard, click the Client project link in the configuration > Select the StockQuoteAxisClient client project > OK. Tip: The wizard window might lose focus. You need to bring it back into focus manually.
        4. The web service runtime must be Apache Axis to generate a JAX-RPC client.
        5. Click Finish.
        6. Change the static URL of the service to point to the IBM MQ transport for SOAP address for the StockQuoteAxis service. You might choose to skip this step, until we have tested the client with an HTTP server.
           1. Open StockQuoteAxisServiceLocator.java and find the declaration for StockQuoteAxis_address.
           2. Change the URL to

              "jms:/queue?destination=REQUESTAXIS
              &initialContextFactory=com.ibm.mq.jms.Nojndi
              &connectionFactory=(connectQueueManager(QM1)binding(auto))"

              Tip: Eclipse automatically transforms & to &, and the reverse, when you copy and paste strings into .java code.
     4. Create three Java client classes, each with a main method:
        1. Create package. Right click StockQuoteAxisClient/src > New Package. Name it soap.client > Finish.
        2. Select soap.client > New > Class. Name the class SQAStaticClient > Check public static void main(string [] args) > Finish
        3. Repeat the procedure to create SQADynamicClient.java and SQADIIClient.java
     5. Write the client code.

        Figure 4 through Figure 8 provide examples of the three styles of client code. The examples use an HTTP URL to test the client using the StockQuoteAxis service deployed to an HTTP server. To run the clients against the StockQuoteAxis service deployed using IBM MQ transport for SOAP, change the URL to:

        "jms:/queue?destination=REQUESTAXIS
        connectionFactory=(connectQueueManager(QM1)binding(auto))
        initialContextFactory=com.ibm.mq.jms.Nojndi
        targetService=soap.server.StockQuoteAxis.java
        replyDestination=SYSTEM.SOAP.RESPONSE.QUEUE"

        • Figure 4 and Figure 6 use the proxy generated by Eclipse, which has the extra StockQuoteAxisproxy helper class that makes coding a little easier.
        • Figure 5 and Figure 7 use the proxy generated by amqwdeployWMQService.
        • Figure 8 uses no proxy classes.
        Each of the clients call com.ibm.mq.soap.Register.extension() to link to the IBM MQ transport for SOAP. The extension is registered in the client deployment descriptor. Client deployment to Axis 1.4 is described in Deploying a web service client to Axis 1.4 to use IBM MQ transport for SOAP.
     6. Run the clients by sending the SOAP request to StockQuoteAxis hosted by the WebSphere Application Server Community Edition server configured in the workspace.
        1. Check that the server is running, StockQuoteAxis is deployed and synchronized.
        2. Select or open the client you want to test > Click Run in the action bar. Alternatively, click the green Run icon or eight click the client in the navigator > Run As > Run Configurations .... Configure the parameters you require to run the client.
     7. Run the client using the IBM MQ transport for SOAP.

        The procedure uses amqwdeployWMQService to deploy the service, and only works with the client that uses the WSDL or proxies built by amqwdeployWMQService. To run the client using the original WSDL, or proxies built by eclipse, deploy the service with its deployment descriptor built by Eclipse. Manually start SimpleJavaListener using the service port binding name as the targetServiceName.

        1. Follow the instructions in Deploying a service to Axis 1.4 to use for WebSphere transport for SOAP using amqwdeployWMQService to deploy the service to the IBM MQ Simple Java SOAP listener. The service deployment works only for the client using the WSDL or client proxies built by amqwdeployWMQService.
        2. In a command window, run amqwclientconfig to create the client deployment descriptor file, client-deploy.wsdd.
        3. Import client-deploy.wsdd into the root of the Java project you want to test using IBM MQ transport for SOAP.
           1. Right click the Java project StockQuoteAxisEclipseClient > Import > File system > Next > Browse...
           2. Browse to the directory containing client-deploy.wsdd > Open > Select the directory in the Import wizard page > check client-deploy.wsdd.
           3. Verify Into folder: has StockQuoteAxisEclipseClient entered > Finish.
        4. Confirm that the working directory for running a Java application in this project is the StockQuoteAxisEclipseClient directory: Right click the Java project StockQuoteAxisEclipseClient > Run as.... > Run Configurations... > Select the (x)= Arguments tab > Verify that in Working Directory the Default radio button is checked, and the path is StockQuoteAxisEclipseClient. Alternatively make one of the following choices to select a different location or file containing the client configuration:
           • Check Other: > type a directory path of your choice.
           • In the VM arguments window, type -Daxis.ClientConfigFile= full path to client deployment descriptor file
        5. Make sure the URL is configured to point to the service deployed using IBM MQ transport for SOAP. Run the client as described in step ii.
        Tip: Typically, you might encounter one of these errors:
        1. Exception: No client transport named 'jms' found! .
        2. A JMS connection error.
        3. Exception: The AXIS engine could not find a target service to invoke! targetService is soap.server.StockQuoteAxis.java
        4. Exception: java.lang.InstantiationException: soap.server.StockQuoteAxis
        Explanations:
        1. client-config.wsdd is not found, or does include the line <transport name="jms" pivot="java:com.ibm.mq.soap.transport.jms.WMQSender"/> in client-config.wsdd.
        2. Possibly a build path problem - not including the .jar files in MQ_INSTALLATION_PATH/java/lib. MQ_INSTALLATION_PATH is the directory where IBM MQ is installed.
        3. Service deployment problem, either with server-config-wsdd, or with parameters passed to SimpleSoapListener.
        4. Mismatch between deployment descriptor and the implementation of the service.
        If you are having difficulty running the client in Eclipse, try using a command window:
        1. Switch to the StockQuoteAxisEclipseClient\bin directory in the workspace directory tree.
        2. Run amqwsetcp and amqwclientconfig
        3. Run java soap/client/SQAStaticClient.

Sample JAX-RPC web service clients

SQAxis2Axis.java

SQAxis2Axis.java, Figure 1, is a dynamic proxy client to invoke the StockQuoteAxis service. We can override the URL of the service, which is compiled into the dynamic proxy, by providing a URL on the command line.

SQAxis2DotNet.java

SQAxis2DotNet.java, Figure 2, is a dynamic proxy client to invoke the StockQuoteDotNet service. We can override the URL of the service, which is compiled into the dynamic proxy, by providing a URL on the command line.

WsdlClient.java

WsdlClient.java, Figure 3, is a dynamic invocation client to invoke either the StockQuoteDotNet or StockQuoteAxis service. The client invokes the StockQuoteAxis service by default. Add the command-line option -D invoke the StockQuoteDotNet service and -w to provide a different port to the one in .\generated\StockQuoteDotNet_Wmq.wsdl

package soap.clients;
import java.net.URL;
import soap.server.*;
public class SQAxis2Axis {
   public static void main(String[] args) {
      com.ibm.mq.soap.Register.extension();
      try {
         StockQuoteAxisService locator = new StockQuoteAxisServiceLocator();
         StockQuoteAxis service = null;
         if (args.length == 0)
            service = locator.getSoapServerStockQuoteAxis_Wmq();
         else
            service = locator.getSoapServerStockQuoteAxis_Wmq(
                new java.net.URL(args[0]));
         System.out.println("Response: " + service.getQuote("XXX"));
      } catch (Exception e) {
         System.out.println("\n>>> EXCEPTION WHILE RUNNING ProxyClient DEMO <<<\n");
                            e.printStackTrace();
         System.exit(2);
      }
  }

public class SQAxis2DotNet {
public static void main(String[] args) {
   com.ibm.mq.soap.Register.extension();
      try {
         StockQuoteDotNet locator = new StockQuoteDotNetLocator();
         StockQuoteDotNetSoap_PortType service = null;
         if (args.length == 0)
            service = locator.getStockQuoteDotNetSoap();
         else
            service = locator.getStockQuoteDotNetSoap(new java.net.URL(
                  args[0]));
         System.out.println("Response: " + service.getQuoteDOC("XXX"));
      } catch (Exception e) {
         System.out.println("\n>>> EXCEPTION WHILE RUNNING ProxyClient DEMO <<<\n");
                            e.printStackTrace();
         System.exit(2);
      }
   }
}

package soap.clients;
import com.ibm.mq.soap.*;
import org.apache.axis.utils.Options;
import java.net.URL;
import javax.xml.rpc.Call;
import javax.xml.rpc.Service;
import javax.xml.rpc.ServiceFactory;
import javax.xml.namespace.QName;
public class WsdlClient {
public static void main(String[] args) {
      String wsdlService, wsdlPort, namespace, wsdlSource, wsdlTargetURI, s;
      try {
         Register.extension();
         Options opts = new Options(args);
         if (opts.isFlagSet('D') != 0) {
            wsdlService = "StockQuoteDotNet";
            wsdlPort = "StockQuoteDotNetSoap";
            namespace = "http://stock.samples";
            wsdlSource = "file:generated/StockQuoteDotNet_Wmq.wsdl";
         } else {
            wsdlService = "StockQuoteAxisService";
            wsdlPort = "soap.server.StockQuoteAxis_Wmq";
            namespace = "soap.server.StockQuoteAxis_Wmq";
            wsdlSource = "file:generated/soap.server.StockQuoteAxis_Wmq.wsdl";
         if (null != (s = (opts.isValueSet('w'))))
            wsdlPort = s;
         System.out.println("start WsdlClient demo, wsdl port " + wsdlPort
               + " resolving uri to ...");
         QName servQN = new QName(namespace, wsdlService);
         QName portQN = new QName(namespace, wsdlPort);
         Service service = ServiceFactory.newInstance().createService(
               new URL(wsdlSource), servQN);
         Call call = (Call) service.createCall(portQN, "getQuote");
         wsdlTargetURI = call.getTargetEndpointAddress().toString();
         System.out.println("  '" + wsdlTargetURI + "'");
         Object ret = call.invoke(new Object[] { "XXX" });
         System.out.println("Response: " + ret);
      } catch (Exception e) {
         System.out.println("\n>>> EXCEPTION WHILE RUNNING WsdlClient DEMO <<<\n");
         e.printStackTrace();
         System.exit(2);
      }
   }
}

package soap.client;
import soap.server.StockQuoteAxisProxy;
public class SQAStaticClient {
  public static void main(String[] args) {
    try {
      com.ibm.mq.soap.Register.extension();
      StockQuoteAxisProxy sqa = new StockQuoteAxisProxy();
      System.out.println("Static client synchronous result is:" 
          + sqa.getQuote("ibm"));
    } catch (Exception e) {
      System.out.println("Exception: " + e);
    }
  }
}

package soap.client;
import soap.server.StockQuoteAxis;
import soap.server.StockQuoteAxisService;
import soap.server.StockQuoteAxisServiceLocator;
public class SQAStaticClient {
  public static void main(String[] args) {
    try {
      com.ibm.mq.soap.Register.extension();
      StockQuoteAxisService locator = new StockQuoteAxisServiceLocator();
      StockQuoteAxis sqa = locator.getSoapServerStockQuoteAxis_Wmq();
      System.out.println("Static client synchronous result is: "
          + sqa.getQuote("ibm"));
    } catch (Exception e) {
      System.out.println("Exception: " + e);
    }
  }
}

package soap.client;
import soap.server.StockQuoteAxisProxy;
public class SQADynamicClient {
  public static void main(String[] args) {
    try {
      com.ibm.mq.soap.Register.extension();
      StockQuoteAxisProxy sqa = new StockQuoteAxisProxy(
          "http://localhost:8080/StockQuoteAxis/services/StockQuoteAxis");
      System.out.println("Dynamic client synchronous result is: "
          + sqa.getQuote("ibm"));
    } catch (Exception e) {
      System.out.println("Exception: " + e);
    }
  }
}

package soap.client;

import java.net.URL;
import soap.server.StockQuoteAxis;
import soap.server.StockQuoteAxisService;
import soap.server.StockQuoteAxisServiceLocator;
public class SQADynamicClient {
  public static void main(String[] args) {
    try {
      com.ibm.mq.soap.Register.extension();
      URL sqaURL = new URL(
          "http://localhost:8080/StockQuoteAxis/services/StockQuoteAxis");
      StockQuoteAxisService locator = new StockQuoteAxisServiceLocator();
      StockQuoteAxis sqa = locator.getSoapServerStockQuoteAxis_Wmq(sqaURL);
      System.out.println("Dynamic client synchronous result is: "
          + sqa.getQuote("ibm"));
    } catch (Exception e) {
      System.out.println("Exception: " + e);
    }
  }
}

package soap.client;
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.rpc.Call;
import javax.xml.rpc.Service;
import javax.xml.rpc.ServiceFactory;
public class SQADIIClient {
  public static void main(String[] args) {
    try {
      com.ibm.mq.soap.Register.extension();
      URL wsdl = new URL(
          "http://localhost:8080/StockQuoteAxis/services/StockQuoteAxis?wsdl");
      Service SQAService = (ServiceFactory.newInstance()).createService(wsdl,
          new QName("http://server.soap", "StockQuoteAxisService"));
      Call SQACall = SQAService.createCall(new QName("http://server.soap",
          "StockQuoteAxis"), "getQuote");
      System.out.println("DII client synchronous result is "
          + SQACall.invoke(new Object[] { "ibm" }));
    } catch (Exception e) {
      System.out.println("Exception: " + e);
    }
  }
}