<?xml version="1.0" encoding=""?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta http-equiv="content-type" content="" />
  <title>Generating a Web Service Client using Axis2 and JiBX</title>
  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
  media="all" />
</head>

<body>
<h1 class="title">Generating a Web Service Client using Axis2 and JiBX</h1>

<p>This document explains how to generate a Web service client using Axis2
and JiBX data binding. The service has the following WSDL:</p>

<p><b>Code Listing 1: The WSDL file</b></p>
<pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;wsdl:definitions
   xmlns:apachesoap="http://xml.apache.org/xml-soap"
   xmlns:impl="http://apache.org/axis2/Axis2UserGuide"
   xmlns:intf="http://apache.org/axis2/Axis2UserGuide"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
   xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   targetNamespace="http://apache.org/axis2/Axis2UserGuide"&gt;

  &lt;wsdl:types&gt;
    &lt;schema
       elementFormDefault="qualified"
       targetNamespace="http://apache.org/axis2/Axis2UserGuide"
       xmlns="http://www.w3.org/2001/XMLSchema"&gt;
      
      &lt;!-- ELEMENTS --&gt;
      
      &lt;element name="DoInOnlyRequest"&gt;
        &lt;complexType&gt;
          &lt;sequence&gt;
            &lt;element name="messageString" type="xsd:string"/&gt;
          &lt;/sequence&gt;
        &lt;/complexType&gt;
      &lt;/element&gt;
      
      &lt;element name="TwoWayOneParameterEchoRequest"&gt;
        &lt;complexType&gt;
          &lt;sequence&gt;
            &lt;element name="echoString" type="xsd:string"/&gt;
          &lt;/sequence&gt;
        &lt;/complexType&gt;
      &lt;/element&gt;
      &lt;element name="TwoWayOneParameterEchoResponse"&gt;
        &lt;complexType&gt;
          &lt;sequence&gt;
            &lt;element name="echoString" type="xsd:string"/&gt;
          &lt;/sequence&gt;
        &lt;/complexType&gt;
      &lt;/element&gt;
      
      &lt;element name="NoParametersRequest"&gt;
        &lt;complexType/&gt;
      &lt;/element&gt;
      &lt;element name="NoParametersResponse"&gt;
        &lt;complexType/&gt;
      &lt;/element&gt;
      
      &lt;element name="MultipleParametersAddItemRequest"&gt;
        &lt;complexType&gt;
          &lt;sequence&gt;
            &lt;element name="itemId" type="xsd:int"/&gt;
            &lt;element name="itemName" type="xsd:string"/&gt;
            &lt;element name="price" type="xsd:float"/&gt;
            &lt;element name="description" type="xsd:string"/&gt;
          &lt;/sequence&gt;
        &lt;/complexType&gt;
      &lt;/element&gt;

      &lt;element name="MultipleParametersAddItemResponse"&gt;
        &lt;complexType&gt;
          &lt;sequence&gt;
          &lt;element name="itemId" type="xsd:int"/&gt;
          &lt;element name="successfulAdd" type="xsd:boolean"/&gt;
          &lt;/sequence&gt;
        &lt;/complexType&gt;
      &lt;/element&gt;

    &lt;/schema&gt;
  &lt;/wsdl:types&gt;

  
  &lt;!-- MESSAGES --&gt;

  &lt;wsdl:message name="DoInOnlyRequestMessage"&gt;
    &lt;wsdl:part name="input" element="impl:DoInOnlyRequest"/&gt;
  &lt;/wsdl:message&gt;

  &lt;wsdl:message name="TwoWayOneParameterEchoRequestMessage"&gt;
    &lt;wsdl:part name="input" element="impl:TwoWayOneParameterEchoRequest"/&gt;
  &lt;/wsdl:message&gt;
  &lt;wsdl:message name="TwoWayOneParameterEchoResponseMessage"&gt;
    &lt;wsdl:part name="output" element="impl:TwoWayOneParameterEchoResponse"/&gt;
  &lt;/wsdl:message&gt;

  &lt;wsdl:message name="NoParametersRequestMessage"&gt;
    &lt;wsdl:part name="input" element="impl:NoParametersRequest"/&gt;
  &lt;/wsdl:message&gt;
  &lt;wsdl:message name="NoParametersResponseMessage"&gt;
    &lt;wsdl:part name="output" element="impl:NoParametersResponse"/&gt;
  &lt;/wsdl:message&gt;

  &lt;wsdl:message name="MultipleParametersAddItemRequestMessage"&gt;
    &lt;wsdl:part name="input" element="impl:MultipleParametersAddItemRequest"/&gt;
  &lt;/wsdl:message&gt;
  &lt;wsdl:message name="MultipleParametersAddItemResponseMessage"&gt;
    &lt;wsdl:part name="output" element="impl:MultipleParametersAddItemResponse"/&gt;
  &lt;/wsdl:message&gt;


  &lt;!-- Port type (operations) --&gt;

  &lt;wsdl:portType name="Axis2UserGuidePortType"&gt;

    &lt;wsdl:operation name="DoInOnly" parameterOrder="input"&gt;
      &lt;wsdl:input name="DoInOnlyRequestMessage"
                  message="impl:DoInOnlyRequestMessage"/&gt;
    &lt;/wsdl:operation&gt;

    &lt;wsdl:operation name="TwoWayOneParameterEcho" parameterOrder="input"&gt;
      &lt;wsdl:input name="TwoWayOneParameterEchoRequestMessage"
                  message="impl:TwoWayOneParameterEchoRequestMessage"/&gt;
      &lt;wsdl:output name="TwoWayOneParameterEchoResponseMessage"
                  message="impl:TwoWayOneParameterEchoResponseMessage"/&gt;
    &lt;/wsdl:operation&gt;

    &lt;wsdl:operation name="NoParameters" parameterOrder="input"&gt;
      &lt;wsdl:input name="NoParametersRequestMessage"
                  message="impl:NoParametersRequestMessage"/&gt;
      &lt;wsdl:output name="NoParametersResponseMessage"
                   message="impl:NoParametersResponseMessage"/&gt;
    &lt;/wsdl:operation&gt;

    &lt;wsdl:operation name="MultipleParametersAddItem" parameterOrder="input"&gt;
      &lt;wsdl:input name="MultipleParametersAddItemRequestMessage"
                  message="impl:MultipleParametersAddItemRequestMessage"/&gt;
      &lt;wsdl:output name="MultipleParametersAddItemResponseMessage"
                  message="impl:MultipleParametersAddItemResponseMessage"/&gt;
    &lt;/wsdl:operation&gt;

  &lt;/wsdl:portType&gt;


  &lt;!-- BINDING (bind operations) --&gt;
  &lt;wsdl:binding
     name="Axis2UserGuideSoapBinding"
     type="impl:Axis2UserGuidePortType"&gt;
    &lt;wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/&gt;

    &lt;wsdl:operation name="DoInOnly"&gt;
      &lt;wsdlsoap:operation soapAction="DoInOnly"/&gt;
      &lt;wsdl:input&gt;
        &lt;wsdlsoap:body use="literal"/&gt;
      &lt;/wsdl:input&gt;
    &lt;/wsdl:operation&gt;

    &lt;wsdl:operation name="TwoWayOneParameterEcho"&gt;
      &lt;wsdlsoap:operation soapAction="TwoWayOneParameterEcho"/&gt;
      &lt;wsdl:input&gt;
        &lt;wsdlsoap:body use="literal"/&gt;
      &lt;/wsdl:input&gt;
      &lt;wsdl:output&gt;
        &lt;wsdlsoap:body use="literal"/&gt;
      &lt;/wsdl:output&gt;
    &lt;/wsdl:operation&gt;

    &lt;wsdl:operation name="NoParameters"&gt;
      &lt;wsdlsoap:operation soapAction="NoParameters"/&gt;
      &lt;wsdl:input&gt;
        &lt;wsdlsoap:body use="literal"/&gt;
      &lt;/wsdl:input&gt;
      &lt;wsdl:output&gt;
        &lt;wsdlsoap:body use="literal"/&gt;
      &lt;/wsdl:output&gt;
    &lt;/wsdl:operation&gt;

    &lt;wsdl:operation name="MultipleParametersAddItem"&gt;
      &lt;wsdlsoap:operation soapAction="MultipleParametersAddItem"/&gt;
      &lt;wsdl:input&gt;
        &lt;wsdlsoap:body use="literal"/&gt;
      &lt;/wsdl:input&gt;
      &lt;wsdl:output&gt;
        &lt;wsdlsoap:body use="literal"/&gt;
      &lt;/wsdl:output&gt;
    &lt;/wsdl:operation&gt;
  &lt;/wsdl:binding&gt;


  &lt;!-- SERVICE --&gt;

  &lt;wsdl:service name="Axis2UserGuideService"&gt;
    &lt;wsdl:port binding="impl:Axis2UserGuideSoapBinding"
               name="Axis2UserGuide"&gt;
      &lt;wsdlsoap:address location="http://localhost:8080/axis2/services/Axis2UserGuide"/&gt;
    &lt;/wsdl:port&gt;
  &lt;/wsdl:service&gt;
