You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-commits@axis.apache.org by ve...@apache.org on 2012/01/10 23:00:08 UTC
svn commit: r1229756 - in /axis/axis1/java/trunk: docs/images/tcpmon1.jpg
docs/images/tcpmon2.jpg docs/user-guide.html
src/site/resources/images/tcpmon1.jpg src/site/resources/images/tcpmon2.jpg
src/site/xdoc/user-guide.xml
Author: veithen
Date: Tue Jan 10 22:00:07 2012
New Revision: 1229756
URL: http://svn.apache.org/viewvc?rev=1229756&view=rev
Log:
Migrated the user guide to XDoc.
Added:
axis/axis1/java/trunk/src/site/resources/images/tcpmon1.jpg
- copied unchanged from r1229178, axis/axis1/java/trunk/docs/images/tcpmon1.jpg
axis/axis1/java/trunk/src/site/resources/images/tcpmon2.jpg
- copied unchanged from r1229178, axis/axis1/java/trunk/docs/images/tcpmon2.jpg
axis/axis1/java/trunk/src/site/xdoc/user-guide.xml
- copied, changed from r1229638, webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/user-guide.xml
Removed:
axis/axis1/java/trunk/docs/images/tcpmon1.jpg
axis/axis1/java/trunk/docs/images/tcpmon2.jpg
axis/axis1/java/trunk/docs/user-guide.html
Copied: axis/axis1/java/trunk/src/site/xdoc/user-guide.xml (from r1229638, webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/user-guide.xml)
URL: http://svn.apache.org/viewvc/axis/axis1/java/trunk/src/site/xdoc/user-guide.xml?p2=axis/axis1/java/trunk/src/site/xdoc/user-guide.xml&p1=webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/user-guide.xml&r1=1229638&r2=1229756&rev=1229756&view=diff
==============================================================================
--- webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/user-guide.xml (original)
+++ axis/axis1/java/trunk/src/site/xdoc/user-guide.xml Tue Jan 10 22:00:07 2012
@@ -1,90 +1,49 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "./dtd/document-v12.dtd">
-<document>
- <header>
- <title>WebServices - Axis</title>
- </header>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+ <properties>
+ <title>User's Guide</title>
+ </properties>
<body>
-<a name="AxisUsersGuide"/>
-<section>
-<title>Axis User's Guide</title>
-
-<p><i>1.2 Version</i><br/>
- <i>Feedback: <a href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i></p>
-
-<a name="TableOfContents"/>
-<section>
-<title>Table of Contents</title>
+<section name="Table of Contents">
-<ul>
- <li><a href="#Introduction">Introduction</a></li>
- <ul>
- <li><a href="#WhatIsSOAP">What is SOAP?</a></li>
- <li><a href="#WhatIsAxis">What is Axis?</a></li>
- <li><a href="#WhatsInThisRelease">What's in this release?</a></li>
- <li><a href="#WhatsStillToDo">What's still to do?</a></li>
- </ul>
- <li><a href="#InstallingAxisAndUsingThisGuide">Installing Axis and Using this Guide</a></li>
- <li><a href="#ConsumingWebServicesWithAxis">Consuming Web Services with Axis</a></li>
- <ul>
- <li><a href="#BasicsGettingStarted">Basics - Getting Started</a></li>
- <li><a href="#NamingParameters">Naming Parameters</a></li>
- <li><a href="#InteroperatingWithUntypedServers">Interoperating with "untyped" servers</a></li>
- </ul>
- <li><a href="#PublishingWebServicesWithAxis">Publishing Web Services with Axis</a></li>
- <ul>
- <li><a href="#JWSJavaWebServiceFilesInstantDeployment">JWS (Java Web Service) Files - Instant Deployment</a></li>
- <li><a href="#CustomDeploymentIntroducingWSDD">Custom Deployment - Introducing WSDD</a></li>
- <li><a href="#ServiceStylesRPCDocumentWrappedAndMessage">Service Styles - RPC, Document, Wrapped, and Message</a></li>
- </ul>
- <li><a href="#XMLJavaDataMappingInAxis">XML <-> Java Data Mapping in Axis</a></li>
- <ul>
- <li><a href="#HowYourJavaTypesMapToSOAPXMLTypes">How your Java types map to SOAP/XML types</a></li>
- <li><a href="#Exceptions">Exceptions</a></li>
- <li><a href="#WhatAxisCanSendViaSOAPWithRestrictedInteroperability">What Axis can send via SOAP with restricted Interoperability</a></li>
- <li><a href="#WhatAxisCanNotSendViaSOAP">What Axis can not send via SOAP</a></li>
- <li><a href="#EncodingYourBeansTheBeanSerializer">Encoding Your Beans - the BeanSerializer</a></li>
- <li><a href="#WhenBeansAreNotEnoughCustomSerialization">When Beans Are Not Enough - Custom Serialization</a></li>
- </ul>
- <li><a href="#UsingWSDLWithAxis">Using WSDL with Axis</a></li>
- <ul>
- <li><a href="#WSDLObtainingWSDLForDeployedServices">?WSDL: Obtaining WSDL for deployed services</a></li>
- <li><a href="#WSDL2JavaBuildingStubsSkeletonsAndDataTypesFromWSDL">WSDL2Java: Building stubs, skeletons, and data types from WSDL</a></li>
- <li><a href="#Java2WSDLBuildingWSDLFromJava">Java2WSDL: Building WSDL from Java</a></li>
- </ul>
- <li><a href="#PublishedAxisInterfaces">Published Axis Interfaces</a></li>
- <li><a href="#NewbieTipsFindingYourWayAround">Newbie Tips: Finding Your Way Around</a></li>
- <ul>
- <li><a href="#PlacesToLookForClues">Places to Look for Clues</a></li>
- <li><a href="#ClassesToKnow">Classes to Know</a></li>
- </ul>
- <li><a href="#AppendixUsingTheAxisTCPMonitorTcpmon">Appendix : Using the Axis TCP Monitor (tcpmon)</a></li>
- <li><a href="#AppendixUsingTheSOAPMonitor">Appendix: Using the SOAP Monitor</a></li>
- <li><a href="#Glossary">Glossary</a></li>
-</ul>
+<macro name="toc"/>
</section>
-<a name="Introduction"/>
-<section>
-<title>Introduction</title>
+<section name="Introduction">
<p>Welcome to Axis, the third generation of Apache SOAP!</p>
-<a name="WhatIsSOAP"/>
-<section>
-<title>What is SOAP?</title>
+<subsection name="What is SOAP?">
<p>SOAP is an XML-based communication protocol and encoding format for inter-application communication. Originally conceived by Microsoft and Userland software, it has evolved through several generations; the current spec is version, <a href="http://w3.org/TR/soap">SOAP 1.2</a>, though version 1.1 is more widespread. The W3C's <a href="http://www.w3.org/2000/xp/Group/">XML Protocol working group</a> is in charge of the specification. </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>
-</section>
+</subsection>
-<a name="WhatIsAxis"/>
-<section>
-<title>What is Axis?</title>
+<subsection name="What is Axis?">
<p>Axis is essentially a <i>SOAP engine</i> -- a framework for constructing SOAP processors such as clients, servers, gateways, etc. The current version of Axis is written in Java, but a C++ implementation of the client side of Axis is being developed.</p>
@@ -108,7 +67,7 @@
<ul>
<li><b>Speed.</b> Axis uses SAX (event-based) parsing to acheive significantly greater speed than earlier versions of Apache SOAP.</li>
<li><b>Flexibility.</b> The Axis architecture gives the developer complete freedom to insert extensions into the engine for custom header processing, system management, or anything else you can imagine.</li>
- <li><b>Stability.</b> Axis defines a set of <b>published interfaces</b> which change relatively slowly compared to the rest of Axis.</li>
+ <li><b>Stability.</b> Axis defines a set of <a href="#published interfaces">published interfaces</a> which change relatively slowly compared to the rest of Axis.</li>
<li><b>Component-oriented deployment.</b> You can easily define reusable networks of Handlers to implement common patterns of processing for your applications, or to distribute to partners.</li>
<li><b>Transport framework.</b> We have a clean and simple abstraction for designing transports (i.e., senders and listeners for SOAP over various protocols such as SMTP, FTP, message-oriented middleware, etc), and the core of the engine is completely transport-independent.</li>
<li><b>WSDL support.</b> Axis supports the <a href="http://www.w3.org/TR/wsdl">Web Service Description Language</a>, version 1.1, which allows you to easily build stubs to access remote services, and also to automatically export machine-readable descriptions of your deployed services from Axis.</li>
@@ -120,11 +79,9 @@
<p>Please send feedback about the package to "<a href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a>". Also, Axis is registered in <a href="http://issues.apache.org/jira">jira</a>, the Apache bug tracking and feature-request database.</p>
-</section>
+</subsection>
-<a name="WhatsInThisRelease"/>
-<section>
-<title>What's in this release?</title>
+<subsection name="What's in this release?">
<p>This release includes the following features:</p>
@@ -149,21 +106,17 @@
<li>Examples, including a client and server for the SoapBuilders community interoperability tests and experimental TCP, JMS, and file-based transports.</li>
</ul>
-</section>
+</subsection>
-<a name="WhatsStillToDo"/>
-<section>
-<title>What's still to do?</title>
+<subsection name="What's still to do?">
<p>Please click for <a href="to-do.html">a list of what we think needs doing</a> - and please consider helping out if you're interested & able!</p>
-</section>
+</subsection>
</section>
-<a name="InstallingAxisAndUsingThisGuide"/>
-<section>
-<title>Installing Axis and Using this Guide</title>
+<section name="Installing Axis and Using this Guide">
<p>See the <a href="install.html">Axis Installation Guide</a> for instructions on installing Axis as a web application on your J2EE server.</p>
@@ -182,13 +135,9 @@
</section>
-<a name="ConsumingWebServicesWithAxis"/>
-<section>
-<title>Consuming Web Services with Axis</title>
-
-<a name="BasicsGettingStarted"/>
-<section>
-<title>Basics - Getting Started</title>
+<section name="Consuming Web Services with Axis">
+
+<subsection name="Basics - Getting Started">
<p>Let's take a look at an example Web Service client that will call the <b>echoString</b> method on the public Axis server at Apache.</p>
<source>1 import org.apache.axis.client.Call;
@@ -205,9 +154,9 @@
12 Call call = (Call) service.createCall();
13
14 call.setTargetEndpointAddress( new java.net.URL(endpoint) );
-15 call.setOperationName(new QName("http://soapinterop.org/", echoString"));
+15 call.setOperationName(new QName("<font color="#009933">http://soapinterop.org/</font>", "<font color="#993333">echoString</font>"));
16
-17 String ret = (String) call.invoke( new Object[] { "Hello!" } );
+17 String ret = (String) call.invoke( new Object[] { "<font color="#CC00CC">Hello!</font>" } );
18
19 System.out.println("Sent 'Hello!', got '" + ret + "'");
20 } catch (Exception e) {
@@ -233,21 +182,19 @@ Sent 'Hello!', got 'Hello!'
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Body>
- <ns1:<b>echoString</b> xmlns:ns1="<b>http://soapinterop.org/</b>">
- <arg0 xsi:type="xsd:string"><b>Hello!</b></arg0>
+ <ns1:<b><font color="#993333">echoString</font></b> xmlns:ns1="<b><font color="#009933">http://soapinterop.org/</font></b>">
+ <arg0 xsi:type="xsd:string"><b><font color="#CC00CC">Hello!</font></b></arg0>
</ns1:echoString>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope></source>
<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 <a href="user-guide.html#AppendixUsingTheAxisTCPMonitorTcpmon">tcpmon</a> tool or <a href="user-guide.html#AppendixUsingTheSOAPMonitor">SOAP monitor</a> tool. See the appendix for an overview.</i></p>
+<p><i>Note: To actually watch the XML flowing back and forth between a SOAP client and server, you can use the included <a href="#AppendixUsingTheAxisTCPMonitorTcpmon">tcpmon</a> tool or <a href="#AppendixUsingTheSOAPMonitor">SOAP monitor</a> tool. See the appendix for an overview.</i></p>
-</section>
+</subsection>
-<a name="NamingParameters"/>
-<section>
-<title>Naming Parameters</title>
+<subsection name="Naming Parameters">
<p>In the above example, you can see that Axis automatically names the XML-encoded arguments in the SOAP message "arg0", "arg1", etc. (In this case there's just "arg0") If you want to change this, it's easy! Before calling <code>invoke()</code> you need to call <code>addParameter</code> for each parameter and <code>setReturnType</code> for the return, like so:</p>
@@ -265,18 +212,16 @@ call.setReturnType(org.apache.axis.Const
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>
+ <<font color="#CC00CC">testParam</font> xsi:type="xsd:string">Hello!</<font color="#CC00CC">testParam</font>>
</ns1:echoString>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope></source>
<p>Note that the param is now named "testParam" as expected.</p>
-</section>
+</subsection>
-<a name="InteroperatingWithUntypedServers"/>
-<section>
-<title>Interoperating with "untyped" servers</title>
+<subsection name="Interoperating with "untyped" servers">
<p>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 :)).</p>
@@ -288,12 +233,12 @@ call.setReturnType(org.apache.axis.Const
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>
+ <result <font color="#FF0000">xsi:type="xsd:string"</font>>Hello!</result>
</ns1:echoStringResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope></source>
-<p>Take a look at the section which we've highlighted in red - that attribute is a schema <b>type declaration</b>, 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:</p>
+<p>Take a look at the section which we've highlighted in <font color="#FF0000">red</font> - that attribute is a schema <b>type declaration</b>, 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:</p>
<source><?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
@@ -308,23 +253,21 @@ call.setReturnType(org.apache.axis.Const
<p>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 <b>metadata</b> - data about data. In this case, we need a <b>description</b> 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:</p>
-<p><code>call.setReturnType( org.apache.axis.Constants.XSD_STRING );</code></p>
+<source>call.setReturnType( org.apache.axis.Constants.XSD_STRING );</source>
<p>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.)</p>
<p>There is also a similar method which allows you to specify the Java class of the expected return type:</p>
-<p><code>call.setReturnClass(String.class);</code></p>
+<source>call.setReturnClass(String.class);</source>
<p>OK - so now you know the basics of accessing SOAP services as a client. But how do you publish your own services?</p>
-</section>
+</subsection>
</section>
-<a name="PublishingWebServicesWithAxis"/>
-<section>
-<title>Publishing Web Services with Axis</title>
+<section name="Publishing Web Services with Axis">
<p>Let's say we have a simple class like the following:</p>
@@ -342,18 +285,18 @@ call.setReturnType(org.apache.axis.Const
<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>
-<a name="JWSJavaWebServiceFilesInstantDeployment"/>
-<section>
-<title>JWS (Java Web Service) Files - Instant Deployment</title>
+<subsection name="JWS (Java Web Service) Files - Instant Deployment">
<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>
-<source>% copy Calculator.java <i><your-webapp-root></i>/axis/Calculator.jws</source>
+<source>% copy Calculator.java <i><font color="#0000FF"><your-webapp-root></font></i>/Calculator.jws</source>
-<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 your Axis web application is on port 8080):</p>
+<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 your container serves on port 8080 and that your web application is called axis):</p>
<p><a href="http://localhost:8080/axis/Calculator.jws">http://localhost:8080/axis/Calculator.jws</a></p>
+<p>If you followed the link (and the deployment has been successful), you'll see a message information you that there is a Web Service deployed here.</p>
+
<p>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:</p>
<source>% java samples.userguide.example2.CalcClient -p8080 add 2 5
@@ -366,16 +309,13 @@ Got result : 1
<p><i><b>Important:</b></i> JWS web services are intended for simple web services. You cannot use packages in the pages, and as the code is compiled at run time you can not find out about errors until after deployment. Production quality web services should use Java classes with custom deployment.</p>
-</section>
+</subsection>
-<a name="CustomDeploymentIntroducingWSDD"/>
-<section>
-<title>Custom Deployment - Introducing WSDD</title>
+<subsection name="Custom Deployment - Introducing WSDD">
<p>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. <i>(Note for the future : the Axis team, and the Java SOAP community at large, are thinking about ways to be able to embed this sort of metadata into your source files if desired - stay tuned!)</i></p>
-<section>
-<title>Deploying via descriptors</title>
+<h4>Deploying via descriptors</h4>
<p>To really use the flexibility available to you in Axis, you should get familiar with the Axis <b>Web Service Deployment Descriptor (WSDD)</b> 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 <a href="http://cvs.apache.org/viewcvs.cgi/ws-axis/java/samples/userguide/example3/deploy.wsdd?rev=1.2&view=log">samples/userguide/example3/deploy.wsdd</a>):</p>
@@ -392,29 +332,20 @@ case, our provider is "java:RPC", which
<p>We need to tell the RPCProvider that it should instantiate and call the correct class (e.g. samples.userguide.example3.MyService), and we do so by including <parameter> tags, 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).</p>
-</section>
-
-<section>
-<title>Advanced WSDD - specifying more options</title>
+<h5>Advanced WSDD - specifying more options</h5>
<p>WSDD descriptors can also contain other information about services, and also other pieces of Axis called "Handlers" which we'll cover in a later section.</p>
-</section>
+<h5>Scoped Services</h5>
-<section>
-<title>Scoped Services</title>
-
-<p>Axis supports scoping service objects (the actual Java objects which implement your methods) three ways. "Request" scope, the default, will create a new object each time a SOAP request comes in for your service. "Application" scope will create a singleton shared object to service <b>all</b> requests. "Session" scope will create a new object for each session-enabled client who accesses your service. To specify the scope option, you add a <parameter> to your service like this (where "<i>value</i>" is request, session, or application):</p>
+<p>Axis supports scoping service objects (the actual Java objects which implement your methods) three ways. "Request" scope, the default, will create a new object each time a SOAP request comes in for your service. "Application" scope will create a singleton shared object to service <b>all</b> requests. "Session" scope will create a new object for each session-enabled client who accesses your service. To specify the scope option, you add a <parameter> to your service like this (where "<i><font color="#FF0000">value</font></i>" is request, session, or application):</p>
<source><service name="MyService"...>
- <parameter name="scope" value="<i>value</i>"/>
+ <parameter name="scope" value="<font color="#FF0000"><i>value</i></font>"/>
...
</service></source>
-</section>
-
-<section>
-<title>Using the AdminClient</title>
+<h4>Using the AdminClient</h4>
<p>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. If you have deployed Axis on a server other than Tomcat, you may need to use the -p <i><port></i> argument. The default port is 8080. A typical invocation of the AdminClient looks like this:</p>
@@ -438,10 +369,7 @@ You typed : test me!
<p>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.</p>
-</section>
-
-<section>
-<title>More deployment - Handlers and Chains</title>
+<h4>More deployment - Handlers and Chains</h4>
<p>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 4 in samples/userguide):</p>
@@ -467,10 +395,7 @@ You typed : test me!
<p>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.</p>
-</section>
-
-<section>
-<title>Remote Administration</title>
+<h4>Remote Administration</h4>
<p>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 <b>true</b>. 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:</p>
@@ -482,26 +407,18 @@ You typed : test me!
<p><b>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!</b></p>
-</section>
-
-</section>
+</subsection>
-<a name="ServiceStylesRPCDocumentWrappedAndMessage"/>
-<section>
-<title>Service Styles - RPC, Document, Wrapped, and Message</title>
+<subsection name="Service Styles - RPC, Document, Wrapped, and Message">
<p>There are four "styles" of service in Axis. <b>RPC</b> services use the SOAP RPC conventions, and also the SOAP "section 5" encoding. <b>Document</b> services do not use any encoding (so in particular, you won't see multiref object serialization or SOAP-style arrays on the wire) but DO still do XML<->Java databinding. <b>Wrapped</b> services are just like document services, except that rather than binding the entire SOAP body
into one big structure, they "unwrap" it into individual parameters. <b>Message</b> services receive and return arbitrary XML in the SOAP Envelope without any type mapping / data binding. If you want to work with the raw XML of the incoming and outgoing SOAP Envelopes, write a message service.</p>
-<section>
-<title>RPC services</title>
+<h4>RPC services</h4>
<p>RPC services are the default in Axis. They are what you get when you deploy services with <service ... provider="java:RPC"> or <service ... style="RPC">. RPC services follow the SOAP RPC and encoding rules, which means that the XML for an RPC service will look like the "echoString" example above - each RPC invocation is modeled as an outer element which matches the operation name, containing inner elements each of which maps to a parameter of the operation. Axis will deserialize XML into Java objects which can be fed to your service, and will serialize the returned Java object(s) from your service back into XML. Since RPC services default to the soap section 5 encoding rules, objects will be encoded via "multi-ref" serialization, which allows object graphs to be encoded. (See the SOAP spec for more on multi-ref serialization.)</p>
-</section>
-
-<section>
-<title>Document / Wrapped services</title>
+<h4>Document / Wrapped services </h4>
<p>Document services and wrapped services are similar in that neither uses the SOAP encoding for data; it's just plain old XML schema. In both cases, however, Axis still "binds" Java representations to the XML (see the <a href="#XMLJavaDataMappingInAxis">databinding</a> section for more), so you end up dealing with Java objects, not directly with XML constructs.</p>
@@ -533,11 +450,11 @@ into one big structure, they "unwrap" it
<p>For a <b>document</b> style service, this would map to a method like this:</p>
-<p><code>public void method(PurchaseOrder po)</code></p>
+<source>public void method(PurchaseOrder po)</source>
<p>In other words, the ENTIRE <PurchaseOrder> element would be handed to your method as a single bean with three fields inside it. On the other hand, for a <b>wrapped</b> style service, it would map to a method like this:</p>
-<p><code>public void purchaseOrder(String item, int quantity, String description)</code></p>
+<source>public void purchaseOrder(String item, int quantity, String description)</source>
<p>Note that in the "wrapped" case, the <PurchaseOrder> element is a "wrapper" (hence the name) which only serves to indicate the correct operation. The arguments to our method are what we find when we "unwrap" the outer element and take each of the inner ones as a parameter.</p>
@@ -548,17 +465,16 @@ into one big structure, they "unwrap" it
<p>In most cases you won't need to worry about document or wrapped services if you are starting from a WSDL document (<a href="#UsingWSDLWithAxis">see below</a>).</p>
-</section>
-
-<section>
-<title>Message services</title>
+<h4>Message services</h4>
<p>Finally, we arrive at "Message" style services, which should be used when you want Axis to step back and let your code at the actual XML instead of turning it into Java objects. There are four valid signatures for your message-style service methods:</p>
-<p><code>public Element [] method(Element [] bodies);</code><br/>
- <code>public SOAPBodyElement [] method (SOAPBodyElement [] bodies);</code><br/>
- <code>public Document method(Document body);</code><br/>
- <code>public void method(SOAPEnvelope req, SOAPEnvelope resp);</code></p>
+<source>
+public Element [] method(Element [] bodies);
+public SOAPBodyElement [] method (SOAPBodyElement [] bodies);
+public Document method(Document body);
+public void method(SOAPEnvelope req, SOAPEnvelope resp);
+</source>
<p>The first two will pass your method arrays of either DOM Elements or SOAPBodyElements - the arrays will contain one element for each XML element inside the <soap:body> in the envelope.</p>
@@ -570,7 +486,7 @@ into one big structure, they "unwrap" it
<p>A sample message service can be found in <a href="http://cvs.apache.org/viewcvs.cgi/ws-axis/java/samples/message/MessageService.java?rev=1.7&view=log">samples/message/MessageService.java</a>. The service class, <code>MessageService</code>, has one public method, <code>echoElements</code>, which matches the first of the three method signatures above:</p>
-<p><code>public Element[] echoElements(Element [] elems)</code></p>
+<source>public Element[] echoElements(Element [] elems)</source>
<p>The <code>MsgProvider</code> handler calls the method with an array of <code>org.w3c.dom.Element</code> objects that correspond to the immediate children of the incoming message's SOAP Body. Often, this array will contain a single Element (perhaps the root element of some XML document conforming to some agreed-upon schema), but the SOAP Body can handle any number of children. The method returns an <code>Element[]</code> array to be returned in the SOAP body of the response message.</p>
@@ -579,7 +495,7 @@ into one big structure, they "unwrap" it
<source><deployment name="test" xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">
- <service name="MessageService" style="message">
+ <service name="MessageService" <font color="#FF0000">style="message"</font>>
<parameter name="className" value="samples.message.MessageService"/>
<parameter name="allowedMethods" value="echoElements"/>
</service>
@@ -589,25 +505,18 @@ into one big structure, they "unwrap" it
<p>You can test this service by deploying it, then running samples.message.TestMsg (look at the source to see what the test driver does).</p>
-</section>
+</subsection>
</section>
-</section>
+<section name="XML <-> Java Data Mapping in Axis">
-<a name="XMLJavaDataMappingInAxis"/>
-<section>
-<title>XML <-> Java Data Mapping in Axis</title>
-
-<a name="HowYourJavaTypesMapToSOAPXMLTypes"/>
-<section>
-<title>How your Java types map to SOAP/XML types</title>
+<subsection name="How your Java types map to SOAP/XML types">
<p>Interoperability, <i>interop</i>, is an ongoing challenge between SOAP implementations. If you want your service to work with other platforms and implementations, you do need to understand the issues. There are some <a href="reading.html#Interoperability">external articles</a> on the subject that act as a good starting place. The basic mapping between Java types and WSDL/XSD/SOAP in Axis is determined by the JAX-RPC specification. Read chapters 4 and 5 of the <a href="http://java.sun.com/xml/jaxrpc/">specification</a> to fully understand how things are converted. Here are some of the salient
points.</p>
-<section>
-<title>Standard mappings from WSDL to Java</title>
+<h4>Standard mappings from WSDL to Java</h4>
<table>
<tr>
@@ -670,25 +579,17 @@ points.</p>
<p>If the WSDL says that an object can be <code>nillable</code>, that is the caller may choose to return a value of <code>nil</code>, then the primitive data types are replaced by their wrapper classes, such as Byte, Double, Boolean, etc.</p>
-</section>
-
-<section>
-<title>SOAP Encoding Datatypes</title>
+<h4>SOAP Encoding Datatypes</h4>
<p>Alongside the XSD datatypes are the SOAP 'Section 5' datatypes that are all nillable, and so only ever map to the wrapper classes. These types exist because they all support the "ID" and "HREF" attributes, and so will be used when in an RPC-encoded context to support multi-ref serialization.</p>
-</section>
-
-</section>
+</subsection>
-<a name="Exceptions"/>
-<section>
-<title>Exceptions</title>
+<subsection name="Exceptions">
<p>This is an area which causes plenty of confusion, and indeed, the author of this section is not entirely sure how everything works, especially from an interop perspective. This means treat this section as incomplete and potentially inaccurate. See also section 5.5.5 and chapter 14 in the JAX-RPC specification</p>
-<section>
-<title>RemoteExceptions map to SOAP Faults</title>
+<h4>RemoteExceptions map to SOAP Faults</h4>
<p>If the server method throws a <code>java.rmi.RemoteException</code> then this will be mapped into a SOAP Fault. The <code>faultcode</code> of this will contain the classname of the fault. The recipient is expected to deserialize the body of the fault against the classname.</p>
@@ -696,10 +597,7 @@ points.</p>
<p>When an implementation in another language receives such an exception, it should see the name of the class as the faultCode, but still be left to parse the body of the exception. You need to experiment to find out what happens there.</p>
-</section>
-
-<section>
-<title>Exceptions are represented as wsdl:fault elements</title>
+<h4>Exceptions are represented as wsdl:fault elements</h4>
<p>If a method is marked as throwing an <code>Exception</code> that is not an instance or a subclass of <code>java.rmi.RemoteException</code>, then things are subtly different. The exception is no longer a SOAP Fault, but described as a <code>wsdl:fault</code> in the WSDL of the method. According to the JAX-RPC specification, your subclass of Exception must have accessor methods to access all the fields in the object to be marshalled <i>and</i> a constructor that takes as parameters all the same fields (i.e, arguments of the same name and type). This is a kind of immutable variant of a normal <a href="http://java.sun.com/products/javabeans">JavaBean</a>. The fields in the object must be of the datatypes that can be reliably mapped into WSDL.</p>
@@ -707,47 +605,30 @@ points.</p>
<p>Again, to be sure of interoperability, you need to be experiment a bit. Remember, the calling language may not have the notion of Exceptions, or at least not be as rigorous as Java in the rules as to how exceptions must be handled.</p>
-</section>
-
-</section>
+</subsection>
-<a name="WhatAxisCanSendViaSOAPWithRestrictedInteroperability"/>
-<section>
-<title>What Axis can send via SOAP with restricted Interoperability</title>
+<subsection name="What Axis can send via SOAP with restricted Interoperability">
-<section>
-<title>Java Collections</title>
+<h4>Java Collections</h4>
<p>Some of the Collection classes, such as <code>Hashtable</code>, do have serializers, but there is no formal interoperability with other SOAP implementations, and nothing in the SOAP specifications which covers complex objects. The most reliable way to send aggregate objects is to use arrays. In particular, .NET cannot handle them, though many Java SOAP implementations can marshall and unmarshall hash tables.</p>
-</section>
-
-</section>
+</subsection>
-<a name="WhatAxisCanNotSendViaSOAP"/>
-<section>
-<title>What Axis can not send via SOAP</title>
+<subsection name="What Axis can not send via SOAP">
-<section>
-<title>Arbitrary Objects without Pre-Registration</title>
+<h4>Arbitrary Objects without Pre-Registration</h4>
<p>You cannot send arbitrary Java objects over the wire and expect them to be understood at the far end. With RMI you can send and receive <code>Serializable</code> Java objects, but that is because you are running Java at both ends. <b>Axis will only send objects for which there is a registered Axis serializer.</b> This document shows below how to use the BeanSerializer to serialize any class that follows the JavaBean pattern of accessor and mutator. To serve up objects you must either register your classes with this BeanSerializer, or there must be serialization support built in to Axis.</p>
-</section>
-
-<section>
-<title>Remote References</title>
+<h4>Remote References</h4>
<p>Remote references are neither part of the SOAP specification, nor the JAX-RPC specification. You cannot return some object reference and expect
the caller to be able to use it as an endpoint for SOAP calls or as a parameter in other calls. Instead you must use some other reference mechanism, such as storing them in a <code>HashMap</code> with numeric or string keys that can be passed over the wire.</p>
-</section>
-
-</section>
+</subsection>
-<a name="EncodingYourBeansTheBeanSerializer"/>
-<section>
-<title>Encoding Your Beans - the BeanSerializer</title>
+<subsection name="Encoding Your Beans - the BeanSerializer">
<p>Axis includes the ability to serialize/deserialize, without writing any code, arbitrary Java classes which follow the standard <a href="http://java.sun.com/products/javabeans">JavaBean</a> 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>
@@ -773,18 +654,15 @@ If this had been a real order processing
you about now.
%</source>
-</section>
+</subsection>
-<a name="WhenBeansAreNotEnoughCustomSerialization"/>
-<section>
-<title>When Beans Are Not Enough - Custom Serialization</title>
+<subsection name="When Beans Are Not Enough - Custom Serialization">
<p>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.</p>
-<p><i>TBD - this section will be expanded in a future version! For now look at the DataSer/DataDeser classes (in samples/encoding). Also look at the BeanSerializer, BeanDeserializer, ArraySerializer, ArrayDeserializer and other classes in the org.apache.axis.encoding.ser package.</i></p>
+<p><i><font color="#FF0000">TBD - this section will be expanded in a future version! For now look at the DataSer/DataDeser classes (in samples/encoding). Also look at the BeanSerializer, BeanDeserializer, ArraySerializer, ArrayDeserializer and other classes in the org.apache.axis.encoding.ser package.</font></i></p>
-<section>
-<title>Deploying custom mappings - the <typeMapping> tag</title>
+<h4>Deploying custom mappings - the <typeMapping> tag</h4>
<p>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:</p>
@@ -798,12 +676,9 @@ you about now.
<p>(The <beanMapping> tag is really just shorthand for a <typeMapping> tag with <code>serializer="org.apache.axis.encoding.ser.BeanSerializerFactory"</code>, <code>deserializer="org.apache.axis.encoding.ser.BeanDeserializerFactory"</code>, and <code>encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"</code>, but clearly it can save a lot of typing!)</p>
-</section>
-
-<section>
-<title>Deploying array mappings - the <arrayMapping> tag</title>
+<h4>Deploying array mappings - the <arrayMapping> tag</h4>
-<p>nother variation around typeMapping is arrayMapping. The arrayMapping tag is useful for advanced users wanting to exatly control how their arrays are serialized throught the wire. </p>
+<p>Another variation around typeMapping is arrayMapping. The arrayMapping tag is useful for advanced users wanting to exatly control how their arrays are serialized throught the wire. </p>
<source><arrayMapping qname="ns:ArrayOfthingy" xmlns:ns="someNamespaceURI"
languageSpecificType="java:my.java.array.thingy[]"
@@ -814,16 +689,11 @@ you about now.
is only about arrays (no List, ...). The added attribute (<i>innerType</i>) is used
to tell Axis what precisely is the item type of the Array.</p>
-</section>
-
-</section>
+</subsection>
</section>
-
-<a name="UsingWSDLWithAxis"/>
-<section>
-<title>Using WSDL with Axis</title>
+<section name="Using WSDL with Axis">
<p>The <a href="http://www.w3.org/TR/wsdl">Web Service Description Language</a> 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.</p>
@@ -835,9 +705,7 @@ to tell Axis what precisely is the item
<li>We provide a "Java2WSDL" tool which will build WSDL from Java classes.</li>
</ol>
-<a name="WSDLObtainingWSDLForDeployedServices"/>
-<section>
-<title>?WSDL: Obtaining WSDL for deployed services</title>
+<subsection name="?WSDL: Obtaining WSDL for deployed services">
<p>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>".</p>
@@ -845,14 +713,11 @@ to tell Axis what precisely is the item
<p>You can also generate WSDL files from existing Java classes (see <a href="#Java2WSDLBuildingWSDLFromJava">Java2WSDL: Building WSDL from Java</a>).</p>
-</section>
+</subsection>
-<a name="WSDL2JavaBuildingStubsSkeletonsAndDataTypesFromWSDL"/>
-<section>
-<title>WSDL2Java: Building stubs, skeletons, and data types from WSDL</title>
+<subsection name="WSDL2Java: Building stubs, skeletons, and data types from WSDL">
-<section>
-<title>Client-side bindings</title>
+<h4>Client-side bindings</h4>
<p>You'll find the Axis WSDL-to-Java tool in "org.apache.axis.wsdl.WSDL2Java". The basic invocation form looks like this:</p>
@@ -898,10 +763,7 @@ to tell Axis what precisely is the item
<p>There is an <a href="ant/axis-wsdl2java.html">Ant Task</a> to integrate this action with an Ant based build process.</p>
-</section>
-
-<section>
-<title>Types</title>
+<h4>Types</h4>
<p>The Java class generated from a WSDL type will be named from the WSDL type. This class will typically, though not always, be a bean. For example, given the WSDL (the WSDL used throughout the WSDL2Java discussion is from the <a href="http://cvs.apache.org/viewcvs.cgi/ws-axis/java/samples/addr/AddressBook.wsdl?amp;rev=1.9&view=log">Address Book sample</a>):</p>
@@ -927,10 +789,7 @@ to tell Axis what precisely is the item
public int hashCode() {...}
}</source>
-</section>
-
-<section>
-<title>Mapping XML to Java types : Metadata</title>
+<h4>Mapping XML to Java types : Metadata</h4>
<p>Notice in the mapping above, the XML type name is "phone" and the generated Java class is "Phone" - the capitalization of the first letter has changed to match the Java coding convention that classes begin with an uppercase letter. This sort of thing happens a lot, because the rules for expressing XML names/identifiers are much less restrictive than those for Java. For example, if one of the sub-elements in the "phone" type above was named "new", we couldn't just generate a Java field called "new", since that is a reserved word and the resultant source code would fail to compile.</p>
@@ -940,10 +799,7 @@ to tell Axis what precisely is the item
<p>To see an example of this kind of metadata, look at the "test.encoding.AttributeBean" class in the Axis source, or generate your own bean from XML which uses attributes or names which would be illegal in Java.</p>
-</section>
-
-<section>
-<title>Holders</title>
+<h4>Holders</h4>
<p>This type may be used as an inout or out parameter. Java does not have the concept of inout/out parameters. In order to achieve this behavior, JAX-RPC specifies the use of holder classes. A holder class is simply a class that contains an instance of its type. For example, the holder for the Phone class would be:</p>
@@ -965,10 +821,7 @@ public final class PhoneHolder implement
<p>The holder classes for the primitive types can be found in javax.xml.rpc.holders.</p>
-</section>
-
-<section>
-<title>PortTypes</title>
+<h4>PortTypes</h4>
<p>The Service Definition Interface (SDI) is the interface that's derived from a WSDL's portType. This is the interface you use to access the operations on the service. For example, given the WSDL:</p>
@@ -1001,10 +854,7 @@ public final class PhoneHolder implement
<p>Ugly, isn't it? But you can see why it's necessary. Since document/literal changes what the interface looks like, and we could have more than one binding referring to a single portType, we have to create more than one interface, and each interface must have a unique name.</p>
-</section>
-
-<section>
-<title>Bindings</title>
+<h4>Bindings</h4>
<p>A Stub class implements the SDI. Its name is the binding name with the suffix "Stub". It contains the code which turns the method invocations into SOAP calls using the Axis Service and Call objects. It stands in as a <b>proxy</b> (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.</p>
@@ -1030,10 +880,7 @@ public final class PhoneHolder implement
throws RemoteException {...}
}</source>
-</section>
-
-<section>
-<title>Services</title>
+<h4>Services</h4>
<p>Normally, a client program would not instantiate a stub directly. It would instead instantiate a service locator and call a get method which returns a stub. This locator is derived from the service clause in the WSDL. WSDL2Java generates two objects from a service clause. For example, given the WSDL:</p>
@@ -1079,10 +926,7 @@ public final class PhoneHolder implement
}
}</source>
-</section>
-
-<section>
-<title>Server-side bindings</title>
+<h4>Server-side bindings</h4>
<p>Just as a stub is the client side of a Web Service represented in Java, a <b>skeleton</b> is a Java framework for the server side. To make skeleton classes, you just specify the "--server-side --skeletonDeploy true" options to WSDL2Java. For instance, using the AddressBook.wsdl as we had above:</p>
@@ -1139,15 +983,9 @@ public final class PhoneHolder implement
</tr>
</table>
-</section>
-
-<section>
-<title>Bindings</title>
+<h4>Bindings</h4>
-</section>
-
-<section>
-<title>Skeleton Description (for Skeleton Deployment)</title>
+<h5>Skeleton Description (for Skeleton Deployment)</h5>
<p>The skeleton class is the class that sits between the Axis engine and the actual service implementation. Its name is the binding name with suffix "Skeleton". For example, for the AddressBook binding, WSDL2Java will generate:</p>
@@ -1173,10 +1011,7 @@ public final class PhoneHolder implement
<p>The skeleton contains an implementation of the AddressBook service. This implementation is either passed into the skeleton on construction, or an instance of the generated implementation is created. When the Axis engine calls the skeleton's addEntry method, it simply delegates the invocation to the real implementation's addEntry method.</p>
-</section>
-
-<section>
-<title>Implementation Template Description</title>
+<h5>Implementation Template Description</h5>
<p>WSDL2Java also generates an implementation template from the binding:</p>
@@ -1190,25 +1025,17 @@ public final class PhoneHolder implement
<p>When WSDL2Java is asked to generate the implementation template (via the --server-side flag), it will ONLY generate it if it does not already exist. If this implementation already exists, it will not be overwritten.</p>
-</section>
-
-<section>
-<title>Services</title>
+<h4>Services</h4>
<p>The tool also builds you a "deploy.wsdd" and an "undeploy.wsdd" for each service 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.</p>
-</section>
+</subsection>
-</section>
-
-<a name="Java2WSDLBuildingWSDLFromJava"/>
-<section>
-<title>Java2WSDL: Building WSDL from Java</title>
+<subsection name="Java2WSDL: Building WSDL from Java">
<p>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.</p>
-<section>
-<title>Step 1: Provide a Java interface or class</title>
+<h4>Step 1: Provide a Java interface or class</h4>
<p>Write and compile a Java interface (or class) 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 (<a href="http://cvs.apache.org/viewcvs.cgi/ws-axis/java/samples/userguide/example6/WidgetPrice.java?amp;rev=1.3&view=log">samples/userguide/example6/WidgetPrice.java</a>):</p>
@@ -1224,14 +1051,11 @@ public interface WidgetPrice {
<p><b>Note:</b> If you compile your class with debug information, Java2WSDL will use the debug information to obtain the method parameter names.</p>
-</section>
-
-<section>
-<title>Step 2: Create WSDL using Java2WSDL</title>
+<h4>Step 2: Create WSDL using Java2WSDL</h4>
<p>Use the Java2WSDL tool to create a WSDL file from the interface above.</p>
-<p>Here is an example invocation that produces the wsdl file (<code>wp.wsdl</code>) from the interface described in the previous section:</p>
+<p>Here is an example invocation that produces the wsdl file (<code>wp.wsdl</code>) from the interface described in the previous section (entered all on one line):</p>
<source>
% java org.apache.axis.wsdl.Java2WSDL -o wp.wsdl
@@ -1243,7 +1067,7 @@ public interface WidgetPrice {
<ul>
<li>-o indicates the name of the <b><i>output WSDL</i></b> file</li>
- <li>-l indicates the<b><i>location of the service</i></b></li>
+ <li>-l indicates the <b><i>location of the service</i></b></li>
<li>-n is the target <b><i>namespace</i></b> of the WSDL file</li>
<li>-p indicates a mapping from the <b><i>package to a namespace</i></b>. There may be multiple mappings.</li>
<li>the class specified contains the interface of the webservice.</li>
@@ -1253,10 +1077,7 @@ public interface WidgetPrice {
<p>The Java2WSDL tool has many additional options which are detailed in the <a href="reference.html#Java2WSDLReference">reference guide</a>. There is an <a href="ant/axis-java2wsdl.html">Ant Task</a> to integrate this action with an Ant based build process.</p>
-</section>
-
-<section>
-<title>Step 3: Create Bindings using WSDL2Java</title>
+<h4>Step 3: Create Bindings using WSDL2Java</h4>
<p>Use the generated WSDL file to build the appropriate client/server bindings for the web service (see <a href="#WSDL2JavaBuildingStubsSkeletonsAndDataTypesFromWSDL">WSDL2Java</a>):</p>
@@ -1280,15 +1101,11 @@ public interface WidgetPrice {
<p>Now you have all of the necessary files to build your client/server side code and deploy the web service!</p>
-</section>
+</subsection>
</section>
-</section>
-
-<a name="PublishedAxisInterfaces"/>
-<section>
-<title>Published Axis Interfaces</title>
+<section name="Published Axis Interfaces">
<p>Although you may use any of the interfaces and classes present in Axis, you need to be aware that some are more stable than others since there is a continuing need to refactor Axis to maintain and improve its modularity.</p>
@@ -1405,15 +1222,11 @@ public interface WidgetPrice {
</section>
-<a name="NewbieTipsFindingYourWayAround"/>
-<section>
-<title>Newbie Tips: Finding Your Way Around</title>
+<section name="Newbie Tips: Finding Your Way Around">
<p>So you've skimmed the User's Guide and written your first .jws service, and everything went perfectly! Now it's time to get to work on a real project, and you have something specific you need to do that the User's Guide didn't cover. It's a simple thing, and you know it must be in Axis <i>somewhere</i>, but you don't know what it's called or how to get at it. This section is meant to give you some starting points for your search.</p>
-<a name="PlacesToLookForClues"/>
-<section>
-<title>Places to Look for Clues</title>
+<subsection name="Places to Look for Clues">
<p>Here are the big categories.</p>
@@ -1425,14 +1238,11 @@ public interface WidgetPrice {
<li><b>WSDL2Java.</b> Point WSDL2Java at a known webservice that does some of the things you want to do. See what comes out. This is useful even if you will be writing the actual service or client from scratch. If you want nice, human-readable descriptions of existing web services, try <a href="http://www.xmethods.net">http://www.xmethods.net</a>.</li>
</ul>
-</section>
+</subsection>
-<a name="ClassesToKnow"/>
-<section>
-<title>Classes to Know</title>
+<subsection name="Classes to Know">
-<section>
-<title>org.apache.axis.MessageContext</title>
+<h4>org.apache.axis.MessageContext</h4>
<p>The answer to most "where do I find..." questions for an Axis web service is "in the MessageContext." Essentially everything Axis knows about a given request/response can be retrieved via the MessageContext. Here Axis stores:</p>
@@ -1447,10 +1257,7 @@ public interface WidgetPrice {
<p>From within your service, the current MessageContext object is always available via the static method <code>MessageContext.getCurrentContext()</code>. This allows you to do any needed customization of the request and response methods, even from within an RPC service that has no explicit reference to the MessageContext.</p>
-</section>
-
-<section>
-<title>org.apache.axis.Message</title>
+<h4>org.apache.axis.Message</h4>
<p>An <code>org.apache.axis.Message</code> object is Axis's representation of a SOAP message. The request and response messages can be retrieved from the MessageContext as described above. A Message has:</p>
@@ -1460,22 +1267,15 @@ public interface WidgetPrice {
<li>A SOAPPart (and a convenience method for quick retrieval of the SOAPPart's SOAPEnvelope). The SOAPPart gives you access to the SOAP "guts" of the message (everything inside the <soap:Envelope> tags)</li>
</ul>
-</section>
-
-<section>
-<title>org.apache.axis.SOAPEnvelope</title>
+<h4>org.apache.axis.SOAPEnvelope</h4>
<p>As you can see, starting with the MessageContext lets you work your way down through the API, discovering all the information available to you about a single request/response exchange. A MessageContext has two Messages, which each have a SOAPPart that contains a SOAPEnvelope. The SOAPEnvelope, in turn, holds a full representation of the SOAP Envelope that is sent over the wire. From here you can get and set the contents of the SOAP Header and the SOAP Body. See the Javadocs for a full list of the properties available.</p>
-</section>
+</subsection>
</section>
-</section>
-
-<a name="AppendixUsingTheAxisTCPMonitorTcpmon"/>
-<section>
-<title>Appendix : Using the Axis TCP Monitor (tcpmon)</title>
+<section name="Appendix : Using the Axis TCP Monitor (tcpmon)">
<p>The included "tcpmon" utility can be found in the org.apache.axis.utils package. To run it from the command line:</p>
@@ -1483,11 +1283,11 @@ public interface WidgetPrice {
<p>Without any of the optional arguments, you will get a gui which looks like this:</p>
-<p><img src="images/tcpmon1.jpg" height="599" width="599"/></p>
+<p><img src="images/tcpmon1.jpg" height="599" width="599" alt="tcpmon1"/></p>
<p>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><img src="images/tcpmon2.jpg" height="600" width="599"/></p>
+<p><img src="images/tcpmon2.jpg" height="600" width="599" alt="tcpmon2"/></p>
<p>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>
@@ -1495,9 +1295,7 @@ public interface WidgetPrice {
</section>
-<a name="AppendixUsingTheSOAPMonitor"/>
-<section>
-<title>Appendix: Using the SOAP Monitor</title>
+<section name="Appendix: Using the SOAP Monitor">
<p>Web service developers often have the need to see the SOAP messages being used to invoke web services along with the results of those messages. The goal of the SOAP Monitor utility is to provide a way for these developers to monitor the SOAP messages being used without requiring any special configuration or restarting of the server.</p>
@@ -1513,9 +1311,48 @@ public interface WidgetPrice {
</section>
-<a name="Glossary"/>
-<section>
-<title>Glossary</title>
+<section name="Appendix : Using the Standalone Soap Server">
+
+<p>To run the standalone server from the command line:</p>
+
+<source>% java org.apache.axis.transport.http.SimpleAxisServer [-t maxpool] [-m maxsess] [-p port]</source>
+
+<p>
+The following options can be specified:
+</p>
+<ul>
+<li>
+-t maxpool Specify the maxium pool size for the server.
+This is the maximum number of simultaneous connections (threads) the server can accept (run). The default is 100.
+</li>
+<li>
+-m maxsess
+This is the maximum number of sessions the server will run. Again, the default is 100.
+</li>
+<li>
+-p port
+This is the port number the server will use to run. The default is 8080 which is also used by Tomcat. Unexpected results will occur if you start the server on a port that is already in use.
+</li>
+</ul>
+
+<p>The following jars need to be on the classpath (as a minimum):</p>
+
+<ul>
+<li>axis.jar</li>
+<li>commons-discovery-0.2.jar</li>
+<li>commons-logging-1.0.4.jar</li>
+<li>jaxrpc.jar</li>
+<li>saaj.jar</li>
+<li>wsdl4j-1.5.1.jar</li>
+<li>activation.jar (*)</li>
+<li>mail.jar (*)</li>
+</ul>
+
+<p>(*) These are not included in the distribution, and must be downloaded from java.sun.com</p>
+
+</section>
+
+<section name="Glossary">
<dl>
<dt><i>Handler</i></dt>
@@ -1530,7 +1367,5 @@ public interface WidgetPrice {
</section>
-</section>
-
</body>
</document>