gdaniels 02/04/26 10:15:36
Modified: java/docs user-guide.html reference.html
Log:
More updates to user's guide, pull reference material into reference guide.
Revision Changes Path
1.60 +52 -485 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.59
retrieving revision 1.60
diff -u -r1.59 -r1.60
--- user-guide.html 24 Apr 2002 16:02:12 -0000 1.59
+++ user-guide.html 26 Apr 2002 17:15:36 -0000 1.60
@@ -29,24 +29,12 @@
Table of Contents</h3>
<ul>
-<li>
-<a href="#Introduction">Introduction</a></li>
-
-<li>
-<a href="#Installation">Installing Axis</a></li>
-
-<li>
-<a href="#ConsumingServices">Consuming Web Services with Axis</a></li>
-
-<li>
-<a href="#PublishingServices">Publishing Web Services with Axis</a></li>
-
-<li>
-<a href="#DataMapping">XML <-> Java Data Mapping in Axis</a></li>
-
-<li>
-<a href="#WSDL">Using WSDL with Axis</a></li>
-
+ <li> <a href="#Introduction">Introduction</a></li>
+ <li> <a href="#Installation">Installing Axis</a></li>
+ <li> <a href="#ConsumingServices">Consuming Web Services with Axis</a></li>
+ <li> <a href="#PublishingServices">Publishing Web Services with Axis</a></li>
+ <li> <a href="#DataMapping">XML <-> Java Data Mapping in Axis</a></li>
+ <li> <a href="#WSDL">Using WSDL with Axis</a></li>
<ul>
<li> <a href="#WSDL: Obtaining WSDL for deployed services">?WSDL:
Obtaining
WSDL for deployed services</a></li>
@@ -55,15 +43,9 @@
<li> <a href="#Java2WSDL: Building WSDL from Java">Java2WSDL: Building
WSDL from Java</a></li>
</ul>
-
-<li>
-<a href="#published interfaces">Published Interfaces</a></li>
-
-<li>
-<a href="#tcpmon">Using TCPMon</a></li>
-
-<li>
-<a href="#Glossary">Glossary</a></li>
+ <li> <a href="#published interfaces">Published Interfaces</a></li>
+ <li> <a href="#tcpmon">Appendix : Using TCPMon</a></li>
+ <li> <a href="#Glossary">Glossary</a></li>
</ul>
<h2>
@@ -609,8 +591,7 @@
<p>You can also generate WSDL files from existing Java classes (see <a
href="#Java2WSDL: Building WSDL from Java">Java2WSDL:
Building WSDL from Java</a> ).
<br>
-<h3>
-<a NAME="WSDL2Java: Building stubs, skeletons, and data"></a>WSDL2Java:
+<h3><a NAME="WSDL2Java: Building stubs, skeletons, and data"></a>WSDL2Java:
Building stubs, skeletons, and data types from WSDL</h3>
<h4>Client-side bindings</h4>
@@ -630,8 +611,6 @@
<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.</p>
-<br>
-<br>
<table BORDER COLS=2 WIDTH="100%" >
<tr>
<td><b>WSDL clause</b></td>
@@ -676,12 +655,11 @@
</tr>
</table>
-<h4>
-Types</h4>
-The Java class generated from a WSDL type will be named from the WSDL type.
+<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="../samples/addr/AddressBook.wsdl">Address Book sample</a>):
+the <a href="../samples/addr/AddressBook.wsdl">Address Book sample</a>):</p>
<pre class="example">
<xsd:complexType name="phone">
<xsd:all>
@@ -984,226 +962,16 @@
}</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.
+writer fill out the implementation from this template.</p>
<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. <br>
-<p>
-<h4>
-Services</h4>
-The tool also builds you a "deploy.wsdd" and an "undeploy.wsdd" for each
+ implementation already exists, it will not be overwritten.</p>
+<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.
-<br>
-<h4>
-Other WSDL2Java details</h4>
-<p>Usage: java org.apache.axis.wsdl.WSDL2Java [options] WSDL-URI
-<br>Options:
-<br> -h, --help
-<br>
-print this message and exit
-<br> -v, --verbose
-<br>
-print informational messages
-<br> -s, --server-side
-<br>
-emit server-side bindings for web service
-<br> -S, --skeletonDeploy <argument>
-<br>
-deploy skeleton (true) or implementation (false) in deploy.wsdd.
-<br>
-Default is false. Assumes --server-side.
-<br> -N, --NStoPkg
<argument>=<value>
-<br>
-mapping of namespace to package
-<br> -f, --fileNStoPkg <argument>
-<br>
-file of NStoPkg mappings (default NStoPkg.properties)
-<br> -p, --package <argument>
-<br>
-override all namespace to package mappings, use this package
-<br>
-name instead
-<br> -o, --output <argument>
-<br>
-output directory for emitted files
-<br> -d, --deployScope <argument>
-<br>
-add scope to deploy.xml: "Application", "Request", "Session"
-<br> -t, --testCase
-<br>
-emit junit testcase class for web service
-<br> -n, --noImports
-<br>
-only generate code for the immediate WSDL document
-<br> -a, --all
-<br>
-generate code for all elements, even unreferenced ones
-<br> -D, --Debug
-<br>
-print debug information
-<br> -F, --factory
-<argument>
-<br>
-name of the JavaWriterFactory class for extending Java generation functions
-<br>
-ompliant)
-<br> -O, --timeout <argument>
-<br>
-timeout in seconds (default is 45, specify -1 to disable)
-<br> -U, --user <argument>
-<br>
-username to access the WSDL-URI
-<br> -P, --password <argument>
-<br>
-password to access the WSDL-URI <br>
-<h4>
--h, --help</h4>
-Print the usage statement and exit
-<h4>
--v, --verbose</h4>
-See what the tool is generating as it is generating it.
-<h4>
--s, --server-side</h4>
-Emit the server-side bindings for the web service:
-<ul>
-<li>
-a skeleton class named <bindingName>Skeleton. This may or may
-not be emitted (see -S, --skeletonDeploy).</li>
-
-<li>
-an implementation template class named <bindingName>Impl. Note
-that, if this class already exists, then it is not emitted.</li>
-
-<li>
-deploy.wsdd</li>
-
-<li>
-undeploy.wsdd</li>
-</ul>
-
-<h4>
--S, --skeletonDeploy <argument></h4>
-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:
-<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:
-<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 false. 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>
-By default, package names are generated from the namespace strings in the
-WSDL document in a magical manner (typically, if the namespace is of the
-form "http://x.y.com"; or "urn:x.y.com" the corresponding package will be
-"com.y.x"). If this magic is not what you want, you can provide your
-own mapping using the --NStoPkg argument, which can be repeated as often
-as necessary, once for each unique namespace mapping. For example,
-if there is a namespace in the WSDL document called "urn:AddressFetcher2",
-and you want files generated from the objects within this namespace to
-reside in the package samples.addr, you would provide the following option
-to WSDL2Java:
-<pre>--NStoPkg urn:AddressFetcher2=samples.addr</pre>
-(Note that if you use the short option tag, "-N", then there must not be
-a space between "-N" and the namespace.)
-<br>
-<h4>
--f, --fileNStoPkg <argument></h4>
-If there are a number of namespaces in the WSDL document, listing a mapping
-for them all could become tedious. To help keep the command line
-terse, WSDL2Java will also look for mappings in a properties file.
-By default, this file is named "NStoPkg.properties" and it must reside
-in the default package (ie., no package). But you can explicitly
-provide your own file using the --fileNStoPkg option.
-<p>The entries in this file are of the same form as the arguments to the
---NStoPkg command line option. For example, instead of providing
-the command line option as above, we could provide the same information
-in NStoPkg.properties:
-<pre>urn\:AddressFetcher2=samples.addr</pre>
-(Note that the colon must be escaped in the properties file.)
-<p>If an entry for a given mapping exists both on the command line and
-in the properties file, the command line entry takes precedence.
-<h4>
--p, --package <argument></h4>
-This is a shorthand option to map all namespaces in a WSDL document to
-the same Java package name. This can be useful, but dangerous.
-You must make sure that you understand the effects of doing this.
-For instance there may be multiple types with the same name in different
-namespaces. It is an error to use the --NStoPkg switch and --package
-at the same time.
-<h4>
--o, --output <argument></h4>
-The root directory for all emitted files.
-<h4>
--d, --deployScope <argument></h4>
-Add scope to deploy.wsdd: "Application", "Request", or "Session".
-If this option does not appear, no scope tag appears in deploy.wsdd, which
-the AXIS runtime defaults to "Request".
-<h4>
--t, --testCase</h4>
-Generate a client-side JUnit test case. This test case can stand
-on its own, but it doesn't really do anything except pass default values
-(null for objects, 0 or false for primitive types). Like the generated
-implementation file, the generated test case file could be considered a
-template that you may fill in.
-<h4>
--n, --noImports</h4>
-Only generate code for the WSDL document that appears on the command line.
-The default behaviour is to generate files for all WSDL documents, the
-immediate one and all imported ones.
-<h4>
--a, --all</h4>
-Generate code for all elements, even unreferenced ones. By default,
-WSDL2Java only generates code for those elements in the WSDL file that
-are referenced.
-<p>A note about what it means to be referenced. We cannot simply
-say: start with the services, generate all bindings referenced by
-the service, generated all portTypes referenced by the referenced bindings,
-etc. What if we're generating code from a WSDL file that only contains
-portTypes, messages, and types? If WSDL2Java used service as an anchor,
-and there's no service in the file, then nothing will be generated.
-So the anchor is the lowest element that exists in the WSDL file in the
-order:
-<br>types
-<br>portTypes
-<br>bindings
-<br>services
-<p>For example, if a WSDL file only contained types, then all the listed
-types would be generated. But if a WSDL file contained types and
-a portType, then that portType will be generated and only those types that
-are referenced by that portType.
-<h4>
--D, --Debug</h4>
-Print debug information, which currently is WSDL2Java's symbol table.
-<h4>
--T, --typeMappingVersion <argument></h4>
-Indicate 1.1 or 1.2. The default is 1.2 (SOAP 1.2 JAX-RPC compliant).
-<h4>
--F, --factory <argument></h4>
-Used to extend the functionality of the WSDL2Java emitter. The argument
-is the name of a class which extends JavaWriterFactory.
-<h4> -U, --user <argument></h4>
-This username is used in resolving the WSDL-URI provided as the input to
-WSDL2Java. If the URI contains a username, this will override the command
-line switch. An example of a URL with a username and password is:
-<code>http://user:password@hostname:port/path/to/service?WSDL</code><br>
-<h4> -P, --password <argument></h4>
- This password is used in resolving the WSDL-URI provided as the input to WSDL2Java.
- If the URI contains a password, this will override the command
-line switch.<br>
-
-<br>
-<h3>
-<a NAME="Java2WSDL: Building WSDL from Java"></a>Java2WSDL: Building WSDL
+compiled the code, and made the classes available to your Axis engine.</p>
+<h3><a NAME="Java2WSDL: Building WSDL from Java"></a>Java2WSDL: Building WSDL
from Java</h3>
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.
<br>
@@ -1253,188 +1021,8 @@
represent the classes and any nested/inherited types. The tool supports
JAX-RPC complex types (bean classes), extension classes, enumeration classes,
arrays and Holder classes.
-<p>The Java2WSDL tool has many additional options which are detailed in
-the next section.
-<h5>
-<a NAME="Java2WSDL Details"></a>Java2WSDL Details</h5>
-Here is the help message generated from the current tool:
-<p><tt><font color="#993366">Java2WSDL emitter</font></tt>
-<br><tt><font color="#993366">Usage: java org.apache.axis.wsdl.Java2WSDL
-[options] class-of-portType</font></tt>
-<br><tt><font color="#993366">Options:</font></tt>
-<br><tt><font color="#993366">
--h, --help</font></tt>
-<br><tt><font
color="#993366">
-print this message and exit</font></tt>
-<br><tt><font color="#993366">
--o, --output <argument></font></tt>
-<br><tt><font
color="#993366">
-output WSDL filename</font></tt>
-<br><tt><font color="#993366">
--l, --location <argument></font></tt>
-<br><tt><font
color="#993366">
-service location url</font></tt>
-<br><tt><font color="#993366">
--P, --portTypeName <argument></font></tt>
-<br><tt><font
color="#993366">
-portType name (obtained from class-of-portType if not specified)</font></tt>
-<br><tt><font color="#993366">
--S, --serviceElementName <argument></font></tt>
-<br><tt><font
color="#993366">
-service element name (defaults to servicePortName value + "Service")</font></tt>
-<br><tt><font color="#993366">
--s, --servicePortName <argument></font></tt>
-<br><tt><font
color="#993366">
-service port name (obtained from --location if not specified)</font></tt>
-<br><tt><font color="#993366">
--n, --namespace <argument></font></tt>
-<br><tt><font
color="#993366">
-target namespace</font></tt>
-<br><tt><font color="#993366">
--p, --PkgtoNS <argument>=<value></font></tt>
-<br><tt><font
color="#993366">
-package=namespace, name value pairs</font></tt>
-<br><tt><font color="#993366">
--m, --methods <argument></font></tt>
-<br><tt><font
color="#993366">
-space or comma separated list of methods to export</font></tt>
-<br><tt><font color="#993366">
--a, --all</font></tt>
-<br><tt><font
color="#993366">
-look for allowed methods in inherited class</font></tt>
-<br><tt><font color="#993366">
--w, --outputWsdlMode <argument></font></tt>
-<br><tt><font
color="#993366">
-output WSDL mode: All, Interface, Implementation</font></tt>
-<br><tt><font color="#993366">
--L, --locationImport <argument></font></tt>
-<br><tt><font
color="#993366">
-location of interface WSDL</font></tt>
-<br><tt><font color="#993366">
--N, --namespaceImpl <argument></font></tt>
-<br><tt><font
color="#993366">
-target namespace for implementation WSDL</font></tt>
-<br><tt><font color="#993366">
--O, --outputImpl <argument></font></tt>
-<br><tt><font
color="#993366">
-output Implementation WSDL filename, setting this causes --outputWsdlMode
-to be ignored</font></tt>
-<br><tt><font color="#993366">
--f, --factory <argument></font></tt>
-<br><tt><font
color="#993366">
-name of the Java2WSDLFactory class for extending WSDL generation
functions</font></tt>
-<br><tt><font color="#993366">
--i, --implClass <argument></font></tt>
-<br><tt><font
color="#993366">
-optional class that contains implementation of methods in</font></tt>
-<br><tt><font
color="#993366">
-class-of-portType. The debug information in the class is used</font></tt>
-<br><tt><font
color="#993366">
-to obtain the method parameter names, which are used to set</font></tt>
-<br><tt><font
color="#993366">
-the WSDL part names.</font></tt>
-<br><tt><font color="#993366">
--x, --exclude <argument></font></tt>
-<br><tt><font
color="#993366">
-space or comma separated list of methods not to export</font></tt>
-<br><tt><font color="#993366">
--c, --stopClasses <argument></font></tt>
-<br><tt><font
color="#993366">
-space or comma separated list of class names which stop inheritance search
</font></tt>
-<br><tt><font
color="#993366">
-if --all switch is enabled</font></tt>
-<br><tt><font color="#993366">
--T, --typeMappingVersion <argument></font></tt>
-<br><tt><font
color="#993366">
-indicate 1.1 or 1.2. The default is 1.2 (SOAP 1.2 JAX-RPC compliant)</font></tt>
-
-<br><tt><font color="#993366">Details:</font></tt>
-<br><tt><font color="#993366"> portType element name=
-<.portTypeName value> OR <class-of-portType name></font></tt>
-<br><tt><font color="#993366"> binding element
-name= <--servicePortName value>SoapBinding</font></tt>
-<br><tt><font color="#993366"> service element
-name= <--serviceElementName value> OR <portTypeName value>Service</font></tt>
-<br><tt><font color="#993366"> port element
-name= <--servicePortName value></font></tt>
-<br><tt><font color="#993366"> address
location = <--location
-value></font></tt>
-<br>
-<p><b>-h , --help</b>
-<br>Prints the help message.
-<p><b>-o, --output <WSDL file></b>
-<br>Indicates the name of the output WSDL file. If not specified,
-a suitable default WSDL file is written into the current directory.
-<p><b>-l, --location <location></b>
-<br>Indicates the url of the location of the service. The name after
-the last slash or backslash is the name of the service port (unless overriden
-by the -s option). The service port address location attribute is
-assigned the specified value.
-<p><b>-p, --portTypeName <name></b>
-<br>Indicates the name to use use for the portType element. If not specified,
-the class-of-portType name is used.
-<p><b>-s, -serviceElementName <name></b>
-<br>Indicates the name of the service element. If not specified, the service
-element is the <portTypeName>Service.
-<p><b>-s, -servicePortName <name></b>
-<br>Indicates the name of the service port. If not specified, the service
-port name is derived from the --location value.
-<p><b>-n, --namespace <target namespace></b>
-<br>Indicates the name of the target namespace of the WSDL.
-<p><b>-p, --PkgToNS <package> <namespace></b>
-<br>Indicates the mapping of a package to a namespace. If a package
-is encountered that does not have a namespace, the Java2WSDL emitter will
-generate a suitable namespace name. This option may be specified
-multiple times.
-<p><b>-m, --methods <arguments></b>
-<br>If this option is specified, only the indicated methods in your interface
-class will be exported into the WSDL file. The methods list must
-be comma separated. If not specified, all methods declared in the
-interface class will be exported into the WSDL file.
-<p><b>-a, --all</b>
-<br>If this option is specified, the Java2WSDL parser will look into extended
-classes to determine the list of methods to export into the WSDL file.
-<p><b>-w, --outputWSDLMode <mode></b>
-<br>Indicates the kind of WSDL to generate. Accepted values are:
-<ul>
-<li>
-All --- (default) Generates wsld containing both interface and implementation
-WSDL constructs.</li>
-
-<li>
-Interface --- Generates a WSDL containing the interface constructs (no
-service element).</li>
-
-<li>
-Implementation -- Generates a WSDL containing the implementation.
-The interface WSDL is imported via the -L option.</li>
-</ul>
-<b>-L, --locationImport <url></b>
-<br>Used to indicate the location of the interface WSDL when generating
-an implementation WSDL.
-<p><b>-N, --namespaceImpl <namespace></b>
-<br>Namespace of the implementation WSDL.
-<p><b>-O, --outputImpl <WSDL file></b>
-<br>Use this option to indicate the name of the output implementation WSDL
-file. If specified, Java2WSDL will produce interface and implementation
-WSDL files. If this option is used, the -w option is ignored.
-<p><b>-f, --factory <class></b>
-<br>(No longer used.)
-<p><b>-i, --implClass <impl-class></b>
-<br>
-Sometimes extra information is avalable in the implementation class file.
-Use this option to specify the implementation class.
-<p><b>-f, --factory <class></b>
-<br>(No longer used.)
-<p><b>-x, --exclude <list></b>
-<br>
-List of methods to not exclude from the wsdl file.
-<p><b>-c, --stopClasses <list></b>
-<br>
-List of classes which stop the Java2WSDL inheritance search.
-<p><b>-T, --typeMappingVersion <version></b>
-<br>
-Choose the default type mapping registry to use. Either 1.1 or 1.2.
+<p>The Java2WSDL tool has many additional options which are detailed in the <a
href="reference.html#Java2WSDL">reference
+ guide</a>.
<h4>
Step 3: Create Bindings using WSDL2Java</h4>
Use the generated WSDL file to build the appropriate client/server bindings
@@ -1442,43 +1030,28 @@
<pre class="example">% java org.apache.axis.wsdl.WSDL2Java -o . -d Session -s -S
true -Nurn:Example6 samples.userguide.example6 wp.wsdl</pre>
<p>This will generate the following files:
<ul>
-<li>
-<b><tt>WidgetPriceSoapBindingImpl.java</tt></b> : Java file containing
-the default server implementation of the WidgetPrice web service.</li>
-
-<br>You will need to modify the *SoapBindingImpl file to add your implementation
-(see <a
href="../samples/userguide/example6/WidgetPriceSoapBindingImpl.java">../samples/userguide/example6/WidgetPriceSoapBindingImpl.java</a>
-).
-<li>
-<b><tt>WidgetPrice.java</tt></b>: New interface file that contains
-the appropriate <b><tt>java.rmi.Remote</tt></b> usages.</li>
-
-<li>
-<b><tt>WidgetPriceService.java</tt></b>: Java file containing the client
-side service interface.</li>
-
-<li>
-<b><tt>WidgetPriceServiceLocator.java</tt></b>: Java file containing the client
side service implementation class.</li>
-
-<li>
-<b><tt>WidgetPriceSoapBindingSkeleton.java</tt></b>: Server side skeleton.</li>
-
-<li>
-<b><tt>WidgetPriceSoapBindingStub.java</tt></b>: Client side stub.</li>
-
-<li>
-<b><tt>deploy.xml</tt></b>: Deployment descriptors</li>
-
-<li>
-<b><tt>undeploy.xml</tt></b>: Undeploy descriptors</li>
-
-<li>
-(data types): Java files will be produced for all of the other types
-and holders necessary for the web service. There are no additional
-files for the WidgetPrice web service.</li>
+ <li> <b><tt>WidgetPriceSoapBindingImpl.java</tt></b> : Java file containing
+ the default server implementation of the WidgetPrice web service.</li>
+ <br>
+ You will need to modify the *SoapBindingImpl file to add your implementation
+ (see <a
href="../samples/userguide/example6/WidgetPriceSoapBindingImpl.java">../samples/userguide/example6/WidgetPriceSoapBindingImpl.java</a>
+ ).
+ <li> <b><tt>WidgetPrice.java</tt></b>: New interface file that contains
+ the appropriate <b><tt>java.rmi.Remote</tt></b> usages.</li>
+ <li> <b><tt>WidgetPriceService.java</tt></b>: Java file containing the client
+ side service interface.</li>
+ <li> <b><tt>WidgetPriceServiceLocator.java</tt></b>: Java file containing the
+ client side service implementation class.</li>
+ <li> <b><tt>WidgetPriceSoapBindingSkeleton.java</tt></b>: Server side
skeleton.</li>
+ <li> <b><tt>WidgetPriceSoapBindingStub.java</tt></b>: Client side stub.</li>
+ <li> <b><tt>deploy.wsdd</tt></b>: Deployment descriptor</li>
+ <li> <b><tt>undeploy.wsdd</tt></b>: Undeployment descriptor</li>
+ <li> (data types): Java files will be produced for all of the other types
+ and holders necessary for the web service. There are no additional files
+ for the WidgetPrice web service.</li>
</ul>
-Now you have all of the necessary files to build your client/server side
-code and deploy the web service!
+<p>Now you have all of the necessary files to build your client/server side code
+ and deploy the web service!</p>
<h2>
<a NAME="published interfaces"></a>Published Axis Interfaces</h2>
Although you may use any of the interfaces and classes present in Axis, you need to
@@ -1598,8 +1171,7 @@
<li>org.apache.axis.wsdl.Java2WSDL</li>
</ul>
</ul>
-<h2>
-<a NAME="tcpmon"></a>Using the Axis TCP Monitor (tcpmon)</h2>
+<h2> <a NAME="tcpmon"></a>Appendix : Using the Axis TCP Monitor (tcpmon)</h2>
The included "tcpmon" utility can be found in the org.apache.axis.utils
package. To run it from the command line:
<pre>% java org.apache.axis.utils.tcpmon [listenPort targetHost targetPort]</pre>
@@ -1623,19 +1195,14 @@
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>The "resend" button will resend the request you are currently viewing,
-and record a new response. This is particularly handy in that you can edit
-the XML in the request window before resending - so you can use this as
-a great tool for testing the effects of different XML on SOAP servers.
-Note that you may need to change the content-length HTTP header value
-before resending an edited request.
-<dl>
-<dt>
-</dt>
-</dl>
-<a NAME="Glossary"></a>
-<h2>
-Glossary</h2>
+<p>The "resend" button will resend the request you are currently viewing, and
+ record a new response. This is particularly handy in that you can edit the XML
+ in the request window before resending - so you can use this as a great tool
+ for testing the effects of different XML on SOAP servers. Note that you may
+ need to change the content-length HTTP header value before resending an edited
+ request.
+<a NAME="Glossary">
+<h2>Glossary</h2></a>
<dl>
<dt> <i>Handler</i></dt>
@@ -1654,7 +1221,7 @@
this means calling a method on some back-end service object. The two commonly
used providers are RPCProvider and MsgProvider, both in the
org.apache.axis.providers.java
package.</dd>
- <dt> </dt>
+
</dl>
</body>
1.3 +390 -13 xml-axis/java/docs/reference.html
Index: reference.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/reference.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- reference.html 15 Mar 2002 10:19:35 -0000 1.2
+++ reference.html 26 Apr 2002 17:15:36 -0000 1.3
@@ -18,25 +18,391 @@
<body bgcolor="#ffffff" text="#000000">
<h1 align="center"><IMG height=96 src="axis.jpg" width=176></h1>
<h1>Axis Reference Guide</h1>
-<p><i>Beta 1 Version</i></p>
+<p><i>Beta 2 Version</i></p>
<h3>Table of Contents</h3>
-
-<h2><a name="DeploymentReference"></a>Deployment Reference</h2>
+<ul>
+ <li><a href="#Tools">Tools Reference</a></li>
+ <ul>
+ <li><a href="#WSDL2Java">WSDL2Java</a></li>
+ <li><a href="#Java2WSDL">Java2WSDL</a></li>
+ </ul>
+ <li><a href="#Deployment">Deployment (WSDD) Reference</a></li>
+</ul>
+<h2> <a name="Tools"></a>Tools Reference</h2>
+<h3><a name="WSDL2Java"></a>WSDL2Java Reference</h3>
+<h4>Other WSDL2Java details</h4>
+<p>Usage: java org.apache.axis.wsdl.WSDL2Java [options] WSDL-URI <br>
+ Options: <br>
+ -h, --help <br>
+
+ print this message and exit <br>
+ -v, --verbose <br>
+
+ print informational messages <br>
+ -s, --server-side <br>
+
+ emit server-side bindings for web service <br>
+ -S, --skeletonDeploy <argument>
+ <br>
+
+ deploy skeleton (true) or implementation (false) in deploy.wsdd. <br>
+
+ Default is false. Assumes --server-side. <br>
+ -N, --NStoPkg <argument>=<value>
+ <br>
+
+ mapping of namespace to package <br>
+ -f, --fileNStoPkg <argument> <br>
+
+ file of NStoPkg mappings (default NStoPkg.properties) <br>
+ -p, --package <argument> <br>
+
+ override all namespace to package mappings, use this package <br>
+
+ name instead <br>
+ -o, --output <argument> <br>
+
+ output directory for emitted files <br>
+ -d, --deployScope <argument> <br>
+
+ add scope to deploy.xml: "Application", "Request", "Session" <br>
+ -t, --testCase <br>
+
+ emit junit testcase class for web service <br>
+ -n, --noImports <br>
+
+ only generate code for the immediate WSDL document <br>
+ -a, --all <br>
+
+ generate code for all elements, even unreferenced ones <br>
+ -D, --Debug <br>
+
+ print debug information <br>
+ -F, --factory <argument> <br>
+
+ name of the JavaWriterFactory class for extending Java generation functions
+ <br>
+
+ ompliant) <br>
+ -O, --timeout <argument> <br>
+
+ timeout in seconds (default is 45, specify -1 to disable) <br>
+ -U, --user <argument> <br>
+
+ username to access the WSDL-URI <br>
+ -P, --password <argument> <br>
+
+ password to access the WSDL-URI <br>
+
+<h4> -h, --help</h4>
+Print the usage statement and exit
+<h4> -v, --verbose</h4>
+See what the tool is generating as it is generating it.
+<h4> -s, --server-side</h4>
+Emit the server-side bindings for the web service:
+<ul>
+ <li> a skeleton class named <bindingName>Skeleton. This may or may
+ not be emitted (see -S, --skeletonDeploy).</li>
+ <li> an implementation template class named <bindingName>Impl. Note
+ that, if this class already exists, then it is not emitted.</li>
+ <li> deploy.wsdd</li>
+ <li> undeploy.wsdd</li>
+</ul>
+<h4> -S, --skeletonDeploy <argument></h4>
+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:
+<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:
+<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 false. 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>
+By default, package names are generated from the namespace strings in the WSDL
+document in a magical manner (typically, if the namespace is of the form
"http://x.y.com";
+or "urn:x.y.com" the corresponding package will be "com.y.x"). If this magic
+is not what you want, you can provide your own mapping using the --NStoPkg
argument,
+which can be repeated as often as necessary, once for each unique namespace
mapping.
+For example, if there is a namespace in the WSDL document called
"urn:AddressFetcher2",
+and you want files generated from the objects within this namespace to reside
+in the package samples.addr, you would provide the following option to WSDL2Java:
+<pre>--NStoPkg urn:AddressFetcher2=samples.addr</pre>
+(Note that if you use the short option tag, "-N", then there must not be a space
+between "-N" and the namespace.) <br>
+
+<h4> -f, --fileNStoPkg <argument></h4>
+If there are a number of namespaces in the WSDL document, listing a mapping for
+them all could become tedious. To help keep the command line terse, WSDL2Java
+will also look for mappings in a properties file. By default, this file
+is named "NStoPkg.properties" and it must reside in the default package (ie.,
+no package). But you can explicitly provide your own file using the
--fileNStoPkg
+option.
+<p>The entries in this file are of the same form as the arguments to the --NStoPkg
+ command line option. For example, instead of providing the command line
+ option as above, we could provide the same information in NStoPkg.properties:
+<pre>urn\:AddressFetcher2=samples.addr</pre>
+(Note that the colon must be escaped in the properties file.)
+<p>If an entry for a given mapping exists both on the command line and in the
+ properties file, the command line entry takes precedence.
+<h4> -p, --package <argument></h4>
+This is a shorthand option to map all namespaces in a WSDL document to the same
+Java package name. This can be useful, but dangerous. You must make
+sure that you understand the effects of doing this. For instance there may
+be multiple types with the same name in different namespaces. It is an error
+to use the --NStoPkg switch and --package at the same time.
+<h4> -o, --output <argument></h4>
+The root directory for all emitted files.
+<h4> -d, --deployScope <argument></h4>
+Add scope to deploy.wsdd: "Application", "Request", or "Session". If this
+option does not appear, no scope tag appears in deploy.wsdd, which the AXIS runtime
+defaults to "Request".
+<h4> -t, --testCase</h4>
+Generate a client-side JUnit test case. This test case can stand on its
+own, but it doesn't really do anything except pass default values (null for
objects,
+0 or false for primitive types). Like the generated implementation file,
+the generated test case file could be considered a template that you may fill
+in.
+<h4> -n, --noImports</h4>
+Only generate code for the WSDL document that appears on the command line.
+The default behaviour is to generate files for all WSDL documents, the immediate
+one and all imported ones.
+<h4> -a, --all</h4>
+Generate code for all elements, even unreferenced ones. By default, WSDL2Java
+only generates code for those elements in the WSDL file that are referenced.
+<p>A note about what it means to be referenced. We cannot simply say:
+ start with the services, generate all bindings referenced by the service,
generated
+ all portTypes referenced by the referenced bindings, etc. What if we're
+ generating code from a WSDL file that only contains portTypes, messages, and
+ types? If WSDL2Java used service as an anchor, and there's no service
+ in the file, then nothing will be generated. So the anchor is the lowest
+ element that exists in the WSDL file in the order: <br>
+<ol>
+ <li>types
+ <li>portTypes
+ <li>bindings
+ <li>services
+</ol>
+<p>For example, if a WSDL file only contained types, then all the listed types
+ would be generated. But if a WSDL file contained types and a portType,
+ then that portType will be generated and only those types that are referenced
+ by that portType.
+<h4> -D, --Debug</h4>
+Print debug information, which currently is WSDL2Java's symbol table.
+<h4> -T, --typeMappingVersion <argument></h4>
+Indicate 1.1 or 1.2. The default is 1.2 (SOAP 1.2 JAX-RPC compliant).
+<h4> -F, --factory <argument></h4>
+Used to extend the functionality of the WSDL2Java emitter. The argument is the
+name of a class which extends JavaWriterFactory.
+<h4> -U, --user <argument></h4>
+This username is used in resolving the WSDL-URI provided as the input to WSDL2Java.
+ If the URI contains a username, this will override the command line switch.
+ An example of a URL with a username and password is:
<code>http://user:password@hostname:port/path/to/service?WSDL</code><br>
+<h4> -P, --password <argument></h4>
+This password is used in resolving the WSDL-URI provided as the input to WSDL2Java.
+ If the URI contains a password, this will override the command line
switch.
+<h3><a name="Java2WSDL"></a>Java2WSDL Reference</h3>
+<p>Here is the help message generated from the current tool: </p>
+<p><tt><font color="#993366">Java2WSDL emitter</font></tt> <br>
+ <tt><font color="#993366">Usage: java org.apache.axis.wsdl.Java2WSDL [options]
+ class-of-portType</font></tt> <br>
+ <tt><font color="#993366">Options:</font></tt> <br>
+ <tt><font color="#993366"> -h,
--help</font></tt>
+ <br>
+ <tt><font
color="#993366">
+ print this message and exit</font></tt> <br>
+ <tt><font color="#993366"> -o, --output
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ output WSDL filename</font></tt> <br>
+ <tt><font color="#993366"> -l,
--location
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ service location url</font></tt> <br>
+ <tt><font color="#993366"> -P,
--portTypeName
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ portType name (obtained from class-of-portType if not specified)</font></tt>
+ <br>
+ <tt><font color="#993366"> -S,
--serviceElementName
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ service element name (defaults to servicePortName value + "Service")</font></tt>
+ <br>
+ <tt><font color="#993366"> -s,
--servicePortName
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ service port name (obtained from --location if not specified)</font></tt> <br>
+ <tt><font color="#993366"> -n,
--namespace
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ target namespace</font></tt> <br>
+ <tt><font color="#993366"> -p,
--PkgtoNS
+ <argument>=<value></font></tt> <br>
+ <tt><font
color="#993366">
+ package=namespace, name value pairs</font></tt> <br>
+ <tt><font color="#993366"> -m,
--methods
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ space or comma separated list of methods to export</font></tt> <br>
+ <tt><font color="#993366"> -a,
--all</font></tt>
+ <br>
+ <tt><font
color="#993366">
+ look for allowed methods in inherited class</font></tt> <br>
+ <tt><font color="#993366"> -w,
--outputWsdlMode
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ output WSDL mode: All, Interface, Implementation</font></tt> <br>
+ <tt><font color="#993366"> -L,
--locationImport
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ location of interface WSDL</font></tt> <br>
+ <tt><font color="#993366"> -N,
--namespaceImpl
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ target namespace for implementation WSDL</font></tt> <br>
+ <tt><font color="#993366"> -O,
--outputImpl
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ output Implementation WSDL filename, setting this causes --outputWsdlMode to
+ be ignored</font></tt> <br>
+ <tt><font color="#993366"> -f,
--factory
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ name of the Java2WSDLFactory class for extending WSDL generation
functions</font></tt>
+ <br>
+ <tt><font color="#993366"> -i,
--implClass
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ optional class that contains implementation of methods in</font></tt> <br>
+ <tt><font
color="#993366">
+ class-of-portType. The debug information in the class is used</font></tt>
+ <br>
+ <tt><font
color="#993366">
+ to obtain the method parameter names, which are used to set</font></tt> <br>
+ <tt><font
color="#993366">
+ the WSDL part names.</font></tt> <br>
+ <tt><font color="#993366"> -x,
--exclude
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ space or comma separated list of methods not to export</font></tt> <br>
+ <tt><font color="#993366"> -c,
--stopClasses
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ space or comma separated list of class names which stop inheritance search
</font></tt>
+ <br>
+ <tt><font
color="#993366">
+ if --all switch is enabled</font></tt> <br>
+ <tt><font color="#993366"> -T,
--typeMappingVersion
+ <argument></font></tt> <br>
+ <tt><font
color="#993366">
+ indicate 1.1 or 1.2. The default is 1.2 (SOAP 1.2 JAX-RPC compliant)</font></tt>
+ <br>
+ <tt><font color="#993366">Details:</font></tt> <br>
+ <tt><font color="#993366"> portType element name= <.portTypeName
+ value> OR <class-of-portType name></font></tt> <br>
+ <tt><font color="#993366"> binding element name=
<--servicePortName
+ value>SoapBinding</font></tt> <br>
+ <tt><font color="#993366"> service element name=
<--serviceElementName
+ value> OR <portTypeName value>Service</font></tt> <br>
+ <tt><font color="#993366"> port element name=
+ <--servicePortName value></font></tt> <br>
+ <tt><font color="#993366"> address
location =
+ <--location value></font></tt> <br>
+
+<p><b>-h , --help</b> <br>
+ Prints the help message.
+<p><b>-o, --output <WSDL file></b> <br>
+ Indicates the name of the output WSDL file. If not specified, a suitable
+ default WSDL file is written into the current directory.
+<p><b>-l, --location <location></b> <br>
+ Indicates the url of the location of the service. The name after the last
+ slash or backslash is the name of the service port (unless overriden by the
+ -s option). The service port address location attribute is assigned the
+ specified value.
+<p><b>-p, --portTypeName <name></b> <br>
+ Indicates the name to use use for the portType element. If not specified, the
+ class-of-portType name is used.
+<p><b>-s, -serviceElementName <name></b> <br>
+ Indicates the name of the service element. If not specified, the service
+ element is the <portTypeName>Service.
+<p><b>-s, -servicePortName <name></b> <br>
+ Indicates the name of the service port. If not specified, the service
+ port name is derived from the --location value.
+<p><b>-n, --namespace <target namespace></b> <br>
+ Indicates the name of the target namespace of the WSDL.
+<p><b>-p, --PkgToNS <package> <namespace></b> <br>
+ Indicates the mapping of a package to a namespace. If a package is
encountered
+ that does not have a namespace, the Java2WSDL emitter will generate a suitable
+ namespace name. This option may be specified multiple times.
+<p><b>-m, --methods <arguments></b> <br>
+ If this option is specified, only the indicated methods in your interface class
+ will be exported into the WSDL file. The methods list must be comma
separated.
+ If not specified, all methods declared in the interface class will be exported
+ into the WSDL file.
+<p><b>-a, --all</b> <br>
+ If this option is specified, the Java2WSDL parser will look into extended classes
+ to determine the list of methods to export into the WSDL file.
+<p><b>-w, --outputWSDLMode <mode></b> <br>
+ Indicates the kind of WSDL to generate. Accepted values are:
+<ul>
+ <li> All --- (default) Generates wsld containing both interface and
implementation
+ WSDL constructs.</li>
+ <li> Interface --- Generates a WSDL containing the interface constructs (no
+ service element).</li>
+ <li> Implementation -- Generates a WSDL containing the implementation.
+ The interface WSDL is imported via the -L option.</li>
+</ul>
+<b>-L, --locationImport <url></b> <br>
+Used to indicate the location of the interface WSDL when generating an
implementation
+WSDL.
+<p><b>-N, --namespaceImpl <namespace></b> <br>
+ Namespace of the implementation WSDL.
+<p><b>-O, --outputImpl <WSDL file></b> <br>
+ Use this option to indicate the name of the output implementation WSDL
file.
+ If specified, Java2WSDL will produce interface and implementation WSDL
files.
+ If this option is used, the -w option is ignored.
+<p><b>-f, --factory <class></b> <br>
+ (No longer used.)
+<p><b>-i, --implClass <impl-class></b> <br>
+ Sometimes extra information is avalable in the implementation class file. Use
+ this option to specify the implementation class.
+<p><b>-f, --factory <class></b> <br>
+ (No longer used.)
+<p><b>-x, --exclude <list></b> <br>
+ List of methods to not exclude from the wsdl file.
+<p><b>-c, --stopClasses <list></b> <br>
+ List of classes which stop the Java2WSDL inheritance search.
+<p><b>-T, --typeMappingVersion <version></b> <br>
+ Choose the default type mapping registry to use. Either 1.1 or 1.2.</p>
+<h2><a name="Deployment"></a>Deployment (WSDD) Reference</h2>
Note : all the elements referred to in this section are in the WSDD namespace,
-namely "http://wsdd".
+namely "http://xml.apache.org/axis/wsdd/".
<dl>
<dt><b><font face="Courier New, Courier, mono"><deployment></font></b></dt>
<dd>The root element of the deployment document which tells the Axis engine
- that this is a deployment. Must be in the "AdminService"
namespace.</dd>
+ that this is a deployment. A deployment document may represent EITHER a
complete
+ engine configuration OR a set of components to deploy into an active
engine.</dd>
<dt> </dt>
<dt><b><font face="Courier New, Courier,
mono"><undeployment></font></b></dt>
<dd>The root element of the deployment document which tells Axis that this is
- an undeployment. Must be in the "AdminService" namespace.</dd>
+ an undeployment. Undeployments are only useful as </dd>
<dt> </dt>
- <dt><b><font face="Courier New, Courier, mono"><handler
name="</font></b><font face="Courier New, Courier,
mono"><i>name</i></font><b><font face="Courier New, Courier, mono">"
+ <dt><b><font face="Courier New, Courier, mono"><handler
[name="</font></b><font face="Courier New, Courier,
mono"><i>name</i></font><b><font face="Courier New, Courier, mono">"]
type="</font></b><font face="Courier New, Courier,
mono"><i>type</i></font><b><font face="Courier New, Courier,
mono">"/></font></b></dt>
- <dd>Belongs inside a deploy or undeploy. Names a Handler, and indicates the
- class which corresponds to the name. May contain an arbitrary number of
<b><font face="Courier New, Courier, mono"><option
+ <dd>Belongs at the top level inside a <b><deployment></b> or
<b><undeployment></b>,
+ or inside a <b><chain></b>, <b><requestFlow></b>, or
<b><responseFlow></b>.
+ Defines a Handler, and indicates the type of the handler. "Type"
+ is either the name of another previously defined Handler, or a QName of the
+ form "<b>java:<i>class.name</i></b>". The optional "name"
+ attribute allows you to refer to this Handler defintion in other parts of
+ the deployment. May contain an arbitrary number of <b><font face="Courier New,
Courier, mono"><option
name="</font></b><font face="Courier New, Courier,
mono"><i>name</i></font><b><font face="Courier New, Courier, mono">"
value="</font></b><font face="Courier New, Courier,
mono"><i>value</i></font><b><font face="Courier New, Courier,
mono">"></font></b>
elements, each of which will supply an option to the deployed Handler.</dd>
@@ -46,9 +412,11 @@
></font></b></dt>
<dd>Deploys/undeploys an Axis Service. Common options for this element (i.e.
subelements of the form <code><b><parameter name="</b>name<b>"
- value="</b>value<b>"/></b>)</code> include:<br>
+ value="</b>value<b>"/></b>)</code> include: <br>
+ <br>
<b>className</b> : the backend implementation class<br>
- <b>methodName</b> : the allowed methods<br>
+ <b>allowedMethods</b> : the allowed methods (use "*" to allow all
+ public methods)<br>
<b>allowedRoles</b> : comma-separated list of roles allowed to access this
service<br>
<br>
@@ -58,7 +426,16 @@
may be specified inside the <b><service></b> element, and their semantics
are identical to the <b><chain></b> element described below - in other
words, they may contain <b><handler></b> and <b><chain</b>>
elements
- which will be invoked in the order they are specified.</dd>
+ which will be invoked in the order they are specified.<br>
+ <br>
+ Example:<br>
+ <pre><service name="test">
+ <parameter name="className"
value="test.Implementation"/>
+ <parameter name="allowedMethods" value="*"/>
+ <namespace>http://testservice/</namespace>
+
+</service></pre>
+ </dd>
<dt><b><br>
<font face="Courier New, Courier, mono"><chain name="</font></b><font
face="Courier New, Courier, mono"><i>name</i></font><b><font face="Courier New,
Courier, mono">"</font></b><b><font face="Courier New, Courier, mono">><br>
<<i>subelement</i>/>...<br>
@@ -74,7 +451,7 @@
or may refer to previously defined <handlers>, with the "type"
of the handler referring to the name of the other handler definition:<br>
<pre><handler name="logger"
type="java:org.apache.axis.handlers.LogHandler"/><br><chain
name="myChain"/><br> <handler
type="logger"/><br></chain></pre>
- </dd>
+ </dd> <dt> </dt>
<dt><b><font face="Courier New, Courier, mono"><transport
name="</font></b><font face="Courier New, Courier,
mono"><i>name</i></font><b><font face="Courier New, Courier,
mono">"></font></b></dt>
<dd>Defines a transport on the server side. Server transports are invoked when
an incoming request arrives. A server transport may define
<b><requestFlow></b>