&lt;/wsdl:definitions&gt;</pre>

<p>Note that the document defines four operations, DoInOnly, NoParameters,
TwoWayOneParameterEcho, and MultipleParametersAddItem. Each client will
include methods for calling each of these operations.</p>

<p>(You can get more information on WSDL at <a
href="http://www.w3.org/2002/ws/desc/">http://www.w3.org/2002/ws/desc/</a>
.)</p>
<a name="jibx"></a>

<h2>JiBX</h2>

<p>JiBX is not part of the Apache project, so in order to use it to generate
your clients, you will need to do some setting up to start with. To generate
your client, execute the following steps:</p>

<p><b>The short story</b>:</p>
<ol>
  <li>Download the latest JiBX package (tested with JiBX v1.1) from <a
    href="http://sourceforge.net/projects/jibx/">http://sourceforge.net/projects/jibx/</a>
    . Extract the zip file, and copy the JARs in the lib directory to the
    AXIS2_HOME/lib directory. (Delete the stax-api.jar file; it's superseded
    by the version that comes with Axis2.)</li>
  <li>Download <a
    href="http://sourceforge.net/project/showfiles.php?group_id=69358&amp;package_id=122897">xsd2jibx
    version beta2a</a> from SourceForge. Create a directory called xsd2jibx
    in your working directory and extract the files into it. This utility
    does not work with the latest release (v1.1) of JiBX, so download <a
    href="http://sourceforge.net/project/showfiles.php?group_id=69358&amp;package_id=68290">jibx-1.0RC1</a>
    from SourceForge. Extract the files from this archive and copy the *.jar
    files in the lib directory into the xsd2jibx/lib directory.</li>
  <li>Create a schema based on the data structures of your WSDL file and save
    it in your working directory.</li>
  <li>Make sure that only the xsd2jibx jar files are in the classpath and
    execute the following command to create the basic binding file: java -jar
    xsd2jibx\lib\xsd2jibx.jar Axis2UserGuide.xsd</li>
  <li>Copy the org directory to the src directory to place the generated
    classes into the project so that the compiler will see them.</li>
  <li>Remove the xsd2jibx-related *.jar files from your CLASSPATH and add the
    Axis2 .jar files back into it. Execute the following command to generate
    the stubs:
    <pre>%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d jibx -Ebindingfile org\apache\axis2\axis2userguide\binding.xml -s</pre>
  </li>
  <li>Create the client file in the org/apache/axis2/axis2userguide
  directory.</li>
  <li>Copy the org directory and all its contents to the src directory.</li>
  <li>Compile the first set of classes by typing:<code>ant
  jar.client</code></li>
  <li>Go to the build/classes directory and run the JiBX compiler:
    <pre>java -jar C:\apps\axis2\lib\jibx-bind.jar 
