<?xml version="1.0" encoding="UTF-8"?>

<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements. See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership. The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License. You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied. See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta name="generator" content=
"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
<meta http-equiv="content-type" content="" />
<title>Generating a Web Service Client using Axis2 and JiBX</title>
</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" id="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>