Return-Path: Delivered-To: apmail-ws-axis-dev-archive@www.apache.org Received: (qmail 52675 invoked from network); 25 Aug 2008 18:13:33 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 25 Aug 2008 18:13:33 -0000 Received: (qmail 58912 invoked by uid 500); 25 Aug 2008 18:13:30 -0000 Delivered-To: apmail-ws-axis-dev-archive@ws.apache.org Received: (qmail 58773 invoked by uid 500); 25 Aug 2008 18:13:30 -0000 Mailing-List: contact axis-cvs-help@ws.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list axis-cvs@ws.apache.org Received: (qmail 58764 invoked by uid 500); 25 Aug 2008 18:13:30 -0000 Delivered-To: apmail-ws-axis2-cvs@ws.apache.org Received: (qmail 58761 invoked by uid 99); 25 Aug 2008 18:13:30 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 25 Aug 2008 11:13:30 -0700 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 25 Aug 2008 18:12:28 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id DA0C22388A91; Mon, 25 Aug 2008 11:10:13 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r688807 [15/17] - in /webservices/axis2/site/1_4_1: ./ adb/ adb/images/ images/ images/archi-guide/ images/userguide/ jibx/ src/ Date: Mon, 25 Aug 2008 18:10:09 -0000 To: axis2-cvs@ws.apache.org From: nandana@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20080825181013.DA0C22388A91@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: webservices/axis2/site/1_4_1/userguide-codelisting7.html URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4_1/userguide-codelisting7.html?rev=688807&view=auto ============================================================================== --- webservices/axis2/site/1_4_1/userguide-codelisting7.html (added) +++ webservices/axis2/site/1_4_1/userguide-codelisting7.html Mon Aug 25 11:10:04 2008 @@ -0,0 +1,414 @@ + + + + + + + + + + + + + + + Apache Axis2 - + + + + + + + +
+ +
+
+
+ Code Listing 6: Client.java

Code Listing 7- Client.java

+package org.apache.axis2.axis2userguide;
+
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.DoInOnlyRequest;
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.TwoWayOneParameterEchoRequest;
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.NoParametersRequest;
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.MultipleParametersAddItemRequest;
+
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.TwoWayOneParameterEchoResponse;
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.NoParametersResponse;
+import org.apache.axis2.axis2userguide.Axis2UserGuideServiceStub.MultipleParametersAddItemResponse;
+
+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");
+        }
+    }
+
+    /* do in only */
+    public static void doInOnly(Axis2UserGuideServiceStub stub){
+        try{
+            DoInOnlyRequest req = new DoInOnlyRequest();
+
+            req.setMessageString("An in only request");
+
+            stub.DoInOnly(req);
+            System.out.println("done");
+        } catch(Exception e){
+            e.printStackTrace();
+            System.out.println("\n\n\n");
+        }
+    }
+
+    /* two way call/receive */
+    public static void twoWayOneParameterEcho(Axis2UserGuideServiceStub stub){
+        try{
+            TwoWayOneParameterEchoRequest req = new TwoWayOneParameterEchoRequest();
+
+            req.setEchoString("echo! ... echo!");
+
+            TwoWayOneParameterEchoResponse res =
+                stub.TwoWayOneParameterEcho(req);
+
+            System.out.println(res.getEchoString());
+        } catch(Exception e){
+            e.printStackTrace();
+            System.out.println("\n\n\n");
+        }
+    }
+
+    /* No parameters */
+    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");
+        }
+    }
+
+    /* multiple parameters */
+    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.getSuccessfulAdd());
+            System.out.println(res.getItemId());
+        } catch(Exception e){
+            e.printStackTrace();
+            System.out.println("\n\n\n");
+        }
+    }
+}
+
+
+
+
+
+
+ + + Added: webservices/axis2/site/1_4_1/userguide-creatingclients-jibx.html URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4_1/userguide-creatingclients-jibx.html?rev=688807&view=auto ============================================================================== --- webservices/axis2/site/1_4_1/userguide-creatingclients-jibx.html (added) +++ webservices/axis2/site/1_4_1/userguide-creatingclients-jibx.html Mon Aug 25 11:10:04 2008 @@ -0,0 +1,774 @@ + + + + + + + + + + + + + + + Apache Axis2 - + + + + + + + +
+ +
+
+
+ Generating a Web Service Client using Axis2 and JiBX

Generating a Web Service Client using Axis2 and +JiBX

This document explains how to generate a Web service client +using Axis2 and JiBX data binding. The service has the following +WSDL:

+

