Author: chatra Date: Wed Dec 20 06:54:37 2006 New Revision: 489107 URL: http://svn.apache.org/viewvc?view=rev&rev=489107 Log: made corrections regarding issue 1 in https://issues.apache.org/jira/browse/AXIS2-1896 Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/userguide-creatingclients.html Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/userguide-creatingclients.html URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/userguide-creatingclients.html?view=diff&rev=489107&r1=489106&r2=489107 ============================================================================== --- webservices/axis2/branches/java/1_1/xdocs/1_1/userguide-creatingclients.html (original) +++ webservices/axis2/branches/java/1_1/xdocs/1_1/userguide-creatingclients.html Wed Dec 20 06:54:37 2006 @@ -1,233 +1,232 @@ - - - - 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 -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.

- -

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 certainly usable, is not as straightforward as -ADB.

- -

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.

- -

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).

- -

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.

- -

(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_1/download.cgi#std-bin"If - you have not done it already, download and unpack the - Apache Axis2 Standard Distribution.
  2. -
  3. Create the client stub with the following command: -
    %AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s
    -
  4. -
  5. 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.
  6. -
  7. Build the client by typing ant jar.client.
  8. -
  9. 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: -
    java org.apache.axis2.axis2userguide.Client
    -
  10. -
- -

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 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.

- -

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 a 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.

- -

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().

- -

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 -the raw classes.

- -

Make sure all of 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 jar file 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
-

- -

ADB is not your only option for generating web service clients. Other -options include XmlBeans, JiBX, JAXME and JAXBRI.

- -

See Next Section -Building Services

- - + + + + 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 +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.

+ +

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 certainly usable, is not as straightforward as +ADB.

+ +

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.

+ +

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).

+ +

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.

+ +

(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. If you have not done it already, download and unpack the + Apache Axis2 Standard Distribution.
  2. +
  3. Create the client stub with the following command: +
    %AXIS2_HOME%\bin\WSDL2Java -uri Axis2UserGuide.wsdl -p org.apache.axis2.axis2userguide -d adb -s
    +
  4. +
  5. 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.
  6. +
  7. Build the client by typing ant jar.client.
  8. +
  9. 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: +
    java org.apache.axis2.axis2userguide.Client
    +
  10. +
+ +

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 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.

+ +

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 a 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.

+ +

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().

+ +

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 +the raw classes.

+ +

Make sure all of 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 jar file 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
+

+ +

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

+ +

See Next Section -Building Services

+ + --------------------------------------------------------------------- To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org For additional commands, e-mail: axis-cvs-help@ws.apache.org