scheu 01/12/19 07:30:08 Modified: java/docs user-guide.html Log: Added Java2WSDL section, change tool names to WSDL2Java/Java2WSDL, Added links to the tool sections Revision Changes Path 1.31 +972 -596 xml-axis/java/docs/user-guide.html Index: user-guide.html =================================================================== RCS file: /home/cvs/xml-axis/java/docs/user-guide.html,v retrieving revision 1.30 retrieving revision 1.31 diff -u -r1.30 -r1.31 --- user-guide.html 2001/12/19 14:30:59 1.30 +++ user-guide.html 2001/12/19 15:30:08 1.31 @@ -1,8 +1,10 @@ - + -Axis User's Guide - + + + Axis User's Guide + + + +
+

+

+ +

+Axis User's Guide

+Alpha 3 Version +

+Table of Contents

+ + + +

+Introduction

+Welcome to Axis, the third generation of Apache SOAP! This is the alpha +3 version. Please note that Axis is a work in progress, and although +the basic functionality is there, there are still a lot of unfinished areas +and rough edges. That said, we're very psyched about the package so far +and would love to get your take on how we can make it better. +

+What is SOAP?

+SOAP is an XML-based communitcation protocol and encoding format +for inter-application communication. Originally conceived by Microsoft +and Userland software, it has evolved through several generations and the +current spec, SOAP 1.1, is fast growing +in popularity and usage. The W3C's XML Protocol working group is in the +process of turning SOAP into a true open standard, and as of this writing +has released a working draft of SOAP 1.2, which cleans up some of the more +confusing areas of the 1.1 spec. +

SOAP is widely viewed as the backbone to a new generation of cross-platform +cross-language distributed computing applications, termed Web Services. +

+What is Axis?

+Apache SOAP began at IBM as "SOAP4J" and then became Apache SOAP version +2. The committers on the v2 project began some conversations in late 2000 +about making the engine much more flexible, configurable, and able to handle +both SOAP and the upcoming XML Protocol specification from the W3C. +

After a little while, it became clear that a ground-up rearchitecture +was the way to go. Several of the v2 committers proposed very similar designs, +all based around configurable "chains" of message "handlers" which would +implement small bits of functionality in a very flexible and composable +manner. Axis is the result of months of continued discussion and coding +effort in this direction. Some of the key Axis features include the following:

-

What's missing?

+We hope you enjoy using Axis. Please note that this is an open-source effort +- if you feel the code could use some new features or fixes, please get +involved and lend a hand! The Axis developer community welcomes your participation. +

+Let us know what you think!

+Please send feedback about the package to "axis-user@xml.apache.org". +Also, Axis is regsitered in bugzilla, +the Apache bug tracking and feature-request database. +

+What's in this release?

+This release includes the following features: + +

+What's missing?

+ + -

All of these items are on the list for the final release.

-

Installing Axis and Using this Guide

-

See the Axis Installation Guide for instructions - on installing Axis as a web application on your J2EE server.

-

Before running the examples in this guide, you'll need to make sure that axis.jar - is in your classpath. You should find it in the build/lib directory of the distribution.

- -

Consuming Web Services with Axis

-

Basics - Getting Started

-

Let's take a look at an example Web Service client that will call the echoString - method on the public Axis server at Apache.

+All of these items are on the list for the final release. +

+Installing Axis and Using this Guide

+See the Axis Installation Guide for instructions +on installing Axis as a web application on your J2EE server. +

Before running the examples in this guide, you'll need to make sure +that axis.jar is in your classpath. You should find it in the build/lib +directory of the distribution. +

+Consuming Web Services with Axis

+ +

+Basics - Getting Started

+Let's take a look at an example Web Service client that will call the echoString +method on the public Axis server at Apache.
-
  -1   import org.apache.axis.client.Call;
  -2   import org.apache.axis.client.Service;
  -3   
  -4   public class TestClient
  -5   {
  -6      public static void main(String [] args) {
  -7          try {
  -8              String endpoint =
  -9                       "http://nagoya.apache.org:5049/axis/servlet/AxisServlet";
  -10  
  -11             Service  service = new Service();
  -12             Call     call    = (Call) service.createCall();
  -13  
  -14             call.setTargetEndpointAddress( new java.net.URL(endpoint) );
  -15             call.setOperationName( "echoString" );
  -16             call.setProperty( Call.NAMESPACE, "http://soapinterop.org/" );
  -17  
  -18             String ret = (String) call.invoke( new Object[] { "Hello!" } );
  -19  
  -20             System.out.println("Sent 'Hello!', got '" + ret + "'");
  -21         } catch (Exception e) {
  -22             System.err.println(e.toString());
  -23         }
  -24     }
  -25  }
  -
+
1   import org.apache.axis.client.Call;
  +2   import org.apache.axis.client.Service;
  +3   
  +4   public class TestClient
  +5   {
  +6      public static void main(String [] args) {
  +7          try {
  +8              String endpoint =
  +9                       "http://nagoya.apache.org:5049/axis/servlet/AxisServlet";
  +10  
  +11             Service  service = new Service();
  +12             Call     call    = (Call) service.createCall();
  +13  
  +14             call.setTargetEndpointAddress( new java.net.URL(endpoint) );
  +15             call.setOperationName( "echoString" );
  +16             call.setProperty( Call.NAMESPACE, "http://soapinterop.org/" );
  +17  
  +18             String ret = (String) call.invoke( new Object[] { "Hello!" } );
  +19  
  +20             System.out.println("Sent 'Hello!', got '" + ret + "'");
  +21         } catch (Exception e) {
  +22             System.err.println(e.toString());
  +23         }
  +24     }
  +25  }
-