Code Listing 1: The WSDL file

+
+<?xml version="1.0" encoding="UTF-8"?>
+<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">
+
+  <wsdl:types>
+    <schema
+       elementFormDefault="qualified"
+       targetNamespace="http://apache.org/axis2/Axis2UserGuide"
+       xmlns="http://www.w3.org/2001/XMLSchema">
+      
+      <!-- ELEMENTS -->
+      
+      <element name="DoInOnlyRequest">
+        <complexType>
+          <sequence>
+            <element name="messageString" type="xsd:string"/>
+          </sequence>
+        </complexType>
+      </element>
+      
+      <element name="TwoWayOneParameterEchoRequest">
+        <complexType>
+          <sequence>
+            <element name="echoString" type="xsd:string"/>
+          </sequence>
+        </complexType>
+      </element>
+      <element name="TwoWayOneParameterEchoResponse">
+        <complexType>
+          <sequence>
+            <element name="echoString" type="xsd:string"/>
+          </sequence>
+        </complexType>
+      </element>
+      
+      <element name="NoParametersRequest">
+        <complexType/>
+      </element>
+      <element name="NoParametersResponse">
+        <complexType/>
+      </element>
+      
+      <element name="MultipleParametersAddItemRequest">
+        <complexType>
+          <sequence>
+            <element name="itemId" type="xsd:int"/>
+            <element name="itemName" type="xsd:string"/>
+            <element name="price" type="xsd:float"/>
+            <element name="description" type="xsd:string"/>
+          </sequence>
+        </complexType>
+      </element>
+
+      <element name="MultipleParametersAddItemResponse">
+        <complexType>
+          <sequence>
+          <element name="itemId" type="xsd:int"/>
+          <element name="successfulAdd" type="xsd:boolean"/>
+          </sequence>
+        </complexType>
+      </element>
+
+    </schema>
+  </wsdl:types>
+
+  
+  <!-- MESSAGES -->
+
+  <wsdl:message name="DoInOnlyRequestMessage">
+    <wsdl:part name="input" element="impl:DoInOnlyRequest"/>
+  </wsdl:message>
+
+  <wsdl:message name="TwoWayOneParameterEchoRequestMessage">
+    <wsdl:part name="input" element="impl:TwoWayOneParameterEchoRequest"/>
+  </wsdl:message>
+  <wsdl:message name="TwoWayOneParameterEchoResponseMessage">
+    <wsdl:part name="output" element="impl:TwoWayOneParameterEchoResponse"/>
+  </wsdl:message>
+
+  <wsdl:message name="NoParametersRequestMessage">
+    <wsdl:part name="input" element="impl:NoParametersRequest"/>
+  </wsdl:message>
+  <wsdl:message name="NoParametersResponseMessage">
+    <wsdl:part name="output" element="impl:NoParametersResponse"/>
+  </wsdl:message>
+
+  <wsdl:message name="MultipleParametersAddItemRequestMessage">
+    <wsdl:part name="input" element="impl:MultipleParametersAddItemRequest"/>
+  </wsdl:message>
+  <wsdl:message name="MultipleParametersAddItemResponseMessage">
+    <wsdl:part name="output" element="impl:MultipleParametersAddItemResponse"/>
+  </wsdl:message>
+
+
+  <!-- Port type (operations) -->
+
+  <wsdl:portType name="Axis2UserGuidePortType">
+
+    <wsdl:operation name="DoInOnly" parameterOrder="input">
+      <wsdl:input name="DoInOnlyRequestMessage"
+                  message="impl:DoInOnlyRequestMessage"/>
+    </wsdl:operation>
+
+    <wsdl:operation name="TwoWayOneParameterEcho" parameterOrder="input">
+      <wsdl:input name="TwoWayOneParameterEchoRequestMessage"
+                  message="impl:TwoWayOneParameterEchoRequestMessage"/>
+      <wsdl:output name="TwoWayOneParameterEchoResponseMessage"
+                  message="impl:TwoWayOneParameterEchoResponseMessage"/>
+    </wsdl:operation>
+
+    <wsdl:operation name="NoParameters" parameterOrder="input">
+      <wsdl:input name="NoParametersRequestMessage"
+                  message="impl:NoParametersRequestMessage"/>
+      <wsdl:output name="NoParametersResponseMessage"
+                   message="impl:NoParametersResponseMessage"/>
+    </wsdl:operation>
+
+    <wsdl:operation name="MultipleParametersAddItem" parameterOrder="input">
+      <wsdl:input name="MultipleParametersAddItemRequestMessage"
+                  message="impl:MultipleParametersAddItemRequestMessage"/>
+      <wsdl:output name="MultipleParametersAddItemResponseMessage"
+                  message="impl:MultipleParametersAddItemResponseMessage"/>
+    </wsdl:operation>
+
+  </wsdl:portType>
+
+
+  <!-- BINDING (bind operations) -->
+  <wsdl:binding
+     name="Axis2UserGuideSoapBinding"
+     type="impl:Axis2UserGuidePortType">
+    <wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
+
+    <wsdl:operation name="DoInOnly">
+      <wsdlsoap:operation soapAction="DoInOnly"/>
+      <wsdl:input>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:input>
+    </wsdl:operation>
+
+    <wsdl:operation name="TwoWayOneParameterEcho">
+      <wsdlsoap:operation soapAction="TwoWayOneParameterEcho"/>
+      <wsdl:input>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:input>
+      <wsdl:output>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:output>
+    </wsdl:operation>
+
+    <wsdl:operation name="NoParameters">
+      <wsdlsoap:operation soapAction="NoParameters"/>
+      <wsdl:input>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:input>
+      <wsdl:output>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:output>
+    </wsdl:operation>
+
+    <wsdl:operation name="MultipleParametersAddItem">
+      <wsdlsoap:operation soapAction="MultipleParametersAddItem"/>
+      <wsdl:input>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:input>
+      <wsdl:output>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:output>
+    </wsdl:operation>
+  </wsdl:binding>
+
+
+  <!-- SERVICE -->
+
+  <wsdl:service name="Axis2UserGuideService">
+    <wsdl:port binding="impl:Axis2UserGuideSoapBinding"
+               name="Axis2UserGuide">
+      <wsdlsoap:address location="http://localhost:8080/axis2/services/Axis2UserGuide"/>
+    </wsdl:port>
+  </wsdl:service>
+</wsdl:definitions>
+