..\..\org\apache\axis2\axis2userguide\binding.xml</pre>
  </li>
  <li>Run Ant again to package the new auto-generated JiBX classes into the
    client jar by typing: <code>ant jar.client</code></li>
  <li>Add the build/lib/Axis2UserGuideService-test-client.jar file to the
    CLASSPATH and run the client by typing:
    <pre>java org.apache.axis2.axis2userguide.Client</pre>
  </li>
</ol>

<p><b>The long story:</b></p>

<p>To use JiBX to generate your client, you first need to use it in two
different functions. You have to generate a binding file that maps objects to
the XML elements, and then use JiBX to generate the stubs that your client
will use. To generate a binding file, you'll need the xsd2jibx utility, which
creates a binding file from an XML Schema document. Once you have the binding
file, you can run JiBX to create the actual object. In order to do all that
you'll need to have the appropriate versions of the JiBX software.</p>

<p>Download the latest JiBX package (tested with JiBX v1.1) from <a
href="http://sourceforge.net/projects/jibx/">http://sourceforge.net/projects/jibx/</a>.
Extract the zip file, and copy the JARs in the lib directory to the
AXIS2_HOME/lib directory. (Delete the stax-api.jar file; it's superseded by
the version that comes with Axis2.) These files pertain to the main JiBX
application.</p>

