gdaniels 02/04/20 14:33:19
Modified: java/docs user-guide.html
Log:
Start working on beta-2 version - mostly HTML cleanup.
Revision Changes Path
1.55 +233 -269 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.54
retrieving revision 1.55
diff -u -r1.54 -r1.55
--- user-guide.html 11 Apr 2002 15:45:09 -0000 1.54
+++ user-guide.html 20 Apr 2002 21:33:18 -0000 1.55
@@ -24,7 +24,7 @@
<h1>
Axis User's Guide</h1>
-<i>Beta 1 Version</i>
+<i>Beta 2 Version</i>
<h3>
Table of Contents</h3>
@@ -73,10 +73,8 @@
<h2>
<a NAME="Introduction"></a>Introduction</h2>
-Welcome to Axis, the third generation of Apache SOAP! This is the <b>beta 1</b>
version. Please note that Axis is a work in progress, and although
-the basic functionality is there, there are still some unfinished areas
-and rough edges. That said, we're very psyched about the package so far
-and would love to get your take on how we can make it better.
+Welcome to Axis, the third generation of Apache SOAP! This is the <b>beta 2</b>
+version.
<h3>
What is SOAP?</h3>
SOAP is an XML<i>-</i>based communitcation protocol and encoding format
@@ -102,30 +100,24 @@
manner. Axis is the result of months of continued discussion and coding
effort in this direction. Some of the key Axis features include the following:
<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
-<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>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 <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>
</ul>
We hope you enjoy using Axis. Please note that this is an open-source effort
- if you feel the code could use some new features or fixes, please get
@@ -185,8 +177,7 @@
Basics - Getting Started</h3>
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.
-<div class="example">
-<pre>1 import org.apache.axis.client.Call;
+<pre class="example">1 import org.apache.axis.client.Call;
2 import org.apache.axis.client.Service;
3 import javax.xml.rpc.namespace.QName;
4
@@ -194,13 +185,13 @@
6 public static void main(String [] args) {
7 try {
8
String endpoint =
-9
"http://nagoya.apache.org:5049/axis/servlet/AxisServlet";;
+9
"http://nagoya.apache.org:5049/axis/services/echo";;
10
11
Service service = new Service();
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("http://soapinterop.org/";, "echoString"));
16
17 String
ret = (String) call.invoke( new Object[] { "Hello!" } );
18
@@ -210,7 +201,6 @@
22 }
23 }
24 }</pre>
-</div>
(You'll find this file in <a
href="../samples/userguide/example1/TestClient.java">samples/userguide/example1/TestClient.java</a>)
<p>Assuming you have a network connection active, this program can be run
as follows:
@@ -224,11 +214,10 @@
the operation (method) name of the Web Service. And on line 17 we actually invoke
the desired service, passing in an array of parameters - in this case just
one String.
-<p>You can see what happens to the arguments by looking at the SOAP request
-that goes out on the wire (look at the colored sections, and notice they
-match the values in the call above):
-<div class="xml">
-<pre><?xml version="1.0" encoding="UTF-8"?>
+<p>You can see what happens to the arguments by looking at the SOAP request that
+ goes out on the wire (look at the colored sections, and notice they match the
+ values in the call above):
+<pre class="xml"><?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema";
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
@@ -238,31 +227,26 @@
</ns1:echoString>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope></pre>
-</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>
-<h3>
-Naming Parameters</h3>
+for an overview.</i></p>
+<h3>Naming Parameters</h3>
In the above example, the parameters are in the order in which we sent
them, but since we only passed the objects themselves, Axis automatically
named the XML-encoded arguments in the SOAP message "arg0", "arg1", etc.
If you want to change this, it's easy! Before calling <tt>invoke()</tt>
you need to call <tt>addParameter</tt> for each parameter, like so:
-<div class="example">
-<pre> call.addParameter("testParam",
+<pre class="example"> call.addParameter("testParam",
org.apache.axis.encoding.XMLType.XSD_STRING,
javax.xml.rpc.ParameterMode.IN);</pre>
-</div>
This will assign the name <b>testParam</b> to the 1st (and only) parameter
on the invoke call. This will also define the type of the parameter
(<tt>org.apache.axis.encoding.XMLType.XSD_STRING</tt>)
and whether it is an input, output or inout parameter - in this case its
an input parameter. Now when you run the program you'll get a message that
looks like this:
-<div class="xml">
-<pre><?xml version="1.0" encoding="UTF-8"?>
+<pre class="example"><?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema";
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
@@ -272,10 +256,8 @@
</ns1:echoString>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope></pre>
-</div>
Note that the param is now named "testParam" as expected.
-<h3>
-Interoperating with "untyped" servers</h3>
+<h3>Interoperating with "untyped" servers</h3>
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
@@ -283,8 +265,7 @@
which sheds light on a potential problem (to which, of course, we have
a solution - so don't fret :)).
<p>Here's what a typical response might look like to the echoString method: </p>
-<div class="xml">
-<pre><?xml version="1.0" encoding="UTF-8"?><br> <SOAP-ENV:Envelope
xmlns:xsd="http://www.w3.org/2001/XMLSchema";
+<pre class="xml"><?xml version="1.0" encoding="UTF-8"?><br>
<SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema";
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
<SOAP-ENV:Body>
@@ -293,15 +274,13 @@
</ns1:echoStringResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope></pre>
- </div>
<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>
-<div class="xml">
- <pre><?xml version="1.0" encoding="UTF-8"?>
+<pre class="xml"><?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema";
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
@@ -311,19 +290,19 @@
</ns1:echoStringResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope></pre>
-</div>
<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>
-<div class="example">
-<pre> call.setReturnType( org.apache.axis.encoding.XMLType.XSD_STRING );</pre>
-</div>
-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.)
+<pre class="example"> call.setReturnType(
org.apache.axis.encoding.XMLType.XSD_STRING );</pre>
+<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>
+<pre class="example">call.setReturnClass(String.class);</pre>
<p>OK - so now you know the basics of accessing SOAP services as a client.
But how do you publish your own services?
<h2>
@@ -381,15 +360,13 @@
"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="../samples/userguide/example3/deploy.wsdd">samples/userguide/example3/deploy.wsdd</a>):</p>
-<div class="example">
-<pre><deployment xmlns="http://xml.apache.org/axis/wsdd/";
+<pre class="example"><deployment xmlns="http://xml.apache.org/axis/wsdd/";
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java";>
<service name="MyService" provider="java:RPC">
<parameter name="className" value="samples.userguide.example3.MyService"/>
<parameter name="allowedMethods" value="*"/>
</service>
</deployment></pre>
-</div>
Pretty simple, really - the outermost element tells the engine that this
is a WSDD deployment, and defines the "java" namespace. Then the service
element actually defines the service for us. A service is a <b>targeted chain</b>
(see the <a href="architecture-guide.html">Architecture Guide</a>), which means it may
have
@@ -436,23 +413,23 @@
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):
-<div class="example"><br><deployment xmlns="http://xml.apache.org/axis/wsdd/";
-<br>
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java";>
-<br> <!-- define the logging handler configuration -->
-<br> <handler name="track"
type="java:samples.userguide.example4.LogHandler">
-<br> <parameter name="filename" value="MyService.log"/>
-<br> </handler>
-<br>
-<br> <!-- define the service, using the log handler we just defined -->
-<br> <service name="LogTestService"<b> </b>provider="java:RPC">
-<br> <requestFlow>
-<br> <handler type="track"/>
-<br> </requestFlow>
-<br>
-<br> <parameter name="className"
value="samples.userguide.example4.Service"/>
-<br> <parameter name="allowedMethods" value="*"/>
-<br> </service>
-<br></deployment></div>
+<pre class="example"><deployment xmlns="http://xml.apache.org/axis/wsdd/";
+
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java";>
+ <!-- define the logging handler configuration -->
+ <handler name="track" type="java:samples.userguide.example4.LogHandler">
+ <parameter name="filename" value="MyService.log"/>
+ </handler>
+
+ <!-- define the service, using the log handler we just defined -->
+ <service name="LogTestService"<b> </b>provider="java:RPC">
+ <requestFlow>
+ <handler type="track"/>
+ </requestFlow>
+
+ <parameter name="className" value="samples.userguide.example4.Service"/>
+ <parameter name="allowedMethods" value="*"/>
+ </service>
+</deployment></pre>
<p>The first section defines a Handler called "track" that is implemented
by the class samples.userguide.example4.LogHandler. We give this Handler
an option to let it know which file to write its messages into.
@@ -470,11 +447,11 @@
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:
-<div class="example"><br><service name="AdminService" provider="java:MSG">
-<br> <parameter name="className" value="org.apache.axis.util.Admin"/>
-<br> <parameter name="allowedMethods" value="*"/>
-<br> <b><parameter name="enableRemoteAdmin" value="true"/>
-<br></b></service></div>
+<pre class="xml"><service name="AdminService" provider="java:MSG">
+ <parameter name="className" value="org.apache.axis.util.Admin"/>
+ <parameter name="allowedMethods" value="*"/>
+ <b><parameter name="enableRemoteAdmin" value="true"/>
+</b></service></pre>
<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>
@@ -535,11 +512,11 @@
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:
-<div class="example"><br><typeMapping qname="ns:local" xmlns:ns="someNamespace"
+<pre class="example"><br><typeMapping qname="ns:local" xmlns:ns="someNamespace"
<br>
languageSpecificType="java:my.java.thingy"
<br>
serializer="my.java.Serializer"
<br>
deserializer="my.java.DeserializerFactory"
-<br>
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/></div>
+<br>
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/></pre>
<p>This looks a lot like the <beanMapping> tag we saw earlier, but there
are three extra attributes. One, <b>serializer</b>, is the Java class name
of the Serializer class which should be used to write the specified Java
@@ -597,25 +574,25 @@
<a NAME="WSDL2Java: Building stubs, skeletons, and data"></a>WSDL2Java:
Building stubs, skeletons, and data types from WSDL</h3>
-<h4>
-Client-side bindings</h4>
-You'll find the AXIS WSDL -> Java tool in "org.apache.axis.wsdl.WSDL2Java".
-The basic invocation form looks like this:
-<div class="example">
-<br><font face="Courier New,Courier">% java org.apache.axis.wsdl.WSDL2Java
-(WSDL-file-URL)</font></div>
+<h4>Client-side bindings</h4>
+<p>You'll find the AXIS WSDL -> 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
-from WSDL. For this discussion, assume we executed the following:
-<div class="example"><br><font face="Courier New,Courier">% cd samples/addr
-<br>% java org.apache.axis.wsdl.WSDL2Java
-AddressBook.wsdl</font></div>
+from WSDL. For this discussion, assume we executed the following:</p>
+<pre class="example">
+% cd samples/addr
+% java org.apache.axis.wsdl.WSDL2Java AddressBook.wsdl
+</pre>
<p>The generated files will reside in the directory "AddressFetcher2".
They are put here because that is the target namespace from the WSDL and namespaces
map to Java packages.
-Namespaces will be discussed in detail later.
-<br>
-<br>
+Namespaces will be discussed in detail later.</p>
+<br>
+<br>
<table BORDER COLS=2 WIDTH="100%" >
<tr>
<td><b>WSDL clause</b></td>
@@ -666,70 +643,72 @@
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="../samples/addr/AddressBook.wsdl">Address Book sample</a>):
-<div class="example"><br><font face="Courier New,Courier"><xsd:complexType
-name="phone">
-<br> <xsd:all>
-<br> <xsd:element name="areaCode" type="xsd:int"/>
-<br> <xsd:element name="exchange" type="xsd:string"/>
-<br> <xsd:element name="number" type="xsd:string"/>
-<br> </xsd:all>
-<br></xsd:complexType></font></div>
+<pre class="example">
+<xsd:complexType name="phone">
+ <xsd:all>
+ <xsd:element name="areaCode" type="xsd:int"/>
+ <xsd:element name="exchange" type="xsd:string"/>
+ <xsd:element name="number" type="xsd:string"/>
+ </xsd:all>
+</xsd:complexType>
+</pre>
<p>WSDL2Java will generate:
-<div class="example"><br><font face="Courier New,Courier">public class Phone
implements java.io.Serializable {
-<br> public Phone() {...}
-<br> public int getAreaCode() {...}
-<br> public void setAreaCode(int areaCode) {...}
-<br> public java.lang.String getExchange() {...}
-<br> public void setExchange(java.lang.String exchange) {...}
-<br> public java.lang.String getNumber() {...}
-<br> public void setNumber(java.lang.String number) {...}
-<br>}</font>
-</div>
-<h4>
-Holders</h4>
-This type may be used as an inout or out parameter. Java does not
+<pre class="example">
+public class Phone implements java.io.Serializable {
+ public Phone() {...}
+ public int getAreaCode() {...}
+ public void setAreaCode(int areaCode) {...}
+ public java.lang.String getExchange() {...}
+ public void setExchange(java.lang.String exchange) {...}
+ public java.lang.String getNumber() {...}
+ public void setNumber(java.lang.String number) {...}
+}
+</pre>
+<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:
-<div class="example"><br><font face="Courier New,Courier">public final class
PhoneHolder implements
-javax.xml.rpc.holders.Holder {
-<br> public Phone value;
-<br>
-<br> public PhoneHolder()
-{
-<br> }
-<br>
-<br> public PhoneHolder(Phone value) {
-<br> this.value = value;
-<br> }
-<br>}</font></div>
+the holder for the Phone class would be:</p>
+<pre class="example">
+public final class PhoneHolder implements javax.xml.rpc.holders.Holder {
+ public Phone value;
+
+ public PhoneHolder()
+ {
+ }
+
+ public PhoneHolder(Phone value) {
+ this.value = value;
+ }
+}
+</pre>
<p>A holder class is <b>only</b> generated for a type if that type is used as
-an inout or out parameter.
-<p>The holder classes for the primitive types can be found in javax.xml.rpc.holders.
-<br>
-<h4>
-PortTypes</h4>
-The Service Definition Interface (SDI) is the interface that's derived
+an inout or out parameter.</p>
+<p>The holder classes for the primitive types can be found in
javax.xml.rpc.holders.</p>
+<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:
-<div class="example"><br><font face="Courier New,Courier"><message name="empty">
-<br><message name="AddEntryRequest">
-<br> <part name="name" type="xsd:string"/>
-<br> <part name="address" type="typens:address"/>
-<br></message>
-<br><portType name="AddressBook">
-<br> <operation name="addEntry">
-<br> <input message="tns:AddEntryRequest"/>
-<br> <output message="tns:empty"/>
-<br> </operation>
-<br></portType></font></div>
+operations on the service. For example, given the WSDL:</p>
+<pre class="example">
+<message name="empty">
+<message name="AddEntryRequest">
+ <part name="name" type="xsd:string"/>
+ <part name="address" type="typens:address"/>
+</message>
+<portType name="AddressBook">
+ <operation name="addEntry">
+ <input message="tns:AddEntryRequest"/>
+ <output message="tns:empty"/>
+ </operation>
+</portType>
+</pre>
<p>WSDL2Java will generate:
-<div class="example"><br><font face="Courier New,Courier">public interface
AddressBook extends
-java.rmi.Remote {
-<br> public void addEntry(String
-name, Address address) throws java.rmi.RemoteException;
-<br>}</font></div>
+<pre class="example">
+public interface AddressBook extends java.rmi.Remote {
+ public void addEntry(String name, Address address) throws
java.rmi.RemoteException;
+}
+</pre>
<p>A note about the name of the SDI. The name of the SDI is typically the name of
the portType. However, to construct the SDI, WSDL2Java needs information from both
the portType <b>and</b> the binding. (This is unfortunate and is a topic of
discussion for WSDL version 2.)
<p>JAX-RPC says (section 4.3.3): "The name of the Java interface is mapped
from the name attribute of the wsdl:portType element. ... If the mapping to
@@ -756,23 +735,24 @@
which are involved in dynamic invocation via the Service and Call objects.
The stub hides all that work for you.
<p>Given the following WSDL snippet:
-<div class="example"><br><font face="Courier New,Courier"><binding
name="AddressBookSOAPBinding"
-type="tns:AddressBook">
-<br> ...
-<br></binding></font></div>
+<pre class="example"><binding name="AddressBookSOAPBinding"
type="tns:AddressBook">
+ ...
+</binding></pre>
<p>WSDL2Java will generate:
-<div class="example"><br><font face="Courier New,Courier">public class
AddressBookSOAPBindingStub
-extends org.apache.axis.client.Stub implements AddressBook {
-<br> public AddressBookSOAPBindingStub()
-throws org.apache.axis.AxisFault {...}
-<br> public AddressBookSOAPBindingStub(URL
-endpointURL, javax.xml.rpc.Service service) throws org.apache.axis.AxisFault
-{..}
-<br> public AddressBookSOAPBindingStub(javax.xml.rpc.Service
-service) throws org.apache.axis.AxisFault {...}
-<br> public void addEntry(String
-name, Address address) throws RemoteException{...}
-<br>}</font></div>
+<pre class="example">public class AddressBookSOAPBindingStub extends
org.apache.axis.client.Stub
+ implements AddressBook {
+ public AddressBookSOAPBindingStub() throws
org.apache.axis.AxisFault
+ {...}
+
+ public AddressBookSOAPBindingStub(URL endpointURL,
+ javax.xml.rpc.Service service)
+ throws org.apache.axis.AxisFault
+ {...}
+<br> public AddressBookSOAPBindingStub(javax.xml.rpc.Service
service)
+ throws org.apache.axis.AxisFault
+ {...}
+<br> public void addEntry(String name, Address address) throws
RemoteException
+ {...}<br>}</pre>
<h4>
Services</h4>
Normally, a client program would not instantiate a stub directly.
@@ -780,25 +760,22 @@
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:
-<div class="example"><br><font face="Courier New,Courier"><service
name="AddressBookService">
-<br> <port name="AddressBook" binding="tns:AddressBookSOAPBinding">
-<br> <soap:address
location="http://localhost:8080/axis/services/AddressBook"/>
-<br> </port>
-<br></service></font></div>
+<pre class="example"><service name="AddressBookService">
+ <port name="AddressBook" binding="tns:AddressBookSOAPBinding">
+ <soap:address
location="http://localhost:8080/axis/services/AddressBook"/>
+ </port>
+</service></pre>
<p>WSDL2Java will generate the service interface:
-<div class="example"><br><font face="Courier New,Courier">public interface
AddressBookService
-extends javax.xml.rpc.Service {
-<br> public String getAddressBookAddress();
-<br> public AddressBook
-getAddressBook() throws javax.xml.rpc.ServiceException;
-<br> public AddressBook
-getAddressBook(URL portAddress) throws javax.xml.rpc.ServiceException;
-<br>}</font></div>
+<pre class="example">public interface AddressBookService extends
javax.xml.rpc.Service {
+ public String getAddressBookAddress();
+<br> public AddressBook getAddressBook() throws
javax.xml.rpc.ServiceException;
+<br> public AddressBook getAddressBook(URL portAddress) throws
javax.xml.rpc.ServiceException;
+}</pre>
<p>WSDL2Java will also generate the locator which implements this interface:
-<div class="example"><br><font face="Courier New,Courier">public class
AddressBookServiceLocator
-extends org.apache.axis.client.Service implements AddressBookService {
-<br> ...
-<br>}</font></div>
+<pre class="example">public class AddressBookServiceLocator extends
org.apache.axis.client.Service
+ implements AddressBookService {
+ ...
+}</pre>
<p>The service interface defines a get method for each port listed in the
service element of the WSDL. The locator is the implementation of this
service interface. It implements these get methods. It serves as
@@ -807,25 +784,19 @@
but you may also specify a different URL when you ask for the PortType.
<p>A typical usage of the stub classes would be as follows:
-<div class="example"><br><font face="Courier New,Courier">public class Tester
+<pre class="example">public class Tester
{
-<br> public static void main(String
-[] args) throws Exception {
-<br> // Make a service
-<br> AddressBookService
-service = new AddressBookServiceLocator();
-<br>
-<br>
-<br> // Now use the service
-to get a stub which implements the SDI.
-<br> AddressBook port
-= service.getAddressBook();
-<br>
-<br> // Make the actual call
-<br> Address address = new Address(...);
-<br> port.addEntry("Russell Butek", address);
-<br> }
-<br>}</font></div>
+ public static void main(String [] args) throws Exception {
+ // Make a service
+ AddressBookService service = new AddressBookServiceLocator();
+
+ // Now use the service to get a stub which implements the
SDI.
+ AddressBook port = service.getAddressBook();
+
+ // Make the actual call
+ Address address = new Address(...);
+ port.addEntry("Russell Butek", address);
+ }<br>}</pre>
<h4>
Server-side bindings</h4>
@@ -833,8 +804,7 @@
a <b>skeleton</b> is a Java framework for the server side. To make
skeleton classes, you just specify the "--skeleton" option to WSDL2Java.
For instance, using the AddressBook.wsdl as we had above:
-<div class="example"><br><font face="Courier New,Courier">% java
org.apache.axis.wsdl.WSDL2Java
---skeleton AddressBook.wsdl</font></div>
+<pre class="example">% java org.apache.axis.wsdl.WSDL2Java --skeleton
AddressBook.wsdl</pre>
<p>You will see that WSDL2Java generates all the classes that were generated
before for the client, but it generates a few new files:
<br>
@@ -877,27 +847,26 @@
actual service implementation. Its name is the binding name with
suffix "Skeleton". For example, for the AddressBook binding, WSDL2Java
will generate:
-<div class="example"><br><font face="Courier New,Courier">public class
AddressBookSOAPBindingSkeleton
-implements AddressBook,
-<br> org.apache.axis.wsdl.Skeleton {
-<br> private AddressBook impl;
-<br>
-<br> public AddressBookSOAPBindingSkeleton() {
-<br> this.impl = new
AddressBookSOAPBindingImpl();
-<br> }
-<br>
-<br> public AddressBookSOAPBindingSkeleton(AddressBook impl) {
-<br> this.impl = impl;
-<br> }
-<br>
-<br> public void addEntry(java.lang.String
-name, Address address) throws java.rmi.RemoteException
-<br> {
-<br> impl.addEntry(name, address);
-<br> }
-<br>}</font></div>
-<p>(The real skeleton is actually much richer. For brevity I'm just
-showing you the basic skeleton.)
+<pre class="example">public class AddressBookSOAPBindingSkeleton implements
AddressBook,
+
org.apache.axis.wsdl.Skeleton {
+ private AddressBook impl;
+
+ public AddressBookSOAPBindingSkeleton() {
+ this.impl = new
AddressBookSOAPBindingImpl();
+ }
+
+ public AddressBookSOAPBindingSkeleton(AddressBook impl) {
+ this.impl = impl;
+ }
+
+ public void addEntry(java.lang.String name, Address address)
+ throws java.rmi.RemoteException
+ {
+ impl.addEntry(name, address);
+ }
+}</pre>
+<p>(The real skeleton is actually much richer. For brevity we just show
+ you the basic skeleton.)
<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
@@ -905,19 +874,18 @@
invocation to the real implementation's addEntry method.
<p>Besides the skeleton, WSDL2Java also generates an implementation template
from the binding:
-<div class="example"><br><font face="Courier New,Courier">public class
AddressBookSOAPBindingImpl
-implements AddressBook {
-<br> public void addEntry(String
-name, Address address) throws java.rmi.RemoteException {
-<br> }
-<br>}</font></div>
+<pre class="example">public class AddressBookSOAPBindingImpl implements AddressBook
{
+<br> public void addEntry(String name, Address address)
+ throws java.rmi.RemoteException {
+ }
+}</pre>
<p>This template could actually be used as a test implementation but, as
you can see, it doesn't do anything. It is intended that the service
writer fill out the implementation from this template.
-<p>When WSDL2Java is asked to generate the implementation template (via
-the --skeleton flag), it will ONLY generate it if it does not already exist.
-If this implementation already exists, it will not be overwritten.
-<br>
+<p>When WSDL2Java is asked to generate the implementation template (via the
--skeleton
+ flag), it will ONLY generate it if it does not already exist. If this
+ implementation already exists, it will not be overwritten. <br>
+<p>
<h4>
Services</h4>
The tool also builds you a "deploy.wsdd" and an "undeploy.wsdd" for each
@@ -1018,16 +986,15 @@
Deploy either the skeleton (true) or the implementation (false) in
deploy.wsdd.
In other words, for "true" the service clause in the deploy.wsdd file will
look something like:
-<div class="example"><br><font face="Courier New,Courier"><service
name="AddressBook"
-provider="java:RPC">
-<br> <parameter name="className"
value="samples.addr.AddressBookSOAPBindingSkeleton"/>
-<br> ...
-<br></service></font></div>
+<pre class="example"><service name="AddressBook" provider="java:RPC">
+ <parameter name="className"
value="samples.addr.AddressBookSOAPBindingSkeleton"/>
+ ...
+</service></pre>
<p>and for "false" it would look like:
-<div class="example"><br><font face="Courier New,Courier"><service
name="AddressBook" provider="java:RPC">
-<br> <parameter name="className"
value="samples.addr.AddressBookSOAPBindingImpl"/>
-<br> ...
-<br> </service></font></div>
+<pre class="example"><service name="AddressBook" provider="java:RPC">
+ <parameter name="className"
value="samples.addr.AddressBookSOAPBindingImpl"/>
+ ...
+</service></pre>
<p>The default for this option is true. When you use this option, the
--server-side option is assumed, so you don't have to explicitly specify --server-side
as well.
<h4>
-N, --NStoPkg <argument>=<value></h4>
@@ -1137,17 +1104,14 @@
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="../samples/userguide/example6/WidgetPrice.java">samples/userguide/example6/WidgetPrice.java</a>):
-<div class="example"><br><font face="Courier New,Courier">package
samples.userguide.example6;
+<pre class="example">package samples.userguide.example6;
<br>/**
-<br> * Interface describing a web service
-to set and get Widget prices.
-<br> **/
-<br>public interface WidgetPrice {
-<br> public void setWidgetPrice(String
-widgetName, String price);
-<br> public String getWidgetPrice(String
-widgetName);
-<br>}</font></div>
+ * Interface describing a web service to set and get Widget prices.
+ **/
+public interface WidgetPrice {
+ public void setWidgetPrice(String widgetName, String price);
+ public String getWidgetPrice(String widgetName);
+}</pre>
<p><b>Note: </b>If you compile your class with debug information, Java2WSDL
will use the debug information to obtain the method parameter names.
<h4>
@@ -1155,7 +1119,7 @@
Use the Java2WSDL tool to create a WSDL file from the interface above.
<p>Here is an example invocation that produces the wsdl file (<tt>wp.wsdl</tt>)
from the interface described in the previous section:
-<div class="example"><br><font face="Courier New,Courier">% java
org.apache.axis.wsdl.Java2WSDL -o wp.wsdl
-l"http://localhost:8080/axis/services/WidgetPrice"; -n
"urn:Example6" -p"samples.userguide.example6" "urn:Example6"
samples.userguide.example6.WidgetPrice</font></div>
+<pre class="example">% java org.apache.axis.wsdl.Java2WSDL -o wp.wsdl
-l"http://localhost:8080/axis/services/WidgetPrice"; -n
"urn:Example6" -p"samples.userguide.example6" "urn:Example6"
samples.userguide.example6.WidgetPrice</pre>
<p>Where:
<ul>
<li>
@@ -1335,7 +1299,7 @@
Step 3: Create Bindings using WSDL2Java</h4>
Use the generated WSDL file to build the appropriate client/server bindings
for the web service (see <a href="#WSDL2Java: Building stubs, skeletons, and
data">WSDL2Java</a>):
-<div class="example"><br><font face="Courier New,Courier">% java
org.apache.axis.wsdl.WSDL2Java -o . -d Session -s -Nurn:Example6
samples.userguide.example6 wp.wsdl</font></div>
+<pre class="example">% java org.apache.axis.wsdl.WSDL2Java -o . -d Session -s
-Nurn:Example6 samples.userguide.example6 wp.wsdl</pre>
<p>This will generate the following files:
<ul>
<li>