Note that the document defines four operations, DoInOnly, +NoParameters, TwoWayOneParameterEcho, and +MultipleParametersAddItem. Each client will include methods for +calling each of these operations.

+

(You can get more information on WSDL at http://www.w3.org/2002/ws/desc/ +.)

+

JiBX

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:

+

The short story:

+
  1. Download the latest JiBX package (tested with JiBX v1.1) from +http://sourceforge.net/projects/jibx/ +. 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.)
    2. +
  2. Download +xsd2jibx version beta2a 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 +jibx-1.0RC1 from SourceForge. Extract the files from this +archive and copy the *.jar files in the lib directory into the +xsd2jibx/lib directory.
    3. +
  3. Create a schema based on the data structures of your WSDL file +and save it in your working directory.
    4. +
  4. 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
    5. +
  5. Copy the org directory to the src directory to place the +generated classes into the project so that the compiler will see +them.
    6. +
  6. 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: +
    +%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d jibx -Ebindingfile org\apache\axis2\axis2userguide\binding.xml -s
+
    7. +
  7. Create the client file in the org/apache/axis2/axis2userguide +directory.
    8. +
  8. Copy the org directory and all its contents to the src +directory.
    9. +
  9. Compile the first set of classes by typing:ant +jar.client
    10. +
  10. Go to the build/classes directory and run the JiBX compiler: +
    +java -jar C:\apps\axis2\lib\jibx-bind.jar 
+..\..\org\apache\axis2\axis2userguide\binding.xml
+
    11. +
  11. Run Ant again to package the new auto-generated JiBX classes +into the client jar by typing: ant jar.client
    12. +
  12. Add the build/lib/Axis2UserGuideService-test-client.jar file to +the CLASSPATH and run the client by typing: +
    +java org.apache.axis2.axis2userguide.Client
+
    13. +
+

The long story:

+

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.

+

Download the latest JiBX package (tested with JiBX v1.1) from +http://sourceforge.net/projects/jibx/. +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.

+

Download +xsd2jibx version beta2a 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 +jibx-1.0RC1 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.

+

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.

+

Code Listing 2: XML Schema

+
+<?xml version="1.0" encoding="UTF-8"?>
+<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">
+  
+  <!-- ELEMENTS -->
+  <xsd:element name="DoInOnlyRequest">
+    <xsd:complexType>
+      <xsd:sequence>
+        <xsd:element name="messageString" type="xsd:string"/>
+      </xsd:sequence>
+    </xsd:complexType>
+  </xsd:element>
+  
+  <xsd:element name="TwoWayOneParameterEchoRequest">
+    <xsd:complexType>
+      <xsd:sequence>
+        <xsd:element name="echoString" type="xsd:string"/>
+      </xsd:sequence>
+    </xsd:complexType>
+  </xsd:element>
+  <xsd:element name="TwoWayOneParameterEchoResponse">
+    <xsd:complexType>
+      <xsd:sequence>
+        <xsd:element name="echoString" type="xsd:string"/>
+      </xsd:sequence>
+    </xsd:complexType>
+  </xsd:element>
+  
+  <xsd:element name="NoParametersRequest">
+    <xsd:complexType/>
+  </xsd:element>
+  <xsd:element name="NoParametersResponse">
+    <xsd:complexType/>
+  </xsd:element>
+  
+  <xsd:element name="MultipleParametersAddItemRequest">
+    <xsd:complexType>
+      <xsd:sequence>
+        <xsd:element name="itemId" type="xsd:int"/>
+        <xsd:element name="itemName" type="xsd:string"/>
+        <xsd:element name="price" type="xsd:float"/>
+        <xsd:element name="description" type="xsd:string"/>
+      </xsd:sequence>
+    </xsd:complexType>
+  </xsd:element>
+
+  <xsd:element name="MultipleParametersAddItemResponse">
+    <xsd:complexType>
+      <xsd:sequence>
+        <xsd:element name="itemId" type="xsd:int"/>
+        <xsd:element name="successfulAdd" type="xsd:boolean"/>
+      </xsd:sequence>
+    </xsd:complexType>
+  </xsd:element>
+
+</xsd:schema>
+

Save the above XML schema file as Axis2UserGuide.xsd.

+

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:

+
+java -jar xsd2jibx\lib\xsd2jibx.jar Axis2UserGuide.xsd
+

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.

+

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.

+

Code Listing 3: Generating the stubs

+
+%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d jibx -Ebindingfile org\apache\axis2\axis2userguide\binding.xml -s
+

Create the client file, Client.java, in the +org/apache/axis2/axis2userguide directory. Add the following code +in Code Listing 4.

+

Code Listing 4: Creating Client.java

+
+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");
+        }
+    }
+}
+

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.