<p>Download <a
href="http://sourceforge.net/project/showfiles.php?group_id=69358&amp;package_id=122897">xsd2jibx
version beta2a</a> from Sourceforge. Create a directory called xsd2jibx in
your working directory and extract the files into it. Unfortunately, this
utility does not work with the latest release of JiBX, so you will need to
download <a
href="http://sourceforge.net/project/showfiles.php?group_id=69358&amp;package_id=68290 ">jibx-1.0RC1</a>
from Sourceforge. Extract the files from this archive and place the *.jar
files in the lib directory into the xsd2jibx/lib directory. This way, you can
use them exclusively with the xsd2jibx utility.</p>

<p>You'll need an XML schema from which to generate the binding file, which
links XML elements to the Java classes. As defined in the sample WSDL file,
its content should be as shown in Code Listing 2.</p>

<p><b>Code Listing 2: XML Schema</b></p>
<pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;xsd:schema
   elementFormDefault="qualified"
   targetNamespace="http://apache.org/axis2/Axis2UserGuide"
   xmlns="http://www.w3.org/2001/XMLSchema"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"&gt;
  
  &lt;!-- ELEMENTS --&gt;
  &lt;xsd:element name="DoInOnlyRequest"&gt;
    &lt;xsd:complexType&gt;
      &lt;xsd:sequence&gt;
        &lt;xsd:element name="messageString" type="xsd:string"/&gt;
      &lt;/xsd:sequence&gt;
    &lt;/xsd:complexType&gt;
  &lt;/xsd:element&gt;
  
  &lt;xsd:element name="TwoWayOneParameterEchoRequest"&gt;
    &lt;xsd:complexType&gt;
      &lt;xsd:sequence&gt;
        &lt;xsd:element name="echoString" type="xsd:string"/&gt;
      &lt;/xsd:sequence&gt;
    &lt;/xsd:complexType&gt;
  &lt;/xsd:element&gt;
  &lt;xsd:element name="TwoWayOneParameterEchoResponse"&gt;
    &lt;xsd:complexType&gt;
      &lt;xsd:sequence&gt;
        &lt;xsd:element name="echoString" type="xsd:string"/&gt;
      &lt;/xsd:sequence&gt;
    &lt;/xsd:complexType&gt;
  &lt;/xsd:element&gt;
  
  &lt;xsd:element name="NoParametersRequest"&gt;
    &lt;xsd:complexType/&gt;
  &lt;/xsd:element&gt;
  &lt;xsd:element name="NoParametersResponse"&gt;
    &lt;xsd:complexType/&gt;
  &lt;/xsd:element&gt;
  
  &lt;xsd:element name="MultipleParametersAddItemRequest"&gt;
    &lt;xsd:complexType&gt;
      &lt;xsd:sequence&gt;
        &lt;xsd:element name="itemId" type="xsd:int"/&gt;
        &lt;xsd:element name="itemName" type="xsd:string"/&gt;
        &lt;xsd:element name="price" type="xsd:float"/&gt;
        &lt;xsd:element name="description" type="xsd:string"/&gt;
      &lt;/xsd:sequence&gt;
    &lt;/xsd:complexType&gt;
  &lt;/xsd:element&gt;

  &lt;xsd:element name="MultipleParametersAddItemResponse"&gt;
    &lt;xsd:complexType&gt;
      &lt;xsd:sequence&gt;
        &lt;xsd:element name="itemId" type="xsd:int"/&gt;
        &lt;xsd:element name="successfulAdd" type="xsd:boolean"/&gt;
      &lt;/xsd:sequence&gt;
    &lt;/xsd:complexType&gt;
  &lt;/xsd:element&gt;

&lt;/xsd:schema&gt;</pre>

<p>Save the above XML schema file as Axis2UserGuide.xsd.</p>