(You'll find this file in samples/userguide/example1/TestClient.java)

-

Assuming you have a network connection active, this program can be run as follows:

+(You'll find this file in samples/userguide/example1/TestClient.java) +

Assuming you have a network connection active, this program can be run +as follows:

% java samples.userguide.example1.TestClient
   Sent 'Hello!', got 'Hello!'
  -% 
-

- So what's happening here? On lines 11 and 12 we create new Service and Call - objects. These are the standard JAX-RPC objects that are used to store - metadata about the service to invoke. On line 14, we set up our endpoint - URL - this is the destination for our SOAP message. On line 15 we define - the operation (method) name of the Web Service. Line 16 defines the - namespace to use on the Body of the SOAP message. And on line 18 we - actually invoke the desired service, passing in an array of parameters - - in this case just one String. - -

You can see what happens to the arguments by looking at the SOAP request that - goes out on the wire (look at the colored sections, and notice they match the - values in the call above):

-
-
<?xml version="1.0" encoding="UTF-8"?>
  +%
+So what's happening here? On lines 11 and 12 we create new Service and +Call objects. These are the standard JAX-RPC objects that are used to store +metadata about the service to invoke. On line 14, we set up our endpoint +URL - this is the destination for our SOAP message. On line 15 we define +the operation (method) name of the Web Service. Line 16 defines the namespace +to use on the Body of the SOAP message. And on line 18 we actually invoke +the desired service, passing in an array of parameters - in this case just +one String. +

You can see what happens to the arguments by looking at the SOAP request +that goes out on the wire (look at the colored sections, and notice they +match the values in the call above): +

+
<?xml version="1.0" encoding="UTF-8"?>
   <SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  -                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  -                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  -  <SOAP-ENV:Body>
  -    <ns1:echoString xmlns:ns1="http://soapinterop.org/">
  -      <arg0 xsi:type="xsd:string">Hello!</arg0>
  -    </ns1:echoString>
  -  </SOAP-ENV:Body>
  -</SOAP-ENV:Envelope>
  -
-
+                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" +                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> +  <SOAP-ENV:Body> +    <ns1:echoString xmlns:ns1="http://soapinterop.org/"> +      <arg0 xsi:type="xsd:string">Hello!</arg0> +    </ns1:echoString> +  </SOAP-ENV:Body> +</SOAP-ENV:Envelope>
-

The String argument is automatically serialized into XML, and the server responds - with an identical String, which we deserialize and print.

-

Note: to actually watch the XML flowing back and forth between a SOAP client - and server, you can use the included tcpmon tool. See the appendix - for an overview.

-

Naming Parameters

-

In the above example, the parameters are in the order in which we sent them, - but since we only passed the objects themselves, Axis automatically named the - XML-encoded arguments in the SOAP message "arg0", "arg1", etc. If you want to - change this, it's easy! Before calling invoke() you need to call - addParameter for each parameter, like so: -

  -  call.addParameter("testParam", 
  -                    org.apache.axis.encoding.XMLType.XSD_STRING,
  -                    Call.PARAM_MODE_IN);
  -

- +The String argument is automatically serialized into XML, and the server +responds with an identical String, which we deserialize and print. +

Note: to actually watch the XML flowing back and forth between a +SOAP client and server, you can use the included tcpmon tool. See the appendix +for an overview. +

+Naming Parameters

+In the above example, the parameters are in the order in which we sent +them, but since we only passed the objects themselves, Axis automatically +named the XML-encoded arguments in the SOAP message "arg0", "arg1", etc. +If you want to change this, it's easy! Before calling invoke() +you need to call addParameter for each parameter, like so: +
+
  call.addParameter("testParam", 
  +                    org.apache.axis.encoding.XMLType.XSD_STRING,
  +                    Call.PARAM_MODE_IN);
+
This will assign the name testParam to the 1st (and only) parameter -on the invoke call. This will also define the type of the parameter -(org.apache.axis.encoding.XMLType.XSD_STRING) and whether it is -an input, output or inout parameter - in this case its an input parameter. -Now when you run the program you'll get a message that looks like this: +on the invoke call. This will also define the type of the parameter (org.apache.axis.encoding.XMLType.XSD_STRING) +and whether it is an input, output or inout parameter - in this case its +an input parameter. Now when you run the program you'll get a message that +looks like this:
-
<?xml version="1.0" encoding="UTF-8"?>
  +
<?xml version="1.0" encoding="UTF-8"?>
   <SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  -                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  -                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  -  <SOAP-ENV:Body>
  -    <ns1:echoString xmlns:ns1="http://soapinterop.org/">
  -      <testParam xsi:type="xsd:string">Hello!</testParam>
  -    </ns1:echoString>
  -  </SOAP-ENV:Body>
  -</SOAP-ENV:Envelope>
- +                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" +                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> +  <SOAP-ENV:Body> +    <ns1:echoString xmlns:ns1="http://soapinterop.org/"> +      <testParam xsi:type="xsd:string">Hello!</testParam> +    </ns1:echoString> +  </SOAP-ENV:Body> +</SOAP-ENV:Envelope>
-

Note that the param is now named "testParam" as expected.

-

Interoperating with "untyped" servers

-

In the above examples, we've been casting the return type of invoke(), which - is Object, to the appropriate "real" type - for instance, we know - that the echoString method returns a String, so we expect to get one back from - client.invoke(). Let's take a moment and investigate how this happens, which - sheds light on a potential problem (to which, of course, we have a solution - - so don't fret :)).

-

Here's what a typical response might look like to the echoString method:

-
<?xml version="1.0" encoding="UTF-8"?> -<SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" - xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> - <SOAP-ENV:Body> - <ns1:echoStringResponse xmlns:ns1="http://soapinterop.org/"> - <result xsi:type="xsd:string">Hello!</result> - </ns1:echoStringResponse> - </SOAP-ENV:Body> -</SOAP-ENV:Envelope>
-

Take a look at the section which we've highlighted in red - that attribute - is a schema type declaration, which Axis uses to figure out that the - contents of that element are, in this case, deserializable into a Java String - object. Many toolkits put this kind of explicit typing information in the XML - to make the message "self-describing". On the other hand, some toolkits - return responses that look like this:

-
<?xml version="1.0" encoding="UTF-8"?> -<SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" - xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> - <SOAP-ENV:Body> - <ns1:echoStringResponse xmlns:ns1="http://soapinterop.org/"> - <result>Hello, I'm a string!</result> - </ns1:echoStringResponse> - </SOAP-ENV:Body> -</SOAP-ENV:Envelope>
-

There's no type in the message, so how do we know what Java object we should - deserialize the <result> element into? The answer is metadata - - data about data. In this case, we need a description of the service that - tells us what to expect as the return type. Here's how to do it on the client - side in Axis:

+Note that the param is now named "testParam" as expected. +

+Interoperating with "untyped" servers

+In the above examples, we've been casting the return type of invoke(), +which is Object, to the appropriate "real" type - for instance, we know +that the echoString method returns a String, so we expect to get one back +from client.invoke(). Let's take a moment and investigate how this happens, +which sheds light on a potential problem (to which, of course, we have +a solution - so don't fret :)). +

Here's what a typical response might look like to the echoString method: +

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope +xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" +xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> +<ns1:echoStringResponse xmlns:ns1="http://soapinterop.org/"> <result +xsi:type="xsd:string">Hello!</result> +</ns1:echoStringResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
+Take a look at the section which we've highlighted in red - that attribute +is a schema type declaration, which Axis uses to figure out that +the contents of that element are, in this case, deserializable into a Java +String object. Many toolkits put this kind of explicit typing information +in the XML to make the message "self-describing". On the other hand, some +toolkits return responses that look like this: +
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope +xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" +xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> +<ns1:echoStringResponse xmlns:ns1="http://soapinterop.org/"> <result>Hello, +I'm a string!</result> </ns1:echoStringResponse> </SOAP-ENV:Body> +</SOAP-ENV:Envelope>
+There's no type in the message, so how do we know what Java object we should +deserialize the <result> element into? The answer is metadata +- data about data. In this case, we need a description of the service +that tells us what to expect as the return type. Here's how to do it on +the client side in Axis:
-
  call.setReturnType( org.apache.axis.encoding.XMLType.XSD_STRING ); 
+
  call.setReturnType( org.apache.axis.encoding.XMLType.XSD_STRING );
-

- This method will tell the Axis client that if the return element is not typed - then it should act as if the return value has an xsi:type attribute set to - the predefined SOAP String type. - (You can see an example of this in action in the interop echo-test - client - samples/echo/TestClient.java.)

-

OK - so now you know the basics of accessing SOAP services as a client. But - how do you publish your own services?

-

Publishing Web Services with Axis

-

Let's say we have a simple class like the following:

+This method will tell the Axis client that if the return element is not +typed then it should act as if the return value has an xsi:type attribute +set to the predefined SOAP String type. (You can see an example of this +in action in the interop echo-test client - samples/echo/TestClient.java.) +

OK - so now you know the basics of accessing SOAP services as a client. +But how do you publish your own services? +

+Publishing Web Services with Axis

+Let's say we have a simple class like the following:
public class Calculator {
  -  public int add(int i1, int i2)
  -  {
  -    return i1 + i2; 
  -  }
  -  
  -  public int subtract(int i1, int i2)
  -  {
  -    return i1 - i2;
  -  }
  -} 
  -
-

(You'll find this very class in samples/userguide/example2/Calculator.java.)

-

How do we go about making this class available via SOAP? There are a couple - of answers to that question, but we'll start with the easiest way Axis provides - to do this, which takes almost no effort at all!

-

JWS (Java Web Service) Files - Instant Deployment

-

OK, here's step 1 : copy the above .java file into your webapp directory, and - rename it "Calculator.jws". So you might do something like this:

-
% copy Calculator.java <your-webapp-root>/axis/Calculator.jws
-

Now for step 2... hm, wait a minute. You're done! You should now be able to - access the service at the following URL (assuming your Axis web application - is on port 8080):

-

http://localhost:8080/axis/Calculator.jws -

-

Axis automatically locates the file, compiles the class, and converts SOAP - calls correctly into Java invocations of your service class. Try it out - there's - a calculator client in samples/userguide/example2/CalcClient.java, which you - can use like this:

+  public int add(int i1, int i2) +  { +    return i1 + i2;  +  } +   +  public int subtract(int i1, int i2) +  { +    return i1 - i2; +  } +} +(You'll find this very class in samples/userguide/example2/Calculator.java.) +

How do we go about making this class available via SOAP? There are a +couple of answers to that question, but we'll start with the easiest way +Axis provides to do this, which takes almost no effort at all! +

+JWS (Java Web Service) Files - Instant Deployment

+OK, here's step 1 : copy the above .java file into your webapp directory, +and rename it "Calculator.jws". So you might do something like this: +
% copy Calculator.java <your-webapp-root>/axis/Calculator.jws
+Now for step 2... hm, wait a minute. You're done! You should now be able +to access the service at the following URL (assuming your Axis web application +is on port 8080): +

http://localhost:8080/axis/Calculator.jws +

Axis automatically locates the file, compiles the class, and converts +SOAP calls correctly into Java invocations of your service class. Try it +out - there's a calculator client in samples/userguide/example2/CalcClient.java, +which you can use like this:

% javac CalcClient.java
   % java CalcClient -p8080 add 2 5
   Got result : 7
   % java CalcClient -p8080 subtract 10 9
   Got result : 1
  -% 
-(note that you may need to replace the "-p8080" with whatever port your -J2EE server is running on) -

Custom Deployment - Introducing WSDD

-

JWS files are great quick ways to get your classes out there as Web Services, - but they're not always the best choice. For one thing, you need the source code - - there might be times when you want to expose a pre-existing class on your - system without source. Also, the amount of configuration you can do as to how - the service gets accessed is pretty limited - you can't specify custom type - mappings, or control which Handlers get invoked when people are using your service.

-

Deploying via descriptors

-To really use the flexibility available to you in Axis, you should get familiar -with the Axis Web Service Deployment Descriptor (WSDD) format. A deployment -descriptor contains a bunch of things you want to "deploy" into Axis - i.e. make -available to the Axis engine. The most common thing to deploy is a Web Service, -so let's start by taking a look at a deployment descriptor for a basic service -(this file is samples/userguide/example3/deploy.wsdd): -
-
<deployment xmlns="http://xml.apache.org/axis/wsdd/"
  -            xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
  - <service name="MyService" provider="java:RPC">
  -  <parameter name="className" value="samples.userguide.example3.MyService"/>
  -  <parameter name="methodName" value="*"/>
  - </service>
  -</deployment>
+% +(note that you may need to replace the "-p8080" with whatever port your +J2EE server is running on) +

+Custom Deployment - Introducing WSDD

+JWS files are great quick ways to get your classes out there as Web Services, +but they're not always the best choice. For one thing, you need the source +code - there might be times when you want to expose a pre-existing class +on your system without source. Also, the amount of configuration you can +do as to how the service gets accessed is pretty limited - you can't specify +custom type mappings, or control which Handlers get invoked when people +are using your service. +

+Deploying via descriptors

+To really use the flexibility available to you in Axis, you should get +familiar with the Axis Web Service Deployment Descriptor (WSDD) +format. A deployment descriptor contains a bunch of things you want to +"deploy" into Axis - i.e. make available to the Axis engine. The most common +thing to deploy is a Web Service, so let's start by taking a look at a +deployment descriptor for a basic service (this file is samples/userguide/example3/deploy.wsdd): +
+
<deployment xmlns="http://xml.apache.org/axis/wsdd/"
  +            xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
  + <service name="MyService" provider="java:RPC">
  +  <parameter name="className" value="samples.userguide.example3.MyService"/>
  +  <parameter name="methodName" value="*"/>
  + </service>
  +</deployment>
- -

Pretty simple, really - the outermost element tells the engine that this is - a WSDD deployment, and defines the "java" namespace. Then the service - element actually defines the service for us. If you remember from the architecture - overview, a service is a targeted chain, which means it may have any/all - of: a request Handler, a pivot Handler (which for a service is called a "provider"), - and a response Handler. In this case, our provider is "java:RPC", - which is predefined to indicate a Java RPC service.

-

We need to tell the RPCDispatcher that it should instantiate and call the correct - class (e.g. samples.userguide.example3.MyService), and we do so by including - a <parameter> tag, giving the service one parameter to configure the class - name, and another to tell the engine that any public method on that class may - be called via SOAP (that's what the "*" means; we could also have restricted - the SOAP-accessible methods by using a space or comma separated list of available - method names).

-

Using the AdminClient

-

Once we have this file, we need to send it to an Axis server in order to actually - deploy the described service. We do this with the AdminClient, or the "org.apache.axis.client.AdminClient" - class. An invocation of the AdminClient looks like this:

+Pretty simple, really - the outermost element tells the engine that this +is a WSDD deployment, and defines the "java" namespace. Then the service +element actually defines the service for us. If you remember from the architecture +overview, a service is a targeted chain, which means it may have +any/all of: a request Handler, a pivot Handler (which for a service is +called a "provider"), and a response Handler. In this case, our provider +is "java:RPC", which is predefined to indicate a Java RPC service. +

We need to tell the RPCDispatcher that it should instantiate and call +the correct class (e.g. samples.userguide.example3.MyService), and we do +so by including a <parameter> tag, giving the service one parameter +to configure the class name, and another to tell the engine that any public +method on that class may be called via SOAP (that's what the "*" means; +we could also have restricted the SOAP-accessible methods by using a space +or comma separated list of available method names). +

+Using the AdminClient

+Once we have this file, we need to send it to an Axis server in order to +actually deploy the described service. We do this with the AdminClient, +or the "org.apache.axis.client.AdminClient" class. An invocation of the +AdminClient looks like this:
% java org.apache.axis.client.AdminClient deploy.wsdd
  -<Admin>Done processing</Admin>
-

This command has now made our service accessible via -SOAP. Check it out by running the Client class - it should look like this:

% java samples.userguide.example3.Client "test me!"
You typed : test me!
%
-

If you want to prove to yourself that the deployment really worked, try undeploying - the service and calling it again.  There's an "undeploy.wsdd" file in the - example3/ directory which you can use just as you did the deploy.wsdd file above.  - Run the AdminClient on that file, then try the service Client again and see - what happens.

-

You can also use the AdminClient to get a listing of all the deployed -components in the server:

% java org.apache.axis.client.AdminClient list
<big XML document returned here>
-

In there you'll see services, handlers, transports, etc. Note that this listing - is an exact copy of the server's "server-config.wsdd" file, which - we'll talk about in more detail a little later.

-

More deployment - Handlers and Chains

-

Now let's start to explore some of the more powerful features of the Axis engine. - Let's say you want to track how many times your service has been called. We've - included a sample handler in the samples/log directory to do just this. To use - a handler class like this, you first need to deploy the Handler itself, and - then use the name that you give it in deploying a service. Here's a sample deploy.wsdd - file (this is example 4in samples/userguide):

-
<deployment xmlns="http://xml.apache.org/axis/wsdd/"
  -            xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
  - 
  - <!-- define the logging handler configuration -->
  - <handler name="track" type="java:samples.userguide.example4.LogHandler">
  -  <parameter name="filename" value="MyService.log"/>
  - </handler>
  -
  - <!-- define the service, using the log handler we just defined -->
  - <service name="LogTestService" provider="java:RPC">
  -  <requestFlow>
  -   <handler type="track"/>
  -  </requestFlow>
  -
  -  <parameter name="className" value="samples.userguide.example4.Service"/>
  -  <parameter name="methodName" value="*"/>
  - </service>
  -</deployment>
-

The first section defines a Handler called "track" that is implemented by the - class samples.userguide.example4.LogHandler. We give this Handler an option to let it know - which file to write its messages into.

-

Then we define a service, LogTestService, which is an RPC service just like we saw - above in our first example. The difference is the <requestFlow> element - inside the <service> - this indicates a set of Handlers that should be - invoked when the service is invoked, before the provider. By inserting a reference - to "track", we ensure that the message will be logged each time this service - is invoked.
-

-

Remote Administration

-

Note that by default, the Axis server is configured to only accept administration - requests from the machine on which it resides - if you wish to enable remote - administration, you must set the "enableRemoteAdmin" property of the AdminService - to true. To do this, find the "server-config.wsdd" file in your webapp's - WEB-INF directory. In it, you'll see a deployment for the AdminService. Add - an option as follows:

-
<service name="AdminService" provider="java:MSG">
  - <parameter name="className" value="org.apache.axis.util.Admin"/>
  - <parameter name="methodName" value="*"/>
  - <parameter name="enableRemoteAdmin" value="true"/>
  -</service>
-

WARNING: enabling remote administration may give unauthorized parties access - to your machine. If you do this, please make sure to add security to your configuration!
-

-

XML <-> Java Data Mapping in Axis

-

Encoding Your Beans - the BeanSerializer

-

Axis includes the ability to serialize/deserialize, without writing any code, - arbitrary Java classes which follow the standard JavaBean pattern of get/set - accessors. All you need to do is tell Axis which Java classes map to which XML - Schema types. Configuring a bean mapping looks like this:

-
<beanMapping qname="ns:local" xmlns:ns="someNamespace"
  -             languageSpecificType="java:my.java.thingy"/>
  -
-

The <beanMapping> tag maps a Java class (presumably a bean) to an XML - QName. You'll note that it has two important attributes, qname and languageSpecificType. - So in this case, we'd be mapping the "my.java.thingy" class to the XML QName - [someNamespace]:[local].

-

Let's take a look at how this works in practice. Go look at the samples/userguide/example5/BeanService.java - file. (we won't reproduce it here, it's pretty straightforward) The key thing - to notice is that the argument to the service method is an Order object. Since - Order is not a basic type which Axis understands by default, trying to run this - service without a type mapping will result in a fault (if you want to try this - for yourself, you can use the bad-deploy.wsdd file in the example5 directory). - But if we put a beanMapping into our deployment, all will be well. Here's how - to run this example (from the example5 directory):

+<Admin>Done processing</Admin> +This command has now made our service accessible via SOAP. Check it out +by running the Client class - it should look like this: +
% java samples.userguide.example3.Client "test me!"
  +You typed : test me!
  +%
+If you want to prove to yourself that the deployment really worked, try +undeploying the service and calling it again.  There's an "undeploy.wsdd" +file in the example3/ directory which you can use just as you did the deploy.wsdd +file above.  Run the AdminClient on that file, then try the service +Client again and see what happens. +

You can also use the AdminClient to get a listing of all the deployed +components in the server: +

% java org.apache.axis.client.AdminClient list
  +<big XML document returned here>
+In there you'll see services, handlers, transports, etc. Note that this +listing is an exact copy of the server's "server-config.wsdd" file, which +we'll talk about in more detail a little later. +

+More deployment - Handlers and Chains

+Now let's start to explore some of the more powerful features of the Axis +engine. Let's say you want to track how many times your service has been +called. We've included a sample handler in the samples/log directory to +do just this. To use a handler class like this, you first need to deploy +the Handler itself, and then use the name that you give it in deploying +a service. Here's a sample deploy.wsdd file (this is example 4in samples/userguide): +
<deployment xmlns="http://xml.apache.org/axis/wsdd/"
  +            xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
  + 
  + <!-- define the logging handler configuration -->
  + <handler name="track" type="java:samples.userguide.example4.LogHandler">
  +  <parameter name="filename" value="MyService.log"/>
  + </handler>
  +
  + <!-- define the service, using the log handler we just defined -->
  + <service name="LogTestService" provider="java:RPC">
  +  <requestFlow>
  +   <handler type="track"/>
  +  </requestFlow>
  +
  +  <parameter name="className" value="samples.userguide.example4.Service"/>
  +  <parameter name="methodName" value="*"/>
  + </service>
  +</deployment>
+The first section defines a Handler called "track" that is implemented +by the class samples.userguide.example4.LogHandler. We give this Handler +an option to let it know which file to write its messages into. +

Then we define a service, LogTestService, which is an RPC service just +like we saw above in our first example. The difference is the <requestFlow> +element inside the <service> - this indicates a set of Handlers that +should be invoked when the service is invoked, before the provider. By +inserting a reference to "track", we ensure that the message will be logged +each time this service is invoked. +

+Remote Administration

+Note that by default, the Axis server is configured to only accept administration +requests from the machine on which it resides - if you wish to enable remote +administration, you must set the "enableRemoteAdmin" property of the AdminService +to true. To do this, find the "server-config.wsdd" file in your +webapp's WEB-INF directory. In it, you'll see a deployment for the AdminService. +Add an option as follows: +
<service name="AdminService" provider="java:MSG">
  + <parameter name="className" value="org.apache.axis.util.Admin"/>
  + <parameter name="methodName" value="*"/>
  + <parameter name="enableRemoteAdmin" value="true"/>
  +</service>
+WARNING: enabling remote administration may give unauthorized parties +access to your machine. If you do this, please make sure to add security +to your configuration! +

+XML <-> Java Data Mapping in Axis

+ +

+Encoding Your Beans - the BeanSerializer

+Axis includes the ability to serialize/deserialize, without writing any +code, arbitrary Java classes which follow the standard JavaBean pattern +of get/set accessors. All you need to do is tell Axis which Java classes +map to which XML Schema types. Configuring a bean mapping looks like this: +
<beanMapping qname="ns:local" xmlns:ns="someNamespace"
  +             languageSpecificType="java:my.java.thingy"/>
+The <beanMapping> tag maps a Java class (presumably a bean) to an XML +QName. You'll note that it has two important attributes, qname and +languageSpecificType. +So in this case, we'd be mapping the "my.java.thingy" class to the XML +QName [someNamespace]:[local]. +

Let's take a look at how this works in practice. Go look at the samples/userguide/example5/BeanService.java +file. (we won't reproduce it here, it's pretty straightforward) The key +thing to notice is that the argument to the service method is an Order +object. Since Order is not a basic type which Axis understands by default, +trying to run this service without a type mapping will result in a fault +(if you want to try this for yourself, you can use the bad-deploy.wsdd +file in the example5 directory). But if we put a beanMapping into our deployment, +all will be well. Here's how to run this example (from the example5 directory):

% java org.apache.axis.client.AdminClient -llocal:///AdminService deploy.wsdd
  -<Admin>Done processing</Admin>
  +<Admin>Done processing</Admin>
   
   % java Client -llocal:// -n "Glen"
   Hi, Glen!
  @@ -439,163 +535,196 @@
   4 of item : 1600mahBattery
   
   If this had been a real order processing system, we'd probably have charged you about now.
  -%
+% +
-

When Beans Are Not Enough - Custom Serialization

-

Just as JWS deployment is sometimes not flexible enough to meet all needs, - the default bean serialization model isn't robust enough to handle every case - either. At times there will be non-bean Java classes (especially in the case - of pre-existing assets) which you need to map to/from XML, and there also may - be some custom XML schema types which you want to map into Java in particular - ways. Axis gives you the ability to write custom serializers/deserializers, - and some tools to help make your life easier when you do so.

-

TBD - this section will be expanded in a future version! - For now, take a look at the ArraySerializer, the BeanSerializer (both in org.apache.axis.encoding), - and the DataSer example (in samples/encoding) to see how custom serializers - work.

-

Deploying custom mappings - the <typeMapping> tag

-

Now that you've built your serializers and deserializers, you need to tell - Axis which types they should be used for. You do this with a typeMapping tag - in WSDD, which looks like this:

-
<typeMapping qname="ns:local" xmlns:ns="someNamespace"
  -             languageSpecificType="java:my.java.thingy"
  -             serializer="my.java.Serializer"
  -             deserializer="my.java.DeserializerFactory"/>
-

This looks a lot like the <beanMapping> tag we saw earlier, but there - are two extra attributes. One, serializer, is the Java class name of - the Serializer class which should be used to write the specified Java class - (i.e. my.java.thingy) into XML. The other, deserializer, is the class - name of a Deserializer factory that generates Deserializers which can - be used to unmarshall XML into the correct Java class.

-

(the <beanMapping> tag is really just shorthand for a <typeMapping> - tag with serializer="org.apache.axis.encoding.BeanSerializer" and - deserializer="org.apache.axis.encoding.BeanSerializer$BeanSerFactory", - but clearly it can save a lot of typing!)

-

Using WSDL with Axis

-

The Web Service Description Language - is a specification authored by IBM and Microsoft, and supported by many other - organizations. WSDL serves to describe Web Services in a structured way. A WSDL - description of a service tells us, in a machine-understandable way, the interface - to the service, the data types it uses, and where the service is located. Please - see the spec (follow the link in the first sentence) for details about WSDL's - format and options.

-

Axis supports WSDL in two ways: first, when you deploy a service in Axis, users - may then access your service's URL with a standard web browser and by appending - "?WSDL" to the end of the URL, they will obtain an automatically-generated - WSDL document which describes your service. Second, we provide a "Wsdl2java" - tool which will build Java proxies and skeletons for services with WSDL descriptions. - Both of these techniques are explained in more detail below.

-

WSDL generation for deployed services

-

When you make a service available using Axis, there is typically a unique URL - associated with that service. For JWS files, that URL is simply the path to - the JWS file itself. For non-JWS services, this is usually the URL "http://<host>/axis/services/<service-name>".

-

If you access the service URL in a browser, you'll see a message indicating - that the endpoint is an Axis service, and that you should usually access it - using SOAP. However, if you tack on "?wsdl" to the end of the URL, - Axis will automatically generate a service description for the deployed service, - and return it as XML in your browser (try it!). The resulting description may - be saved or used as input to proxy-generation, described next. You can give - the WSDL-generation URL to your online partners, and they'll be able to use - it to access your service with toolkits like .NET, SOAP::Lite, or any other - software which supports using WSDL.

-

Building stubs and skeletons with Wsdl2java

-

You'll find the Axis WSDL -> Java tool in "org.apache.axis.wsdl.Wsdl2java". - The basic invocation form looks like this:

+ +

+When Beans Are Not Enough - Custom Serialization

+Just as JWS deployment is sometimes not flexible enough to meet all needs, +the default bean serialization model isn't robust enough to handle every +case either. At times there will be non-bean Java classes (especially in +the case of pre-existing assets) which you need to map to/from XML, and +there also may be some custom XML schema types which you want to map into +Java in particular ways. Axis gives you the ability to write custom serializers/deserializers, +and some tools to help make your life easier when you do so. +

TBD - this section will be expanded in a future +version! For now, take a look at the ArraySerializer, the BeanSerializer +(both in org.apache.axis.encoding), and the DataSer example (in samples/encoding) +to see how custom serializers work. +

+Deploying custom mappings - the <typeMapping> tag

+Now that you've built your serializers and deserializers, you need to tell +Axis which types they should be used for. You do this with a typeMapping +tag in WSDD, which looks like this: +
<typeMapping qname="ns:local" xmlns:ns="someNamespace"
  +             languageSpecificType="java:my.java.thingy"
  +             serializer="my.java.Serializer"
  +             deserializer="my.java.DeserializerFactory"/>
+This looks a lot like the <beanMapping> tag we saw earlier, but there +are two extra attributes. One, serializer, is the Java class name +of the Serializer class which should be used to write the specified Java +class (i.e. my.java.thingy) into XML. The other, deserializer, is +the class name of a Deserializer factory that generates Deserializers +which can be used to unmarshall XML into the correct Java class. +

(the <beanMapping> tag is really just shorthand for a <typeMapping> +tag with serializer="org.apache.axis.encoding.BeanSerializer" and deserializer="org.apache.axis.encoding.BeanSerializer$BeanSerFactory", +but clearly it can save a lot of typing!) +

+Using WSDL with Axis

+The Web Service Description Language +is a specification authored by IBM and Microsoft, and supported by many +other organizations. WSDL serves to describe Web Services in a structured +way. A WSDL description of a service tells us, in a machine-understandable +way, the interface to the service, the data types it uses, and where the +service is located. Please see the spec (follow the link in the first sentence) +for details about WSDL's format and options. +

Axis supports WSDL in three ways: +

    +
  1. +When you deploy a service in Axis, users may then access your service's +URL with a standard web browser and by appending "?WSDL" to the end of +the URL, they will obtain an automatically-generated WSDL document which +describes your service.
  2. + +
  3. +We provide a "WSDL2Java" tool which will build Java proxies and skeletons +for services with WSDL descriptions.
  4. + +
  5. +We provide a "Java2WSDL" tool which will build WSDL from Java classes.
  6. +
+ +

+?WSDL: Obtaining +WSDL for deployed services

+When you make a service available using Axis, there is typically a unique +URL associated with that service. For JWS files, that URL is simply the +path to the JWS file itself. For non-JWS services, this is usually the +URL "http://<host>/axis/services/<service-name>". +

If you access the service URL in a browser, you'll see a message indicating +that the endpoint is an Axis service, and that you should usually access +it using SOAP. However, if you tack on "?wsdl" to the end of the URL, Axis +will automatically generate a service description for the deployed service, +and return it as XML in your browser (try it!). The resulting description +may be saved or used as input to proxy-generation, described next. You +can give the WSDL-generation URL to your online partners, and they'll be +able to use it to access your service with toolkits like .NET, SOAP::Lite, +or any other software which supports using WSDL. +

You can also generate WSDL files from existing Java classes (see #Java2WSDL: +Building WSDL from Java  ). +

+WSDL2Java: +Building stubs, skeletons, and data types from WSDL

+You'll find the Axis WSDL -> Java tool in "org.apache.axis.wsdl.WSDL2Java". +The basic invocation form looks like this:
-
% java org.apache.axis.wsdl.Wsdl2java (url-to-wsdl-file)
  -
+
% java org.apache.axis.wsdl.WSDL2Java (url-to-wsdl-file)
-

Stubs - making Web Service access transparent from the client side

-

A stub is a Java class which has the same interface as a remote Web - Service. It stands in as a proxy (another term for the same idea) for - the remote service, letting you call it exactly as if it were a local object. - In other words, you don't need to deal with the endpoint URL, namespace, or - parameter arrays which are involved in dynamic invocation via the Service - and Call objects. - The stub hides all that work for you.

-

You can try an example, assuming you've deployed the service in example - 3 above and have your Axis server up and running. Type the following at - the command line:

-
% java org.apache.axis.wsdl.Wsdl2java http://localhost:8080/axis/services/MyService?wsdl
-

You can add the "--verbose" option right before the URL if you want - some more feedback on what the tool is up to. This will generate stub code, - which we'll describe.

-

Wsdl2java generates a few classes; here's a rundown of what they are and how - to use them:

+ +

+Stubs - making Web Service access transparent from the client side

+A stub is a Java class which has the same interface as a remote +Web Service. It stands in as a proxy (another term for the same +idea) for the remote service, letting you call it exactly as if it were +a local object. In other words, you don't need to deal with the endpoint +URL, namespace, or parameter arrays which are involved in dynamic invocation +via the Service and Call objects. The stub hides all that work for you. +

You can try an example, assuming you've deployed the service in example +3 above and have your Axis server up and running. Type the following +at the command line: +

% java org.apache.axis.wsdl.WSDL2Java http://localhost:8080/axis/services/MyService?wsdl
+You can add the "--verbose" option right before the URL if you want some +more feedback on what the tool is up to. This will generate stub code, +which we'll describe. +

WSDL2Java generates a few classes; here's a rundown of what they are +and how to use them:

-

So a typical usage of the stub classes would be as follows:

+So a typical usage of the stub classes would be as follows:
public class Tester {
  -  public static void main(String [] args) throws Exception
  -  {
  -    // Make a service (PortType factory)
  -    MyService service = new MyService();
  -
  -
  -    // Now use the service to get a PortType that we can call.
  -    MyServicePortType port = service.getMyServicePort();
  - 
  -    // Make the actual call
  -    String ret = port.serviceMethod("test string");
  -    System.out.println("Return val was " + ret);
  -  }
  -} 
-

Skeletons - frameworks for implementing Web Services

-

Just as a stub is the client side of a Web Service represented in Java, a skeleton - is a Java framework for the server side. You'd want to make a skeleton if you - had a WSDL description of a service which you'd like to implement. For instance, - you might want to join a digital marketplace which requires you to make your - inventory available via a particular Web Service interface.

-

To make skeleton classes, you just specify the "--skeleton" option - to Wsdl2java. For instance, if we wanted to replicate the service in the last - example, we'd type:

-
% java org.apache.axis.wsdl.Wsdl2java --skeleton http://localhost:8080/axis/services/MyService?wsdl
-

There are a couple of classes produced by the skeleton generator, so let's - take a look at them:

+  public static void main(String [] args) throws Exception +  { +    // Make a service (PortType factory) +    MyService service = new MyService(); + + +    // Now use the service to get a PortType that we can call. +    MyServicePortType port = service.getMyServicePort(); +  +    // Make the actual call +    String ret = port.serviceMethod("test string"); +    System.out.println("Return val was " + ret); +  } +} + +

+Skeletons - frameworks for implementing Web Services

+Just as a stub is the client side of a Web Service represented in Java, +a skeleton is a Java framework for the server side. You'd want to +make a skeleton if you had a WSDL description of a service which you'd +like to implement. For instance, you might want to join a digital marketplace +which requires you to make your inventory available via a particular Web +Service interface. +

To make skeleton classes, you just specify the "--skeleton" option to +WSDL2Java. For instance, if we wanted to replicate the service in the last +example, we'd type: +

% java org.apache.axis.wsdl.WSDL2Java --skeleton http://localhost:8080/axis/services/MyService?wsdl
+There are a couple of classes produced by the skeleton generator, so let's +take a look at them: -The tool also builds you a "deploy.wsdd" and an "undeploy.wsdd" -for use with the AdminClient. These files may be used to deploy the service once -you've filled in the methods of the Implementation class, compiled the code, and -made the classes available to your Axis engine. -

Data Types for Stubs and Skeletons

-

-

WSDL files can contain (or reference) XML Schema describing the data types - used by particular operations. As we've seen, Axis needs to do some work to - map schema types to Java types, and this remains true whether we code the Java - by hand or generate it with a tool. When you use Wsdl2java to generate either - stubs or skeletons for operations which contain complex types, you will notice - that Java classes corresponding to the XML data types are also generated. For - the stub, the code inside the stub handles setting up the type mapping in Axis - - and for the skeleton, the type mappings are included in the generated "deploy.wsdd" - file.

-
Holders
-

You'll notice that for each data class that Wsdl2java generates, there is a - corresponding "Holder" class - for instance a class called "MyDataType" - would also get a companion class "MyDataTypeHolder". These classes - exist so that we have a reasonably clean mapping for WSDL's in/out and out parameters - in Java. See the examples for more details.

-

Wsdl2java details

+The tool also builds you a "deploy.wsdd" and an "undeploy.wsdd" for use +with the AdminClient. These files may be used to deploy the service once +you've filled in the methods of the Implementation class, compiled the +code, and made the classes available to your Axis engine. +

+Data Types for Stubs and Skeletons

+WSDL files can contain (or reference) XML Schema describing the data types +used by particular operations. As we've seen, Axis needs to do some work +to map schema types to Java types, and this remains true whether we code +the Java by hand or generate it with a tool. When you use WSDL2Java to +generate either stubs or skeletons for operations which contain complex +types, you will notice that Java classes corresponding to the XML data +types are also generated. For the stub, the code inside the stub handles +setting up the type mapping in Axis - and for the skeleton, the type mappings +are included in the generated "deploy.wsdd" file. +
+Holders
+You'll notice that for each data class that Wsdl2java generates, there +is a corresponding "Holder" class - for instance a class called "MyDataType" +would also get a companion class "MyDataTypeHolder". These classes exist +so that we have a reasonably clean mapping for WSDL's in/out and out parameters +in Java. See the examples for more details. +

+Wsdl2java details

Wsdl2java has a number of options, some of which have already been detailed.

Usage:  java org.apache.axis.wsdl.Wsdl2java [options] WSDL-URI
Options: @@ -613,18 +742,17 @@ emit a MessageContext parameter to skeleton methods
        -N, --NStoPkg <argument>=<value>
                -mapping of namespace to package -        -p, --package <argument>
-                -override all namespace to package mappings, use this package name instead
-
        -o, --output <argument> +mapping of namespace to package         +-p, --package <argument>
                +override all namespace to package mappings, use this package name instead +

        -o, --output <argument> +
                output directory for emitted files
        -d, --deployScope <argument> -
-                 - add scope to deploy.wsdd: "Application", "Request", "Session"
-         -t, --testCase +
                +add scope to deploy.wsdd: "Application", "Request", "Session" +
        -t, --testCase
                emit junit testcase class for web service
        -n, --noImports @@ -668,20 +796,21 @@

If an entry for a given mapping exists both on the command line and in the properties file, the command line entry takes precedence.

--p, --package <argument>
-This is a shorthand option to map all namespaces in a WSDL document to the -same Java package name.  This can be useful, but dangerous.  You -must make sure that you understand the effects of doing this.  For instance -there may be multiple types with the same name in different namespaces.  It -is an error to use the --NStoPkg switch and --package at the same time.
+-p, --package <argument> +This is a shorthand option to map all namespaces in a WSDL document to +the same Java package name.  This can be useful, but dangerous.  +You must make sure that you understand the effects of doing this.  +For instance there may be multiple types with the same name in different +namespaces.  It is an error to use the --NStoPkg switch and --package +at the same time.
-o, --output <argument>
The root directory for all emitted files.
-d, --deployScope <argument>
-Add scope to deploy.wsdd: "Application", "Request", or "Session".  If this -option does not appear, no scope tag appears in deploy.wsdd, which the AXIS runtime -defaults to "Request". +Add scope to deploy.wsdd: "Application", "Request", or "Session".  +If this option does not appear, no scope tag appears in deploy.wsdd, which +the AXIS runtime defaults to "Request".
-t, --testCase
Generate a client-side JUnit test case. @@ -690,49 +819,296 @@ Only generate code for the WSDL document that appears on the command line.  The default behaviour is to generate files for all WSDL documents, the immediate one and all imported ones. +

+Java2WSDL: Building WSDL +from Java

+The Java2WSDL and WSDL2Java emitters make it easy to develop a new web +service. +
The following sections describe the steps in building a web service +from a Java interface. +
  +

+Step 1: Provide a Java interface

+Write and compile a Java interface that describes the web service interface.  +Here is an example interface that describes a web services that can be +used to set/query the price of widgets ( ../samples/userguide/example6/WidgetPrice.java +): +

package samples.userguide.example6; +

/** +
 * Interface describing a web service +to set and get Widget prices. +
 **/ +
public interface WidgetPrice +
{ +
    public void setWidgetPrice(String +widgetName, String price); +
    public String getWidgetPrice(String +widgetName); +
} +
  +

+Step 2: Create WSDL using Java2WSDL

+Use the Java2WSDL tool to create a WSDL file from the interface above. +

Here is an example invocation that produces the wsdl file (wp.wsdl) +from the interface described in the previous section: +

java org.apache.axis.wsdlgen.Java2WSDL -o +wp.wsdl -l"http://localhost:8080/axis/services/WidgetPrice" -n "urn:Example6" +-p"samples.userguide.example6" "urn:Example6"  samples.userguide.example6.WidgetPrice +

Where: +

+The output wsld document will contain the appropriate wsdl types, messages, +portType, bindings and service descriptions to support a SOAP rpc, encoding +web service.  If your specified interface methods reference other +classes, the Java2WSDL tool will generate the appropriate xml types to +represent the classes and any nested/inherited types.  The tool supports +JAX-RPC complex types (bean classes), extension classes, enumeration classes, +arrays and Holder classes. +

The Java2WSDL tool has many additional options which are detailed in +the next section. +

+Java2WSDL Details
+Here is the help message generated from the current tool: +

Usage: java org.apache.axis.wsdlgen.Java2WSDL +[options] class-of-portType +
Options: +
        +-h, --help +
                +print this message and exit +
        +-o, --output <argument> +
                +output Wsdl filename +
        +-l, --location <argument> +
                +service location url +
        +-s, --service <argument> +
                +service name (obtained from --location if not specified) +
        +-n, --namespace <argument> +
                +target namespace +
        +-p, --PkgtoNS <argument>=<value> +
                +package=namespace, name value pairs +
        +-m, --methods <argument> +
                +space separated list of methods to export +
        +-a, --all +
                +look for allowed methods in inherited class +
        +-w, --outputWsdlMode <argument> +
                +output WSDL mode: All, Interface, Implementation +
        +-L, --locationImport <argument> +
                +location of interface wsdl +
        +-N, --namespaceImpl <argument> +
                +target namespace for implementation wsdl +
        +-O, --outputImpl <argument> +
                +output Implementation Wsdl filename, setting this causes --o +
                +utputWsdlMode to be ignored +
Details: +
        +portType    name= <class-of-portType name> +
        +binding     name= <--service value>SoapBinding +
        +service     name= <--service value>Service +
        +port        name= <--service value> +
        +address location= <--location value> +

-h , --help +
Prints the help message. +

-o, --output <wsdl file> +
Indicates the name of the output wsdl file.  If not specified, +a suitable default wsdl file is written into the current directory. +

-l, --location <location> +
Indicates the url of the location of the service.  The name after +the last slash or backslash is the name of the service port (unless overriden +by the -s option).  The service port address location attributed is +assigned the specified value. +

-s, -service <name> +
Indicates the name of the service.  If not specified, the service +name is derived from the --location value.  The names of the wsdl +binding, service, and port elements are derived from the service name as +indicated in the Details section +above. +

-n, --namespace <target namespace> +
Indicates the name of the target namespace of the wsdl. +

-p, --PkgToNS <package> <namespace> +
Indicates the mapping of a package to a namespace.  If a package +is encountered that does not have a namespace, the Java2WSDL emitter will +generate a suitable namespace name.  This option may be specified +multiple times. +

-m, --methods <arguments> +
If this option is specified, only the indicated methods in your interface +class will be exported into the wsdl file.  The methods list must +be comma separated.  If not specified, all methods declared in the +interface class will be exported into the wsdl file. +

-a, --all +
If this option is specified, the Java2WSDL parser will look into extended +classes to determine the list of methods to export into the wsdl file. +

-w, --outputWSDLMode <mode> +
Indicates the kind of wsdl to generate.  Accepted values are: +

+-L, --locationImport <url> +
Used to indicate the location of the interface wsdl when generating +an implementation wsdl. +

-N, --namespaceImpl <namespace> +
Namespace of the implementation wsdl. +

-O, --outputImpl <wsdl file> +
Use this option to indicate the name of the output implementation wsdl +file.  If specified, Java2WSDL will produce interface and implementation +wsdl files.  If this option is used, the -w option is ignored. +
  +

+Step 3: Create Bindings using WSDL2Java

+Use the generated wsdl file to build the appropriate client/server bindings +for the web service (see WSDL2Java): +

 java org.apache.axis.wsdl.Wsdl2java +-o . -d session -s -Nurn:Example6 samples.userguide.example6 ws.wsdl +

This will generate the following files: +

+Now you have all of the necessary files to build your client/server side +code and deploy the web service! +

+Using the Axis TCP Monitor (tcpmon)

+The included "tcpmon" utility can be found in the org.apache.axis.utils +package. To run it from the command line:
% java org.apache.axis.utils.tcpmon [listenPort targetHost targetPort]
-

Without any of the optional arguments, you will get a gui which looks like this:

-

-

To use the program, you should select a local port which tcpmon - will monitor for incoming connections, a target host where it will forward such - connections, and the port number on the target machine which should be "tunneled" - to. Then click "add". You should then notice another tab appearing - in the window for your new tunneled connection. Looking at that panel, you'll - see something like this:

-

-

Now each time a SOAP connection is made to the local port, you - will see the request appear in the "Request" panel, and the response - from the server in the "Response" panel. Tcpmon keeps a log of all - request/response pairs, and allows you to view any particular pair by selecting - an entry in the top panel. You may also remove selected entries, or all of them, - or choose to save to a file for later viewing.

-

The "resend" button will resend the request you are - currently viewing, and record a new response. This is particularly handy in - that you can edit the XML in the request window before resending - so you can - use this as a great tool for testing the effects of different XML on SOAP servers.

+Without any of the optional arguments, you will get a gui which looks like +this: +
+

+ +

To use the program, you should select a local port which tcpmon will +monitor for incoming connections, a target host where it will forward such +connections, and the port number on the target machine which should be +"tunneled" to. Then click "add". You should then notice another tab appearing +in the window for your new tunneled connection. Looking at that panel, +you'll see something like this: +

+

+ +

Now each time a SOAP connection is made to the local port, you will +see the request appear in the "Request" panel, and the response from the +server in the "Response" panel. Tcpmon keeps a log of all request/response +pairs, and allows you to view any particular pair by selecting an entry +in the top panel. You may also remove selected entries, or all of them, +or choose to save to a file for later viewing. +

The "resend" button will resend the request you are currently viewing, +and record a new response. This is particularly handy in that you can edit +the XML in the request window before resending - so you can use this as +a great tool for testing the effects of different XML on SOAP servers.

-
+
+
-

Glossary

-
-
Handler -
<definition> -
-
SOAP -
The Simple Object Access Protocol (yes, despite the fact that it sometimes - doesn't seem so simple, and doesn't have anything to do with objects... :)). - You can read the SOAP 1.1 specification at http://www.w3.org/TR/SOAP. - The W3C is currently in the midst of work on SOAP 1.2, under the auspices - of the XML Protocol Group. -
-
Provider -
<definition> -
-
+ +

+Glossary

+ +
+
+Handler
+ +
+<definition>
+ +
+SOAP
+ +
+The Simple Object Access Protocol (yes, despite the fact that it sometimes +doesn't seem so simple, and doesn't have anything to do with objects... +:)). You can read the SOAP 1.1 specification at http://www.w3.org/TR/SOAP. +The W3C is currently in the midst of work on SOAP 1.2, under the auspices +of the XML Protocol Group.
+ +
+Provider
+ +
+<definition>
+ +
+
+