+

Compile the first set of classes by typing: ant +jar.client

+

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:

+
+java -jar C:\apps\axis2\lib\jibx-bind.jar ..\..\org\apache\axis2\axis2userguide\binding.xml
+

Now that you have the new files in place, re-run the Ant task to +generate the client: ant jar.client

+

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

+ +
+
+
+
+
+ + + Added: webservices/axis2/site/1_4_1/userguide-creatingclients-xmlbeans.html URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4_1/userguide-creatingclients-xmlbeans.html?rev=688807&view=auto ============================================================================== --- webservices/axis2/site/1_4_1/userguide-creatingclients-xmlbeans.html (added) +++ webservices/axis2/site/1_4_1/userguide-creatingclients-xmlbeans.html Mon Aug 25 11:10:04 2008 @@ -0,0 +1,698 @@ + + + + + + + + + + + + + + + Apache Axis2 - + + + + + + + +
+ +
+
+
+ Generating a Web Service Client using Axis2 and +XmlBeans

Generating a Web Service Client using Apache +Axis2 and XMLBeans

This document explains how to generate a Web service client +using Apache Axis2 and XMLBeans data binding. The service has the +following WSDL:

+

Code Listing 1: The WSDL file

+
+<?xml version="1.0" encoding="UTF-8"?>
+<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">
+
+  <wsdl:types>
+    <schema
+       elementFormDefault="qualified"
+       targetNamespace="http://apache.org/axis2/Axis2UserGuide"
+       xmlns="http://www.w3.org/2001/XMLSchema">
+      
+      <!-- ELEMENTS -->
+      
+      <element name="DoInOnlyRequest">
+        <complexType>
+          <sequence>
+            <element name="messageString" type="xsd:string"/>
+          </sequence>
+        </complexType>
+      </element>
+      
+      <element name="TwoWayOneParameterEchoRequest">
+        <complexType>
+          <sequence>
+            <element name="echoString" type="xsd:string"/>
+          </sequence>
+        </complexType>
+      </element>
+      <element name="TwoWayOneParameterEchoResponse">
+        <complexType>
+          <sequence>
+            <element name="echoString" type="xsd:string"/>
+          </sequence>
+        </complexType>
+      </element>
+      
+      <element name="NoParametersRequest">
+        <complexType/>
+      </element>
+      <element name="NoParametersResponse">
+        <complexType/>
+      </element>
+      
+      <element name="MultipleParametersAddItemRequest">
+        <complexType>
+          <sequence>
+            <element name="itemId" type="xsd:int"/>
+            <element name="itemName" type="xsd:string"/>
+            <element name="price" type="xsd:float"/>
+            <element name="description" type="xsd:string"/>
+          </sequence>
+        </complexType>
+      </element>
+
+      <element name="MultipleParametersAddItemResponse">
+        <complexType>
+          <sequence>
+          <element name="itemId" type="xsd:int"/>
+          <element name="successfulAdd" type="xsd:boolean"/>
+          </sequence>
+        </complexType>
+      </element>
+
+    </schema>
+  </wsdl:types>
+
+  
+  <!-- MESSAGES -->
+
+  <wsdl:message name="DoInOnlyRequestMessage">
+    <wsdl:part name="input" element="impl:DoInOnlyRequest"/>
+  </wsdl:message>
+
+  <wsdl:message name="TwoWayOneParameterEchoRequestMessage">
+    <wsdl:part name="input" element="impl:TwoWayOneParameterEchoRequest"/>
+  </wsdl:message>
+  <wsdl:message name="TwoWayOneParameterEchoResponseMessage">
+    <wsdl:part name="output" element="impl:TwoWayOneParameterEchoResponse"/>
+  </wsdl:message>
+
+  <wsdl:message name="NoParametersRequestMessage">
+    <wsdl:part name="input" element="impl:NoParametersRequest"/>
+  </wsdl:message>
+  <wsdl:message name="NoParametersResponseMessage">
+    <wsdl:part name="output" element="impl:NoParametersResponse"/>
+  </wsdl:message>
+
+  <wsdl:message name="MultipleParametersAddItemRequestMessage">
+    <wsdl:part name="input" element="impl:MultipleParametersAddItemRequest"/>
+  </wsdl:message>
+  <wsdl:message name="MultipleParametersAddItemResponseMessage">
+    <wsdl:part name="output" element="impl:MultipleParametersAddItemResponse"/>
+  </wsdl:message>
+
+
+  <!-- Port type (operations) -->
+
+  <wsdl:portType name="Axis2UserGuidePortType">
+
+    <wsdl:operation name="DoInOnly" parameterOrder="input">
+      <wsdl:input name="DoInOnlyRequestMessage"
+                  message="impl:DoInOnlyRequestMessage"/>
+    </wsdl:operation>
+
+    <wsdl:operation name="TwoWayOneParameterEcho" parameterOrder="input">
+      <wsdl:input name="TwoWayOneParameterEchoRequestMessage"
+                  message="impl:TwoWayOneParameterEchoRequestMessage"/>
+      <wsdl:output name="TwoWayOneParameterEchoResponseMessage"
+                  message="impl:TwoWayOneParameterEchoResponseMessage"/>
+    </wsdl:operation>
+
+    <wsdl:operation name="NoParameters" parameterOrder="input">
+      <wsdl:input name="NoParametersRequestMessage"
+                  message="impl:NoParametersRequestMessage"/>
+      <wsdl:output name="NoParametersResponseMessage"
+                   message="impl:NoParametersResponseMessage"/>
+    </wsdl:operation>
+
+    <wsdl:operation name="MultipleParametersAddItem" parameterOrder="input">
+      <wsdl:input name="MultipleParametersAddItemRequestMessage"
+                  message="impl:MultipleParametersAddItemRequestMessage"/>
+      <wsdl:output name="MultipleParametersAddItemResponseMessage"
+                  message="impl:MultipleParametersAddItemResponseMessage"/>
+    </wsdl:operation>
+
+  </wsdl:portType>
+
+
+  <!-- BINDING (bind operations) -->
+  <wsdl:binding
+     name="Axis2UserGuideSoapBinding"
+     type="impl:Axis2UserGuidePortType">
+    <wsdlsoap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
+
+    <wsdl:operation name="DoInOnly">
+      <wsdlsoap:operation soapAction="DoInOnly"/>
+      <wsdl:input>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:input>
+    </wsdl:operation>
+
+    <wsdl:operation name="TwoWayOneParameterEcho">
+      <wsdlsoap:operation soapAction="TwoWayOneParameterEcho"/>
+      <wsdl:input>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:input>
+      <wsdl:output>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:output>
+    </wsdl:operation>
+
+    <wsdl:operation name="NoParameters">
+      <wsdlsoap:operation soapAction="NoParameters"/>
+      <wsdl:input>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:input>
+      <wsdl:output>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:output>
+    </wsdl:operation>
+
+    <wsdl:operation name="MultipleParametersAddItem">
+      <wsdlsoap:operation soapAction="MultipleParametersAddItem"/>
+      <wsdl:input>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:input>
+      <wsdl:output>
+        <wsdlsoap:body use="literal"/>
+      </wsdl:output>
+    </wsdl:operation>
+  </wsdl:binding>
+
+
+  <!-- SERVICE -->
+
+  <wsdl:service name="Axis2UserGuideService">
+    <wsdl:port binding="impl:Axis2UserGuideSoapBinding"
+               name="Axis2UserGuide">
+      <wsdlsoap:address location="http://localhost:8080/axis2/services/Axis2UserGuide"/>
+    </wsdl:port>
+  </wsdl:service>
+</wsdl:definitions>
+

