You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by gd...@apache.org on 2001/08/06 21:43:33 UTC
cvs commit: xml-axis/java/docs tcpmon1.jpg tcpmon2.jpg user-guide.html
gdaniels 01/08/06 12:43:33
Modified: java/docs user-guide.html
Added: java/docs tcpmon1.jpg tcpmon2.jpg
Log:
More mods
Revision Changes Path
1.6 +85 -43 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.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- user-guide.html 2001/08/03 21:10:44 1.5
+++ user-guide.html 2001/08/06 19:43:33 1.6
@@ -68,7 +68,15 @@
"<A href="mailto:axis-dev@xml.apache.org">axis-dev@xml.apache.org</a>"
</p>
<h3>What is SOAP?</h3>
-SOAP is an XML <i></i>
+<p>SOAP is an XML<i>-</i>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, <a href="http://w3.org/TR/soap">SOAP
+ 1.1</a>, 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.</p>
+<p>SOAP is widely viewed as the backbone to a new generation of cross-platform
+ cross-language distributed computing applications, termed Web Services.</p>
<h3>What's in this release?</h3>
<p>This release contains:</p>
<ul>
@@ -91,14 +99,19 @@
</ul>
<h3>What's missing?</h3>
<ul>
- <li>Nuttin.
- <li>Well, OK, sumpin.</li>
+ <li>Support for the SOAP with Attachments specification
+ <li>Supprt for multi-dimensional and "sparse" arrays
+ <li>A final deployment descriptor syntax (WSDD)</li>
+ <li>...</li>
</ul>
-<h2><a name="Installation"></a>Installing Axis</h2>
-See the <a href="file:///E|/Documents/Axis/install.html">Axis Installation Guide</a> for instructions on
-installing Axis.
+<h2><a name="Installation"></a>Installing Axis and Using this Guide</h2>
+<p>See the <a href="install.html">Axis Installation Guide</a> for instructions
+ on installing Axis as a webapp on your J2EE server. </p>
+<p>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.</p>
<h2><a name="Architecture"></a>Axis Architecture - a Brief Primer</h2>
-<p>(This section may be skipped if you want to dive right in)</p>
+<p>(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.)</p>
<p><i><font color="#ff0000">TBD - explanation of Axis architecture, Handlers,
Chains, Services... How transports and global chains work, our deployment architecture,
etc...</font></i> </p>
@@ -122,10 +135,9 @@
13 }
</pre>
</div>
-<p>(You'll find this file in axis/docs/examples/example1/TestClient.java)</p>
-<p>If all goes well, this program can be run as follows, and should output:</p>
-<pre>% javac TestClient.java
-% java TestClient
+<p>(You'll find this file in <a href="../samples/userguide/example1/TestClient.java">samples/userguide/example1/TestClient.java</a>)</p>
+<p>Assuming you have a network connection active, this program can be run as follows:</p>
+<pre>% java samples.userguide.example1.TestClient
Sent 'Hello!', got 'Hello!'
% </pre>
<p>So what's happening here? On line 4, we set up our endpoint URL - this is the
@@ -137,7 +149,7 @@
API takes several arguments - first, the XML namespace of the desired service.
Second, the method name which should be invoked. Finally, we pass an Object
array containing the arguments to the method.</p>
-<p>You can see the effect these arguments have by looking at the SOAP which goes
+<p>You can see what happens to the arguments by looking at the SOAP which goes
out on the wire (look at the colored bits, and notice they match the values
in the call above):</p>
<div class="xml">
@@ -154,20 +166,22 @@
</pre>
<div align="center"> </div>
</div>
-The String argument is automatically serialized into XML, and the server responds
-with an identical String, which we deserialize and print.
+<p>The String argument is automatically serialized into XML, and the server responds
+ with an identical String, which we deserialize and print.</p>
+<p><i>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 <a href="#tcpmon">appendix</a>
+ for an overview.</i></p>
<h3>Naming Parameters</h3>
<p>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:</p>
+ since we only passed the objects themselves, Axis automatically named the XML-encoded
+ 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:</p>
<div class="example"><pre> String ret = (String)client.invoke("http://soapinterop.org",
"echoString",
new Object [] { new RPCParam("testParam", "Hello!") };
</pre></div>
-Now you'll get a message that looks like this:
-
+Now when you run the program you'll get a message that looks like this:
<div class="xml">
<pre><?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;
}
}
</pre>
-<p>(you'll find this file in samples/userguide/example2/Calculator.java)</p>
+<p>(you'll find this very class in <a href="../samples/userguide/example2/Calculator.java">samples/userguide/example2/Calculator.java</a>)</p>
<p>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!</p>
<h3>JWS (Java Web Service) Files - Instant Deployment</h3>
<p>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:</p>
-<pre>% copy Calculator.java JRUN_ROOT/servers/default/axis/Calculator.jws</pre>
+<pre>% copy Calculator.java <i><font color="#0000FF"><your-webapp-root></font></i>/axis/Calculator.jws</pre>
<p>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):</p>
<p><a href="http://localhost/axis/Calculator.jws">http://localhost/axis/Calculator.jws</a>
</p>
<p>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:</p>
+ a calculator client in samples/userguide/example2/CalcClient.java, which you
+ can use like this:</p>
<pre>% 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.</p>
<h4>Deploying via descriptors</h4>
-To really use the flexibility available to you in Axis, you'll want to get familiar with
-the Axis <b>deployment descriptor</b> format (<i>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</i>). 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 <b>deployment descriptor</b> format (<i>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</i>). 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):
<div class="example">
<pre><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:</p>
<pre>% java org.apache.axis.client.AdminClient deploy.xml
-<?xml version="1.0" encoding="UTF-8"?><admin>done processing</admin></pre>
+<admin>done processing</admin></pre>
<p>This command has now made our service accessible via
SOAP. Check it out by running the Client class - it should look like this:</p><PRE>% java samples.userguide.example3.Client "test me!"<BR>You typed : "test me!"<BR>% </PRE>
<P>If you want to prove to yourself that the deployment really worked, try
@@ -320,10 +335,10 @@
<i><font color="#ff0000"></font></i> </p>
<i><font color="#ff0000"></font></i><h2><a name="DataMapping"></a>XML <-> Java Data Mapping in Axis</h2>
<h3>Encoding Your Beans - the BeanSerializer</h3>
-<p>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:</p>
+<p>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:</p>
<pre class="xml"><beanMappings>
<ns:local xmlns:ns="someNamespace" classname="my.java.thingy"/>
</beanMappings></pre>
@@ -431,7 +446,6 @@
<p> </p>
<h2>Pre-Configured Axis Components Reference</h2>
<h3>On the server:</h3>
-<p><b>DebugHandler</b></p>
<dl>
<dt><b>LogHandler</b>
<dd>The LogHandler will simply log a message to a logger
@@ -457,13 +471,41 @@
</dl>
<h3>On the client:</h3>
<dl>
- <dt>HTTPSender
- <dd><definition>
- <dt>
- <dt>LocalSender
- <dd><definition>
+ <dt><b>HTTPSender</b>
+ <dd>A Handler which sends the request message to a remote server via HTTP, and
+ collects the response message.
+ <dt>
+ <dt><b>LocalSender</b>
+ <dd>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:<br>
+ <pre>% java org.apache.axis.client.AdminClient -llocal:// list</pre>
<dt></dt>
</dl>
+<a name="tcpmon"></a><h2>Using the Axis TCP Monitor (tcpmon) </h2>
+<p>The included "tcpmon" utility can be found in the org.apache.axis.utils
+ package. To run it from the command line:</p>
+<pre>% java org.apache.axis.utils.tcpmon</pre>
+<p>This will pop up a gui which looks like this:</p>
+<p align="center"><img src="tcpmon1.jpg" width="599" height="599"></p>
+<p align="left">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:</p>
+<p align="center"><img src="tcpmon2.jpg" width="599" height="600"></p>
+<p align="left">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.</p>
+<p align="left">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.</p>
<dl>
<dt> </dt>
</dl>
1.1 xml-axis/java/docs/tcpmon1.jpg
<<Binary file>>
1.1 xml-axis/java/docs/tcpmon2.jpg
<<Binary file>>