| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
| <!-- Generated by Apache Maven Doxia at Apr 17, 2012 -->
|
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
| <head>
|
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
| <title>Apache Axis2 - |
| |
| |
| Apache Axis2 User's Guide- Creating Clients</title>
|
| <style type="text/css" media="all">
|
| @import url("../css/maven-base.css");
|
| @import url("../css/maven-theme.css");
|
| @import url("../css/site.css");
|
| </style>
|
| <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
|
| <meta name="Date-Revision-yyyymmdd" content="20120417" />
|
| <meta http-equiv="Content-Language" content="en" />
|
| <meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" /><meta http-equiv="content-type" content="" />
|
| </head>
|
| <body class="composite">
|
| <div id="banner">
|
| <a href="http://www.apache.org/" id="bannerLeft">
|
| <img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Axis2" />
|
| </a>
|
| <a href="" id="bannerRight">
|
| <img src="../images/axis.jpg" alt="Apache Axis2" />
|
| </a>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| </div>
|
| <div id="breadcrumbs">
|
|
|
|
|
| <div class="xleft">
|
| <span id="publishDate">Last Published: 2012-04-17</span>
|
| | <span id="projectVersion">Version: 1.6.2</span>
|
| </div>
|
| <div class="xright"> <a href="../index.html" title="Axis2/Java">Axis2/Java</a>
|
| |
|
| <a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a>
|
|
|
|
|
| </div>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| </div>
|
| <div id="leftColumn">
|
| <div id="navcolumn">
|
|
|
|
|
| <h5>Axis2/Java</h5>
|
| <ul>
|
| <li class="none">
|
| <a href="../index.html" title="Home">Home</a>
|
| </li>
|
| </ul>
|
| <h5>Downloads</h5>
|
| <ul>
|
| <li class="none">
|
| <a href="../download.cgi" title="Releases">Releases</a>
|
| </li>
|
| <li class="none">
|
| <a href="../modules/index.html" title="Modules">Modules</a>
|
| </li>
|
| <li class="none">
|
| <a href="../tools/index.html" title="Tools">Tools</a>
|
| </li>
|
| </ul>
|
| <h5>Documentation</h5>
|
| <ul>
|
| <li class="none">
|
| <a href="../docs/toc.html" title="Table of Contents">Table of Contents</a>
|
| </li>
|
| <li class="none">
|
| <a href="../docs/installationguide.html" title="Installation Guide">Installation Guide</a>
|
| </li>
|
| <li class="none">
|
| <a href="../docs/quickstartguide.html" title="QuickStart Guide">QuickStart Guide</a>
|
| </li>
|
| <li class="none">
|
| <a href="../docs/userguide.html" title="User Guide">User Guide</a>
|
| </li>
|
| <li class="none">
|
| <a href="../docs/jaxws-guide.html" title="JAXWS Guide">JAXWS Guide</a>
|
| </li>
|
| <li class="none">
|
| <a href="../docs/pojoguide.html" title="POJO Guide">POJO Guide</a>
|
| </li>
|
| <li class="none">
|
| <a href="../docs/spring.html" title="Spring Guide">Spring Guide</a>
|
| </li>
|
| <li class="none">
|
| <a href="../docs/webadminguide.html" title="Web Administrator's Guide">Web Administrator's Guide</a>
|
| </li>
|
| <li class="none">
|
| <a href="../docs/migration.html" title="Migration Guide (from Axis1)">Migration Guide (from Axis1)</a>
|
| </li>
|
| </ul>
|
| <h5>Resources</h5>
|
| <ul>
|
| <li class="none">
|
| <a href="../faq.html" title="FAQ">FAQ</a>
|
| </li>
|
| <li class="none">
|
| <a href="../articles.html" title="Articles">Articles</a>
|
| </li>
|
| <li class="none">
|
| <a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki">Wiki</a>
|
| </li>
|
| <li class="none">
|
| <a href="../refLib.html" title="Reference Library">Reference Library</a>
|
| </li>
|
| <li class="none">
|
| <a href="../api/index.html" title="Online Java Docs">Online Java Docs</a>
|
| </li>
|
| </ul>
|
| <h5>Get Involved</h5>
|
| <ul>
|
| <li class="none">
|
| <a href="../overview.html" title="Overview">Overview</a>
|
| </li>
|
| <li class="none">
|
| <a href="../svn.html" title="Checkout the Source">Checkout the Source</a>
|
| </li>
|
| <li class="none">
|
| <a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
|
| </li>
|
| <li class="none">
|
| <a href="../release-process.html" title="Release Process">Release Process</a>
|
| </li>
|
| <li class="none">
|
| <a href="../guidelines.html" title="Developer Guidelines">Developer Guidelines</a>
|
| </li>
|
| <li class="none">
|
| <a href="../siteHowTo.html" title="Build the Site">Build the Site</a>
|
| </li>
|
| </ul>
|
| <h5>Project Information</h5>
|
| <ul>
|
| <li class="none">
|
| <a href="../team-list.html" title="Project Team">Project Team</a>
|
| </li>
|
| <li class="none">
|
| <a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
|
| </li>
|
| <li class="none">
|
| <a href="http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/" class="externalLink" title="Source Code">Source Code</a>
|
| </li>
|
| <li class="none">
|
| <a href="../thanks.html" title="Acknowledgements">Acknowledgements</a>
|
| </li>
|
| <li class="none">
|
| <a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License">License</a>
|
| </li>
|
| <li class="none">
|
| <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">Sponsorship</a>
|
| </li>
|
| <li class="none">
|
| <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">Thanks</a>
|
| </li>
|
| <li class="none">
|
| <a href="http://www.apache.org/security/" class="externalLink" title="Security">Security</a>
|
| </li>
|
| </ul>
|
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
|
| <img class="poweredBy" alt="Built by Maven" src="../images/logos/maven-feather.png" />
|
| </a>
|
|
|
|
|
| </div>
|
| </div>
|
| <div id="bodyColumn">
|
| <div id="contentBox">
|
| <!-- ~ 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. --><html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
| |
| <a name="createclients" id="createclients"></a> |
| <h1>Apache Axis2 User's Guide - Creating Clients</h1> |
| <p>When it comes to creating a Web service client, you can do it |
| manually (see <a href="userguide-buildingservices.html">Building |
| Services</a>), 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.</p> |
| <div class="section"><h2>Content<a name="Content"></a></h2> |
| <ul> |
| <li><a href="userguide.html#intro">Introducing Axis2</a><br /> |
| <ul> |
| <li><a href="userguide.html#whatis">What is Axis2?</a></li> |
| <li><a href="userguide.html#underhood">What's Under the |
| hood?</a></li> |
| <li><a href="userguide.html#handlessoap">How Axis2 Handles SOAP |
| Messages</a></li> |
| <li><a href="userguide.html#distributions">Axis2 |
| Distributions</a></li> |
| <li><a href="userguide.html#sbd">The Axis2 Standard Binary |
| Distribution</a></li> |
| <li><a href="userguide.html#hierarchy">Axis2.war Directory |
| hierarchy</a></li> |
| <li><a href="userguide.html#docs">Axis2 Documents |
| Distribution</a></li> |
| <li><a href="userguide.html#clients">Axis2 and Clients</a></li> |
| </ul> |
| </li> |
| <li><a href="userguide-installingtesting.html#installingtesting">Installing and |
| Testing Client Code</a></li> |
| <li><a href="userguide-introtoservices.html#introservices">Introduction to |
| Services</a><br /> |
| <ul> |
| <li><a href="userguide-introtoservices.html#messageexchange">Message Exchange |
| Patterns</a></li> |
| </ul> |
| </li> |
| <li><a href="userguide-creatingclients.html#createclients"><b>Creating |
| Clients</b></a><br /> |
| <ul> |
| <li><a href="userguide-creatingclients.html#choosingclient"><b>Choosing a |
| Client Generation Method</b></a></li> |
| <li><a href="userguide-creatingclients.html#generating"><b>Generating |
| Clients</b></a></li> |
| <li><a href="userguide-creatingclients.html#adb"><b>Axis Data |
| Binding (ADB)</b></a></li> |
| </ul> |
| </li> |
| <li><a href="userguide-buildingservices.html#buildservices">Building |
| Services</a><br /> |
| <ul> |
| <li><a href="userguide-buildingservices.html#getcomfortable">Getting |
| Comfortable with Available Options</a></li> |
| <li><a href="userguide-buildingservices.html#createscratch">Creating a service |
| from Scratch</a></li> |
| <li><a href="userguide-buildingservices.html#deploypojo">Deploying |
| Plain Old Java Objects</a></li> |
| <li><a href="userguide-buildingservices.html#deployrun">Deploying |
| and Running an Axis2 Service Created from WSDL</a></li> |
| </ul> |
| </li> |
| <li><a href="userguide-samples.html">Samples</a></li> |
| <li><a href="userguide-forfurtherstudy.html">For Further |
| Study</a></li> |
| </ul> |
| <a name="choosingclient" id="choosingclient"></a> |
| <div class="section"><h2>Choosing a Client Generation Method<a name="Choosing_a_Client_Generation_Method"></a></h2> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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.</p> |
| <p>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.</p> |
| <a name="generating" id="generating"></a> |
| <div class="section"><h2>Generating Clients<a name="Generating_Clients"></a></h2> |
| <p>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 <a href="userguide-codelisting5.html">Code Listing |
| 5</a>).</p> |
| <p>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.</p> |
| <p>(You can get more information on WSDL at <a class="externalLink" href="http://www.w3.org/2002/ws/desc/">http://www.w3.org/2002/ws/desc/</a> |
| .)</p> |
| <a name="adb" id="adb"></a> |
| <div class="section"><h2>Axis Data Binding (ADB)<a name="Axis_Data_Binding_ADB"></a></h2> |
| <p>To create a client using ADB, execute the following steps:</p> |
| <p><b>The short story:</b></p> |
| <ol style="list-style-type: decimal"> |
| <li> |
| <a href="../download.cgi">Download</a> and unpack the Apache Axis2 Standard |
| Distribution, if you have not done it already.</li> |
| <li>Create the client stub with the following command: |
| <div><pre> |
| %AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s |
| </pre></div></li> |
| <li>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.</li> |
| <li>Build the client by typing: ant jar.client.</li> |
| <li>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</li> |
| </ol> |
| <p><b>The long story:</b></p> |
| <p>If you have not done it already, <a href="../download.cgi"> |
| download</a> and unpack the Apache Axis2 Standard Distribution. The |
| Axis2 WAR Distribution does not include the necessary utilities for |
| generating code, such as WSDL2Java.</p> |
| <p>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.</p> |
| <div class="section"><h3><b>Code Listing 6 - Generating the Client</b><a name="Code_Listing_6_-_Generating_the_Client"></a></h3> |
| <div><pre> |
| %AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s |
| </pre></div> |
| <p>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.</p> |
| <p>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 <a class="externalLink" href="http://ant.apache.org/">Ant</a> 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.</p> |
| <p>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 <a href="userguide-codelisting7.html">Code |
| Listing 7</a>.</p> |
| <p>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().</p> |
| <p>To build the client, type: ant jar.client</p> |
| <p>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.</p> |
| <p>Make sure all the jar files in the Axis2 lib directory are in |
| the classpath.</p> |
| <p>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</p> |
| <p>(If you don't have such a service,, refer to the <a href="userguide-buildingservices.html">Building services</a> |
| document.)</p> |
| <p>You should see the response in the console window of your |
| servlet container. It should look something like this:</p> |
| <p><img src="images/fig03.jpg" alt="Response in a console window of your servlet container" /><br /></p> |
| <p>ADB is not your only option for generating Web service clients. |
| Other options include <a href="userguide-creatingclients-xmlbeans.html">XmlBeans</a>, <a href="userguide-creatingclients-jibx.html">JiBX</a> and |
| JAXBRI.</p> |
| <p><b>See the Next Section</b> -<a href="userguide-buildingservices.html#buildservices">Building |
| Services</a></p> |
| </div> |
| </html>
|
| </div>
|
| </div>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| <div id="footer">
|
| <div class="xright">Copyright © 2004-2012
|
| <a href="http://www.apache.org/">The Apache Software Foundation</a>.
|
| All Rights Reserved.
|
|
|
| </div>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| </div>
|
| </body>
|
| </html>
|