Note that the document defines four operations, DoInOnly, +NoParameters, TwoWayOneParameterEcho, and +MultipleParametersAddItem. Each client will include methods for +calling each of these operations.

+

(For more information on WSDL, refer to: http://www.w3.org/2002/ws/desc/ +.)

+

The short story:

+
  1. Download +and unpack the Apache Axis2 Standard Distribution, if you have not +done so already.
    2. +
  2. Create the client classes with the following command:
    +
    +%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d xmlbeans -s
+
    3. +
  3. Create the client (for example, Client.java) and save it in the +org/apache/axis2/axis2userguide directory.
    4. +
  4. Build the client by typing: ant jar.client.
    5. +
  5. Make sure all the .jar files in the Axis2 lib directory are in +the CLASSPATH.
    6. +
  6. Assuming you have a corresponding service, run the client by +adding the generated Axis2UserGuideService-test-client.jar file in +build/lib to the CLASSPATH and type: java +org.apache.axis2.axis2userguide.Client
    7. +
+

The long story:

+

Download +and unpack the Apache Axis2 Standard Distribution, if you have not +done so already. The WAR +distribution does not include the necessary utilities for +generating code, such as WSDL2Java.

+

The XMLBeans method of generating clients, unlike ADB, creates +individual classes for each object it must model. For example, +generating a client for this WSDL file created 642 files and +folders. A small number of these files are directly related to the +actual client you're creating. The rest are related to the +processing of XML, and include data bound objects for schemas, +encodings, and other objects needed to process messages.

+

To generate the client, issue the following command in Listing +2.

+

Code Listing 2. Generating the client

+
+%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d xmlbeans -s
+

This command analyzes the WSDL file and creates the stubs in the +package org.apache.axis2.axis2userguide. The options specify that +you want the XMLBeans data binding method (-d), and synchronous or +blocking methods (-s). In other words, when the client makes an +In-Out call to the service, it will wait for a response before +continuing.

+

Once you run this command, you will see several new items in the +directory. The first is the build.xml file, which contains the +instructions for Ant to +compile the generated classes. The second is the src directory, +which contains all the generated classes. The third is the +resources directory, which includes files related to the actual +data binding process.

+

Now you need a client. To create a client, create a new class +and save it as Client.java in the org/apache/axis2/axis2userguide +directory. It should contain the following code in Listing 3.

+

Code Listing 3: Client.java

+
+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");
+        }
+    }
+
+    /* fire and forget */
+    public static void doInOnly(Axis2UserGuideServiceStub stub){
+        try{
+            DoInOnlyRequestDocument req =
+                DoInOnlyRequestDocument.Factory.newInstance();
+            DoInOnlyRequestDocument.DoInOnlyRequest data =
+                req.addNewDoInOnlyRequest();
+
+            data.setMessageString("fire and forget it!");
+
+            stub.DoInOnly(req);
+            System.out.println("done");
+        } catch(Exception e){
+            e.printStackTrace();
+            System.out.println("\n\n\n");
+        }
+    }
+
+    /* two way call/receive */
+    public static void twoWayOneParameterEcho(Axis2UserGuideServiceStub stub){
+        try{
+            TwoWayOneParameterEchoRequestDocument req =
+                TwoWayOneParameterEchoRequestDocument.Factory.newInstance();
+            TwoWayOneParameterEchoRequestDocument.TwoWayOneParameterEchoRequest data =
+                req.addNewTwoWayOneParameterEchoRequest();
+
+            data.setEchoString("echo! ... echo!");
+
+            TwoWayOneParameterEchoResponseDocument res =
+                stub.TwoWayOneParameterEcho(req);
+
+            System.out.println(res.getTwoWayOneParameterEchoResponse().getEchoString());
+        } catch(Exception e){
+            e.printStackTrace();
+            System.out.println("\n\n\n");
+        }
+    }
+
+    /* No parameters */
+    public static void noParameters(Axis2UserGuideServiceStub stub){
+        try{
+            NoParametersRequestDocument req =
+                NoParametersRequestDocument.Factory.newInstance();
+            NoParametersRequestDocument.NoParametersRequest data =
+                req.addNewNoParametersRequest();
+
+            System.out.println(stub.NoParameters(req));
+        } catch(Exception e){
+            e.printStackTrace();
+            System.out.println("\n\n\n");
+        }
+    }
+
+    /* multiple parameters */
+    public static void multipleParameters(Axis2UserGuideServiceStub stub){
+        try{
+            MultipleParametersAddItemRequestDocument req =
+                MultipleParametersAddItemRequestDocument.Factory.newInstance();
+            MultipleParametersAddItemRequestDocument.
+                MultipleParametersAddItemRequest data =
+                req.addNewMultipleParametersAddItemRequest();
+
+            data.setPrice((float)1.99);
+            data.setItemId((int)23872983);
+            data.setDescription("Must have for cooking");
+            data.setItemName("flour");
+
+            MultipleParametersAddItemResponseDocument res =
+                stub.MultipleParametersAddItem(req);
+            MultipleParametersAddItemResponseDocument.
+                MultipleParametersAddItemResponse dataRes =
+                res.getMultipleParametersAddItemResponse();
+
+            System.out.println(dataRes.getSuccessfulAdd());
+            System.out.println(dataRes.getItemId());
+        } catch(Exception e){
+            e.printStackTrace();
+            System.out.println("\n\n\n");
+        }
+    }
+}
+