<p>In order to map this schema into a JiBX binding file, you'll need to use
the xsd2jibx utility. Clear your CLASSPATH and add only the .jar files in the
xsd2jibx/lib directory. Execute the following command to create the basic
binding file:</p>
<pre>java -jar xsd2jibx\lib\xsd2jibx.jar Axis2UserGuide.xsd</pre>

<p>This operation creates the basic class files, as well as the mapping file,
called binding.xml. You'll use this file to do the actual WSDL-to-Java
conversion.</p>

<p>Remove the xsd2jibx .jar files from your CLASSPATH and add the Axis2 .jar
files back into it. Execute the command in Code Listing 3 to generate the
stubs.</p>

<p><b>Code Listing 3: Generating the stubs</b></p>
<pre>%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d jibx -Ebindingfile org\apache\axis2\axis2userguide\binding.xml -s</pre>

<p>Create the client file, Client.java, in the
org/apache/axis2/axis2userguide directory. Add the following code in Code
Listing 4.</p>

<p><b>Code Listing 4: Creating Client.java</b></p>
<pre>package org.apache.axis2.axis2userguide;

public class Client{
    public static void main(java.lang.String args[]){
        try{
            Axis2UserGuideServiceStub stub =
                new Axis2UserGuideServiceStub
              ("http://localhost:8080/axis2/services/Axis2UserGuideService");

            doInOnly(stub);
            twoWayOneParameterEcho(stub);
            noParameters(stub);
            multipleParameters(stub);
        } catch(Exception e){
            e.printStackTrace();
            System.out.println("\n\n\n");
        }
    }

    public static void doInOnly(Axis2UserGuideServiceStub stub){
        try{
            DoInOnlyRequest req = 
                new DoInOnlyRequest();

            req.setMessageString("fire and forget it!");

            stub.DoInOnly(req);
        } catch(Exception e){
            e.printStackTrace();
            System.out.println("\n\n\n");
        }
    }

    public static void twoWayOneParameterEcho(Axis2UserGuideServiceStub stub){
        try{
            TwoWayOneParameterEchoRequest req = 
                new TwoWayOneParameterEchoRequest();

            req.setEchoString("echo! ... echo!");
        System.out.println(stub.TwoWayOneParameterEcho(req).getEchoString());
        } catch(Exception e){
            e.printStackTrace();
            System.out.println("\n\n\n");
        }
    }

    public static void noParameters(Axis2UserGuideServiceStub stub){
        try{
            NoParametersRequest req =
                new NoParametersRequest();

            System.out.println(stub.NoParameters(req));
        } catch(Exception e){
            e.printStackTrace();
            System.out.println("\n\n\n");
        }
    }

    public static void multipleParameters(Axis2UserGuideServiceStub stub){
        try{
            MultipleParametersAddItemRequest req =
                new MultipleParametersAddItemRequest();

            req.setPrice((float)1.99);
            req.setItemId((int)23872983);
            req.setDescription("Must have for cooking");
            req.setItemName("flour");

            MultipleParametersAddItemResponse res =
                stub.MultipleParametersAddItem(req);

            System.out.println(res.getItemId());
            System.out.println(res.getSuccessfulAdd());
        } catch(Exception e){
            e.printStackTrace();
            System.out.println("\n\n\n");
        }
    }
}</pre>

<p>Now it's time to compile the client. For the generated files to be found,
they need to be in the source directory, so copy the org file to the src
directory.</p>

<p>Compile the first set of classes by typing: <code>ant jar.client</code></p>

<p>This action compiles most of the available classes, but not everything.
Fortunately, it does compile the classes needed by the JiBX compiler, so you
can now generate the actual JiBX resources. Change to the build/classes
directory and run the JiBX compiler:</p>
<pre>java -jar C:\apps\axis2\lib\jibx-bind.jar ..\..\org\apache\axis2\axis2userguide\binding.xml</pre>

<p>Now that you have the new files in place, re-run the Ant task to generate
the client: <code>ant jar.client</code></p>

<p>This action adds all the appropriate files to the
build/lib/Axis2UserGuideService-test-client.jar file, so add that .jar file
to your CLASSPATH and run the client by typing: java
org.apache.axis2.axis2userguide.Client</p>
</body>
</html>