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's in this release?

What's missing?

Installing Axis

Installing Axis and Using this Guide

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

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

Axis Architecture - a Brief Primer

(This section may be skipped if you want to dive right in - in many cases using + the basic features of Axis requires zero knowledge of these topics.)

TBD - explanation of Axis architecture, Handlers, Chains, Services... How transports and global chains work, our deployment architecture, etc...

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 same order we sent them, but - since we only passed the objects themselves, Axis automatically named the arguments - in the SOAP messsage "arg0", "arg1", etc. If you want to - change this, it's easy! Instead of passing the actual Object value of your argument - in the arguments array, simply wrap the argument in an RPCParam class like so:

<?xml version="1.0" encoding="UTF-8"?>
   <SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  @@ -191,29 +205,29 @@
     {
       return i1 + i2; 
     }
  -
  -
  +  
     public int subtract(int i1, int i2)
     {
       return i1 - i2;
     }
   }

(you'll find this file in samples/userguide/example2/Calculator.java)

(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 JRUN_ROOT/servers/default/axis/Calculator.jws

% 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 you've mapped the axis webapp to port 80):

http://localhost/axis/Calculator.jws

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

+ a calculator client in samples/userguide/example2/CalcClient.java, which you + can use like this:

% javac CalcClient.java % java CalcClient add 2 5 Got result : 7 @@ -228,13 +242,14 @@ 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'll want to get familiar with -the Axis deployment descriptor format (note: this format is just for the alpha release. -Axis plans to move to using WSDD (Web Service Deployment Descriptor), a much more robust syntax, -in the next release). 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.xml): - +To really use the flexibility available to you in Axis, you'll want to get familiar +with the Axis deployment descriptor format (note: this particular XML +format is just for the alpha release. Axis plans to move to using WSDD (Web Service +Deployment Descriptor), a much more robust syntax, in the next release). 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.xml):

<admin:deploy xmlns:admin="AdminService">
    <service name="MyService" pivot="RPCDispatcher">
  @@ -264,7 +279,7 @@
     "org.apache.axis.client.AdminClient" class. An invocation of the AdminClient 
     looks like this:
   % java org.apache.axis.client.AdminClient deploy.xml
  -<?xml version="1.0" encoding="UTF-8"?><admin>done processing</admin>
  +<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 @@ -320,10 +335,10 @@

XML <-> Java Data Mapping in Axis

Encoding Your Beans - the BeanSerializer

Axis includes the ability to serialize 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:

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:

<beanMappings>
    <ns:local xmlns:ns="someNamespace" classname="my.java.thingy"/>
   </beanMappings>

@@ -431,7 +446,6 @@

Pre-Configured Axis Components Reference

On the server:

DebugHandler

LogHandler: The LogHandler will simply log a message to a logger @@ -457,13 +471,41 @@

On the client:

HTTPSender -

<definition> -

-

LocalSender -

<definition> +

HTTPSender +

A Handler which sends the request message to a remote server via HTTP, and + collects the response message. +

+

LocalSender +

A Handler which sends the request message to a "local" AxisServer, + which will process it and return a response message. This is extremely useful + for testing, and is by default mapped to the "local:" transport. + So, for instance, you can test the AdminClient by doing something like this:
+

% java org.apache.axis.client.AdminClient -llocal:// list

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

This will pop up 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.

1.1 xml-axis/java/docs/tcpmon1.jpg <> 1.1 xml-axis/java/docs/tcpmon2.jpg <>

What is SOAP?