XMLBeans uses a different architecture from ADB. In XMLBeans, +processing centers around documents, which are created through the +use of factories, and which include inner classes for the objects +they contain. The process is still the same -- you create a +request, and send it using the stub -- the code is just a bit more +complex.

+

To build the client, type: ant jar.client

+

This action creates two new directories, build and test. The +test directory will be empty, but the build directory will contain +two versions of the client. The first version in the lib directory +consists of two .jar files, one containing the Client class and the +stub implementations, and the other containing the XMLBeans-related +classes. The second version in the classes directory consists of +just the raw classes.

+

Make sure all the .jar files in the Axis2 lib directory are on +the classpath.

+

If you have a service corresponding to this client (if you +don't, check out the Building Services document) +you can run the client by adding the two .jar files to your +classpath and typing: +java.org.apache.axis2.axis2userguide.Client

+

You should see the response in a console window of your servlet +container. It should look something like this:

+

Response in a console window of your servlet container
+

+ +
+
+
+
+
+ + + Added: webservices/axis2/site/1_4_1/userguide-creatingclients.html URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4_1/userguide-creatingclients.html?rev=688807&view=auto ============================================================================== --- webservices/axis2/site/1_4_1/userguide-creatingclients.html (added) +++ webservices/axis2/site/1_4_1/userguide-creatingclients.html Mon Aug 25 11:10:04 2008 @@ -0,0 +1,500 @@ + + + + + + + + + + + + + + + Apache Axis2 - + + + + + + + +
+ +
+
+
+ Apache Axis2 User's Guide- Creating Clients

Apache Axis2 User's Guide - Creating Clients

When it comes to creating a Web service client, you can do it +manually (see Building +Services), but in most cases you have a Web Service Description +Language (WSDL) definition that describes the messages clients +should send and expect to receive. Axis2 provides several ways to +use this definition to automatically generate a client.

+

Content

+

Choosing a Client Generation Method

Axis2 gives you several options when it comes to mapping WSDL to +objects when generating clients. Three of these options are Axis2 +DataBinding Framework, XMLBeans, and JiBX databinding. All of these +methods involve using databinding to create Java objects out of the +XML structures used by the service, and each has its pros and cons. +You can also generate XML in-out stubs that are not based on +databinding.

+

Axis2 Databinding Framework (ADB): ADB is probably the simplest +method of generating an Axis2 client. In most cases, all of the +pertinent classes are created as inner classes of a main stub +class. ADB is very easy to use, but it does have limitations. It is +not meant to be a full schema binding application, and has +difficulty with structures such as XML Schema element extensions +and restrictions.

+

XMLBeans: Unlike ADB, XMLBeans is a fully functional schema +compiler, so it doesn't carry the same limitations as ADB. It is, +however, a bit more complicated to use than ADB. It generates a +huge number of files, and the programming model, while being +certainly usable, is not as straightforward as ADB.

+

JiBX: JiBX is a complete databinding framework that actually +provides not only WSDL-to-Java conversion, as covered in this +document, but also Java-to-XML conversion. In some ways, JiBX +provides the best of both worlds. JiBX is extremely flexible, +enabling you to choose the classes that represent your entities, +but it can be complicated to set up. On the other hand, once it is +set up, actually using the generated code is as easy as using +ADB.

+

In the end, for simple structures, ADB will likely be enough for +you. If, on the other hand you need more power or flexibility, +whether you choose XMLBeans or JiBX depends on how much power or +flexibility you need and your tolerance for complexity.

+

Generating Clients

The process for generating and using a client varies slightly +depending on the method of generation you choose. In all three +cases in this document, clients are generated from the same WSDL +file (see Code Listing +5).

+

Note that the document defines four operations, DoInOnly, +NoParameters, TwoWayOneParameterEcho, and +MultipleParametersAddItem. Each of the clients will include methods +for calling each of these operations.

+

(You can get more information on WSDL at http://www.w3.org/2002/ws/desc/ +.)

+

Axis Data Binding (ADB)

To create a client using ADB, execute the following steps:

+

The short story:

+
  1. +href="http://ws.apache.org/axis2/download/1_4_1/download.cgi#std-bin" +Download and unpack the Apache Axis2 Standard +Distribution, if you have not done it already.
    2. +
  2. Create the client stub with the following command: +
    +%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s
+
    3. +
  3. Create the client (for example, Client.java), a Java +application that uses the generated stub, and save it in the +org/apache/axis2/axis2userguide directory.
    4. +
  4. Build the client by typing: ant jar.client.
    5. +
  5. Assuming you have a corresponding service, run the client by +adding the generated Axis2UserGuideService-test-client.jar file +located in build/lib to the classpath and type: java +org.apache.axis2.axis2userguide.Client
    6. +
+

The long story:

+

If you have not done it already, +download and unpack the Apache Axis2 Standard Distribution. The +Axis2 WAR Distribution does not include the necessary utilities for +generating code, such as WSDL2Java.

+

In the ADB method of generating clients, all the functionalities +of the services are contained in a single class called a stub. The +stub contains inner classes corresponding to all the necessary +objects defined in the WSDL file, such as, in the case of this +WSDL, DoInOnlyRequestMessage. Once you have the stub, you will be +able to create a client by simply referring to these classes and +their methods. To generate the client, issue the following command +in Code Listing 6.

+

Code Listing 6 - Generating the Client

+%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s
+

This command analyzes the WSDL file and creates the stub in the +package org.apache.axis2.axis2userguide. The options specify that +you want the ADB data binding method (-d), and synchronous or +blocking, methods (-s). In other words, when the client makes an +In-Out call to the service, it will wait for a response before +continuing.

+

Once you run this command, you will see two new items in the +directory. The first is the build.xml file, which contains the +instructions for Ant to +compile the generated classes. The second is the src directory, +which contains the actual Axis2UserGuideServiceStub.java file. If +you open this file, you will see a collection of inner classes for +each of the items in the WSDL file. You'll also see a number of +calls to the Axis2 client API, including those that use AXIOM to +build and analyze the incoming and outgoing messages.

+

Now you need a client to make use of this code. To create a +client, create a new class and save it as Client.java in the +org/apache/axis2/axis2userguide directory. It should contain the +following code in Code +Listing 7.

+

Note that using the service is simply a matter of creating and +populating the appropriate type of request using the names defined +in the WSDL file, and then using the stub to actually send the +request to the appropriate method. For example, to call the +DoInOnly operation, you create a DoInOnlyRequest, use its +setMessageString() method to set the contents of its messageString +element, and pass it as an argument to stub.DoInOnly().

+

To build the client, type: ant jar.client

+

This action creates two new directories, build and test. The +test directory will be empty, but the build directory contains two +versions of the client. The first version, in the lib directory, is +a .jar file that contains the client class and the stub. The +second, in the classes directory, is just raw classes.

+

Make sure all the jar files in the Axis2 lib directory are in +the classpath.

+

If you have a service corresponding to this client you can run +the client by adding the jar file to your classpath and typing: +java org.apache.axis2.axis2userguide.Client

+

(If you don't have such a service,, refer to the Building services +document.)

+

You should see the response in the console window of your +servlet container. It should look something like this:

+

Response in a console window of your servlet container
+

+

ADB is not your only option for generating Web service clients. +Other options include XmlBeans, JiBX and +JAXBRI.

+

See the Next Section -Building +Services

+ +
+
+
+
+
+ + +