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 rk...@apache.org on 2003/07/10 03:04:25 UTC
cvs commit: xml-axis/java/docs user-guide.html
rkellogg 2003/07/09 18:04:24
Modified: java/docs user-guide.html
Log:
Fix for bug 21450 plus additional editorial corrections.
Revision Changes Path
1.88 +36 -37 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.87
retrieving revision 1.88
diff -u -r1.87 -r1.88
--- user-guide.html 8 Jun 2003 01:48:38 -0000 1.87
+++ user-guide.html 10 Jul 2003 01:04:23 -0000 1.88
@@ -94,7 +94,7 @@
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
+ 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
@@ -138,7 +138,7 @@
<li> HTTP servlet-based transport</li>
<li> JMS based transport</li>
<li> Standalone version of the server (with HTTP support)</li>
- <li> Examples, including a client and server for the soapbuilders community
+ <li> Examples, including a client and server for the SoapBuilders community
interoperability tests and experimental TCP, JMS, and file-based transports.</li>
</ul>
@@ -152,7 +152,7 @@
for instructions on installing Axis as a web application on your J2EE server.
<p>Before running the examples in this guide, you'll need to make sure
that your CLASSPATH includes
-(note: if you build axis from a CVS checkout,
+(Note: If you build Axis from a CVS checkout,
these will be in xml-axis/java/build/lib instead of axis-1_1/lib):
<ul>
<li>axis-1_1/lib/axis.jar</li>
@@ -162,7 +162,7 @@
<li>axis-1_1/lib/commons-discovery.jar</li>
<li>axis-1_1/lib/wsdl4j.jar</li>
<li>axis-1_1/ <i><font color="#9966FF">(for the sample code)</font></i></li>
- <li>A JAXP-1.1 compliant XML parser such as xerces or crimson</li>
+ <li>A JAXP-1.1 compliant XML parser such as Xerces or Crimson</li>
</ul>
<h2>
<a NAME="ConsumingServices"></a>Consuming Web Services with Axis</h2>
@@ -223,12 +223,12 @@
</SOAP-ENV:Envelope></pre>
<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
+<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="#tcpmon">tcpmon</a> tool or <a href="#soapmon">SOAP monitor</a> tool. See the appendix
for an overview.</i></p>
<h3>Naming Parameters</h3>
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
+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 <tt>invoke()</tt>
you need to call <tt>addParameter</tt> for each parameter and <tt>setReturnType</tt> for the return, like so:
<pre class="example"> call.addParameter("testParam",
@@ -335,7 +335,7 @@
% java samples.userguide.example2.CalcClient -p8080 subtract 10 9
Got result : 1
%</pre>
-(note that you may need to replace the "-p8080" with whatever port your
+(Note that you may need to replace the "-p8080" with whatever port your
J2EE server is running on)
<p>
<i><b>Important:</b></i> JWS web services are intended for simple web services.
@@ -351,7 +351,7 @@
- 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
+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>
@@ -500,10 +500,10 @@
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)
+to be encoded. (See the SOAP spec for more on multi-ref serialization.)
<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,
+ 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="#DataMapping">databinding</a>
section for more), so you end up dealing with Java objects, not directly with
XML constructs.</p>
@@ -600,7 +600,7 @@
<h2><a NAME="DataMapping"></a>XML <-> Java Data Mapping in Axis</h2>
<h3>How your Java types map to SOAP/XML types</h3>
-Interoperability, <i>interop</i> is an ongoing challenge
+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#interop">external articles</a> on the subject that act
@@ -637,7 +637,7 @@
<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.
+ will be used when in an RPC-encoded context to support multi-ref serialization.
<h3>Exceptions</h3>
@@ -673,7 +673,7 @@
<h4>Exceptions are represented as <tt>wsdl:fault</tt> elements</h4>
-If a method is marked as throwing an <tt>Exception</tt>, that is not
+If a method is marked as throwing an <tt>Exception</tt> that is not
an instance or a subclass of <tt>java.rmi.RemoteException</tt>, then
things are subtly different. The exception is no longer a SOAP Fault, but
described as a <tt>wsdl:fault</tt> in the WSDL of the method.
@@ -681,15 +681,15 @@
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
+same fields (i.e, arguments of the same name and type). This is a kind of
immutable variant of a normal JavaBean. The fields in the object must be
of the datatypes that can be reliably mapped into WSDL.
<p>
-If your exception meet this specification, then the WSDL describing the
+If your exception meets this specification, then the WSDL describing the
method will describe the exception too, enabling callers to create stub
-implementations of the exception , regardless of platform.
+implementations of the exception, regardless of platform.
<p>
@@ -709,12 +709,12 @@
written in C++, C# and the like, and re-implement interfaces designed for
those languages. Be very wary about exporting unsigned datatypes, however, as to
do so will stop Java clients that do not use Axis or another SOAP client library
-with unsigned support from using them. At least, until
-a revision of JAX-RPC adds this.
+with unsigned support from using them. The current JAX-RPC specification does
+not address this issue.
<h5>Java Collections</h5>
-Some of the Collection classes, such as <tt>Hashtable</tt> do have
+Some of the Collection classes, such as <tt>Hashtable</tt>, 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
@@ -738,10 +738,9 @@
serialization support built in to Axis.
+Remote References
-<h5>Remote References</h5>
-
-This is neither part of the SOAP specification, or the JAX-RPC
+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
@@ -749,8 +748,7 @@
string keys that can be passed over the wire.
-<h3>
-Encoding Your Beans - the BeanSerializer</h3>
+<h3>Encoding Your Beans - the BeanSerializer</h3>
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
@@ -765,9 +763,9 @@
<p>Let's take a look at how this works in practice. Go look at <a href="../samples/userguide/example5/BeanService.java">samples/userguide/example5/BeanService.java</a>. 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,
+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):
<pre class="example">% java org.apache.axis.client.AdminClient -llocal:///AdminService deploy.wsdd
<Admin>Done processing</Admin>
@@ -813,9 +811,10 @@
are three extra attributes. One, <b>serializer</b>, is the Java class name
of the Serializer <i>factory</i> which gets the serializer to
be used to marshal an object of the specified Java class
-(i.e. my.java.thingy) into XML. Two, <b>deserializer</b>, is
+(i.e., my.java.thingy) into XML. Another, <b>deserializer</b>, is
the class name of a Deserializer <i>factory</i> that gets the deserializer
-to be used to unmarshall XML into the correct Java class. Finally, the <b>encodingStyle</b>, which is SOAP encoding.
+to be used to unmarshall XML into the correct Java class. The final attribute,
+the <b>encodingStyle</b>, which is SOAP encoding.
<p>(The <beanMapping> tag is really just shorthand for a <typeMapping> tag
with <tt>serializer="org.apache.axis.encoding.ser.BeanSerializerFactory"</tt>,
<tt>deserializer="org.apache.axis.encoding.ser.BeanDeserializerFactory"</tt>,
@@ -869,14 +868,14 @@
Building stubs, skeletons, and data types from WSDL</h3>
<h4>Client-side bindings</h4>
-<p>You'll find the AXIS WSDL -> Java tool in "org.apache.axis.wsdl.WSDL2Java".
+<p>You'll find the Axis WSDL-to-Java tool in "org.apache.axis.wsdl.WSDL2Java".
The basic invocation form looks like this:</p>
<pre class="example">
% java org.apache.axis.wsdl.WSDL2Java (WSDL-file-URL)
</pre>
<p>This will generate only those bindings necessary for the client.
-AXIS follows the JAX-RPC specification when generating Java client bindings
+Axis follows the JAX-RPC specification when generating Java client bindings
from WSDL. For this discussion, assume we executed the following:</p>
<pre class="example">
% cd samples/addr
@@ -1039,7 +1038,7 @@
from the name attribute of the wsdl:portType element. ... If the mapping to
a service definition interface uses elements of the wsdl:binding ..., then
the name of the service definition interface is mapped from the name of the
-wsdel:binding element."
+wsdl:binding element."
<p>Note the name of the spec. It contains the string "RPC". So this spec,
and WSDL2Java, assumes that the interface generated from the portType is an
RPC interface. If information from the binding tells us otherwise (in
@@ -1048,7 +1047,7 @@
<p>Why? We could have one portType - pt - and two bindings - bRPC and
bDoc. Since document/literal changes what the interface looks like, we
cannot use a single interface for both of these bindings, so we end up with
-2 interfaces - one named pt and another named bDoc - and two stubs -
+two interfaces - one named pt and another named bDoc - and two stubs -
bRPCStub (which implements pt) and bDocStub (which implements bDoc).
<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
@@ -1213,7 +1212,7 @@
Bindings</h4>
<h5>
Skeleton Description (for Skeleton Deployment) </h5>
-The skeleton class is the class that sits between the AXIS engine and the
+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:
@@ -1240,7 +1239,7 @@
<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
+Axis engine calls the skeleton's addEntry method, it simply delegates the
invocation to the real implementation's addEntry method.
<h5>
Implementation Template Description </h5>
@@ -1425,7 +1424,7 @@
<li>javax.xml.transform.Source</li>
</ul>
</li>
-<li>AXIS interfaces. These have less guarantees of stability:
+<li>Axis interfaces. These have less guarantees of stability:
<ul>
<li>org.apache.axis.AxisFault</li>
<li>org.apache.axis.Handler</li>
@@ -1618,7 +1617,7 @@
correct plug-in, the browser should prompt you to install one.
<p>
The port used by the SOAP monitor service to comminicate with
-applets is configurable. Edit the web.xml file for the AXIS
+applets is configurable. Edit the web.xml file for the Axis
web application to change the port to be used.
<a NAME="Glossary">