maven2/xdocs/1_1/userguide-creatingclients.html - axis-axis2-java-core - Git at Google

 <html lang="en">
 <head>
   <meta http-equiv="content-type" content="">
   <title>Apache Axis2 User's Guide- Creating Clients</title>
   <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
   media="all" />
 </head>

 <body>
 <a name="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>

 <h2>Content</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"><strong>Creating
     Clients</strong></a><br>

     <ul>
       <li><a
         href="userguide-creatingclients.html#choosingclient"><strong>Choosing
         a Client Generation Method</strong></a></li>
       <li><a
         href="userguide-creatingclients.html#generating"><strong>Generating
         Clients</strong></a></li>
       <li><a href="userguide-creatingclients.html#adb"><strong>Axis Data
         Binding (ADB)</strong></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"></a>

 <h2>Choosing a Client Generation Method</h2>

 <p>Axis2 gives you several options when it comes to mapping WSDL to objects
 in 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 certainly usable, is not as straightforward as
 ADB.</p>

 <p>JiBX: JiBX is a full 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"></a>

 <h2>Generating Clients</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>Notice 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
 href="http://www.w3.org/2002/ws/desc/">http://www.w3.org/2002/ws/desc/</a>
 .)</p>
 <a name="adb"></a>

 <h2>Axis Data Binding (ADB)</h2>

 <p>To create a client using ADB, execute the following steps:</p>

 <p><b>The short story:</b></p>
 <ol>
   <li>href="http://ws.apache.org/axis2/download/1_1/download.cgi#std-bin"If
     you have not done it already, <a href="">download</a> and unpack the
     Apache Axis2 Standard Distribution.</li>
   <li>Create the client stub with the following command:
     <pre>%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s</pre>
   </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 typing:
     <pre>java org.apache.axis2.axis2userguide.Client</pre>
   </li>
 </ol>

 <p><b>The long story:</b></p>

 <p>If you have not done it already, <a
 href="http://ws.apache.org/axis2/download/1_1/download.cgi#std-bin">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 functionality for the
 services are contained a single class called a stub. The stub contains inner
 classes corresponding to all of 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>

 <h3><b>Code Listing 6 - Generating the Client</b></h3>
 <pre>%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s</pre>

 <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 a 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
 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>Notice 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
 the raw classes.</p>

 <p>Make sure all of the jar files in the Axis2 lib directory are on the
 classpath.</p>

 <p>If you have a service corresponding to this client -- if you don't, check
 out the <a href="userguide-buildingservices.html">Building services</a>
 document -- you can run the client by adding the jar file to your classpath
 and typing: java org.apache.axis2.axis2userguide.Client</p>

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

 <p><img alt="Response in a console window of your servlet container"
 src="images/fig03.jpg"><br clear="all">
 </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>, JAXME and JAXBRI.</p>

 <p><strong>See Next Section</strong> -<a
 href="userguide-buildingservices.html#buildservices">Building Services</a></p>
 </body>
 </html>
	<html lang="en">
	<head>
	<meta http-equiv="content-type" content="">
	<title>Apache Axis2 User's Guide- Creating Clients</title>
	<link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
	media="all" />
	</head>

	<body>
	<a name="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>

	<h2>Content</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"><strong>Creating
	Clients</strong></a><br>

	<ul>
	<li><a
	href="userguide-creatingclients.html#choosingclient"><strong>Choosing
	a Client Generation Method</strong></a></li>
	<li><a
	href="userguide-creatingclients.html#generating"><strong>Generating
	Clients</strong></a></li>
	<li><a href="userguide-creatingclients.html#adb"><strong>Axis Data
	Binding (ADB)</strong></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"></a>

	<h2>Choosing a Client Generation Method</h2>

	<p>Axis2 gives you several options when it comes to mapping WSDL to objects
	in 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 certainly usable, is not as straightforward as
	ADB.</p>

	<p>JiBX: JiBX is a full 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"></a>

	<h2>Generating Clients</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>Notice 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
	href="http://www.w3.org/2002/ws/desc/">http://www.w3.org/2002/ws/desc/</a>
	.)</p>
	<a name="adb"></a>

	<h2>Axis Data Binding (ADB)</h2>

	<p>To create a client using ADB, execute the following steps:</p>

	<p><b>The short story:</b></p>
	<ol>
	<li>href="http://ws.apache.org/axis2/download/1_1/download.cgi#std-bin"If
	you have not done it already, <a href="">download</a> and unpack the
	Apache Axis2 Standard Distribution.</li>
	<li>Create the client stub with the following command:
	<pre>%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s</pre>
	</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 typing:
	<pre>java org.apache.axis2.axis2userguide.Client</pre>
	</li>
	</ol>

	<p><b>The long story:</b></p>

	<p>If you have not done it already, <a
	href="http://ws.apache.org/axis2/download/1_1/download.cgi#std-bin">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 functionality for the
	services are contained a single class called a stub. The stub contains inner
	classes corresponding to all of 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>

	<h3><b>Code Listing 6 - Generating the Client</b></h3>
	<pre>%AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s</pre>

	<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 a 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
	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>Notice 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
	the raw classes.</p>

	<p>Make sure all of the jar files in the Axis2 lib directory are on the
	classpath.</p>

	<p>If you have a service corresponding to this client -- if you don't, check
	out the <a href="userguide-buildingservices.html">Building services</a>
	document -- you can run the client by adding the jar file to your classpath
	and typing: java org.apache.axis2.axis2userguide.Client</p>

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

	<p><img alt="Response in a console window of your servlet container"
	src="images/fig03.jpg"><br clear="all">
	</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>, JAXME and JAXBRI.</p>

	<p><strong>See Next Section</strong> -<a
	href="userguide-buildingservices.html#buildservices">Building Services</a></p>
	</body>
	</html>