Axis Reference Guide

Beta 2 Version

Table of Contents

• Tools Reference
• WSDL2Java
• Java2WSDL
• Deployment (WSDD) Reference

Tools Reference

WSDL2Java Reference

Other WSDL2Java details

Usage:  java org.apache.axis.wsdl.WSDL2Java [options] WSDL-URI
Options:
        -h, --help
                print this message and exit
        -v, --verbose
                print informational messages
        -s, --server-side
                emit server-side bindings for web service
        -S, --skeletonDeploy <argument>
                deploy skeleton (true) or implementation (false) in deploy.wsdd.
                Default is false.  Assumes --server-side.
        -N, --NStoPkg <argument>=<value>
                mapping of namespace to package
        -f, --fileNStoPkg <argument>
                file of NStoPkg mappings (default NStoPkg.properties)
        -p, --package <argument>
                override all namespace to package mappings, use this package
                 name instead
        -o, --output <argument>
                output directory for emitted files
        -d, --deployScope <argument>
                add scope to deploy.xml: "Application", "Request", "Session"
        -t, --testCase
                emit junit testcase class for web service
        -n, --noImports
                only generate code for the immediate WSDL document
        -a, --all
                generate code for all elements, even unreferenced ones
        -D, --Debug
                print debug information
        -F, --factory <argument>
                name of the JavaWriterFactory class for extending Java generation functions
                ompliant)
        -O, --timeout <argument>
                timeout in seconds (default is 45, specify -1 to disable)
        -U, --user <argument>
                username to access the WSDL-URI
        -P, --password <argument>
                password to access the WSDL-URI
 

-h, --help

-v, --verbose

-s, --server-side

• a skeleton class named <bindingName>Skeleton.  This may or may not be emitted (see -S, --skeletonDeploy).
• an implementation template class named <bindingName>Impl.  Note that, if this class already exists, then it is not emitted.
• deploy.wsdd
• undeploy.wsdd

-S, --skeletonDeploy <argument>

<service name="AddressBook" provider="java:RPC">
    <parameter name="className" value="samples.addr.AddressBookSOAPBindingSkeleton"/>
    ...
</service>

and for "false" it would look like:

<service name="AddressBook" provider="java:RPC">
    <parameter name="className" value="samples.addr.AddressBookSOAPBindingImpl"/>
      ...
</service>

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.

-N, --NStoPkg <argument>=<value>

--NStoPkg urn:AddressFetcher2=samples.addr

-f, --fileNStoPkg <argument>

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:

urn\:AddressFetcher2=samples.addr

If an entry for a given mapping exists both on the command line and in the properties file, the command line entry takes precedence.

-p, --package <argument>

-o, --output <argument>

-d, --deployScope <argument>

-t, --testCase

-n, --noImports

-a, --all

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:

1. types
2. portTypes
3. bindings
4. services

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.

-D, --Debug

-T, --typeMappingVersion <argument>

-F, --factory <argument>

-U, --user <argument>

-P, --password <argument>

Java2WSDL Reference

Here is the help message generated from the current tool:

Java2WSDL emitter
Usage: java org.apache.axis.wsdl.Java2WSDL [options] class-of-portType
Options:
        -h, --help
                print this message and exit
        -o, --output <argument>
                output WSDL filename
        -l, --location <argument>
                service location url
        -P, --portTypeName <argument>
                portType name (obtained from class-of-portType if not specified)
        -S, --serviceElementName <argument>
                service element name (defaults to servicePortName value + "Service")
        -s, --servicePortName <argument>
                service port name (obtained from --location if not specified)
        -n, --namespace <argument>
                target namespace
        -p, --PkgtoNS <argument>=<value>
                package=namespace, name value pairs
        -m, --methods <argument>
                space or comma separated list of methods to export
        -a, --all
                look for allowed methods in inherited class
        -w, --outputWsdlMode <argument>
                output WSDL mode: All, Interface, Implementation
        -L, --locationImport <argument>
                location of interface WSDL
        -N, --namespaceImpl <argument>
                target namespace for implementation WSDL
        -O, --outputImpl <argument>
                output Implementation WSDL filename, setting this causes --outputWsdlMode to be ignored
        -f, --factory <argument>
                name of the Java2WSDLFactory class for extending WSDL generation functions
        -i, --implClass <argument>
                optional class that contains implementation of methods in
                class-of-portType.  The debug information in the class is used
                to obtain the method parameter names, which are used to set
                the WSDL part names.
        -x, --exclude <argument>
                space or comma separated list of methods not to export
        -c, --stopClasses <argument>
                space or comma separated list of class names which stop inheritance search
                if --all switch is enabled
        -T, --typeMappingVersion <argument>
                indicate 1.1 or 1.2. The default is 1.2 (SOAP 1.2 JAX-RPC compliant)
Details:
   portType element name= <.portTypeName value> OR <class-of-portType name>
   binding element  name= <--servicePortName value>SoapBinding
   service element  name= <--serviceElementName value> OR <portTypeName value>Service
   port element     name= <--servicePortName value>
   address location     = <--location value>
 

-h , --help
Prints the help message.

-o, --output <WSDL file>
Indicates the name of the output WSDL file.  If not specified, a suitable default WSDL file is written into the current directory.

-l, --location <location>
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, --portTypeName <name>
Indicates the name to use use for the portType element. If not specified, the class-of-portType name is used.

-s, -serviceElementName <name>
Indicates the name of the service element.  If not specified, the service element is the <portTypeName>Service. 

-s, -servicePortName <name>
Indicates the name of the service port.  If not specified, the service port name is derived from the --location value. 

-n, --namespace <target namespace>
Indicates the name of the target namespace of the WSDL.

-p, --PkgToNS <package> <namespace>
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.

-m, --methods <arguments>
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.

-a, --all
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.

-w, --outputWSDLMode <mode>
Indicates the kind of WSDL to generate.  Accepted values are:

• All --- (default) Generates wsld containing both interface and implementation WSDL constructs.
• Interface --- Generates a WSDL containing the interface constructs (no service element).
• Implementation -- Generates a WSDL containing the implementation.  The interface WSDL is imported via the -L option.

-N, --namespaceImpl <namespace>
Namespace of the implementation WSDL.

-O, --outputImpl <WSDL file>
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.

-f, --factory <class>
(No longer used.)

-i, --implClass <impl-class>
Sometimes extra information is avalable in the implementation class file. Use this option to specify the implementation class.

-f, --factory <class>
(No longer used.)

-x, --exclude <list>
List of methods to not exclude from the wsdl file.

-c, --stopClasses <list>
List of classes which stop the Java2WSDL inheritance search.

-T, --typeMappingVersion <version>
Choose the default type mapping registry to use. Either 1.1 or 1.2.

Deployment (WSDD) Reference

<deployment>

The root element of the deployment document which tells the Axis engine 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.

 

<undeployment>

The root element of the deployment document which tells Axis that this is an undeployment. Undeployments are only useful as

 

<handler [name="name"] type="type"/>

Belongs at the top level inside a <deployment> or <undeployment>, or inside a <chain>, <requestFlow>, or <responseFlow>. 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 "java:class.name". The optional "name" attribute allows you to refer to this Handler defintion in other parts of the deployment. May contain an arbitrary number of <option name="name" value="value"> elements, each of which will supply an option to the deployed Handler.

 

<service name="name" provider="provider" >

Deploys/undeploys an Axis Service. This is the most complex WSDD tag, so we're going to spend a little time on it.

Options may be specified as follows : <parameter name="name" value="value"/>, and common ones include:

className : the backend implementation class
allowedMethods : the allowed methods (use "*" to allow all public methods)
allowedRoles : comma-separated list of roles allowed to access this service

If you wish to define handlers which should be invoked either before or after the service's provider, you may do so with the <requestFlow> and the <responseFlow> subelements. Either of those elements may be specified inside the <service> element, and their semantics are identical to the <chain> element described below - in other words, they may contain <handler> and <chain> elements which will be invoked in the order they are specified.

Example:

<service name="test">
  <parameter name="className" value="test.Implementation"/>
  <parameter name="allowedMethods" value="*"/>
  <namespace>http://testservice/</namespace>
  <requestFlow> <!-- Run these before processing the request -->
    <handler type="java:MyHandlerClass"/>
    <handler type="somethingIDefinedPreviously"/>
  </requestFlow>
</service>

Metadata may be specified about particular operations in your service by using the <operation> tag inside a service. This enables you to map the java parameter names of a method to particular XML names, to specify the parameter modes for your parameters, and to map particular XML names to particular operations.

<operation name="method">
</operation>

 

<chain name="name">
<subelement/>...
</chain>

Defines a chain. Each handler (i.e. deployed handler name) in the list will be invoked() in turn when the chain is invoked. This enables you to build up "modules" of commonly used functionality. The subelements inside chains may be <handler>s or <chain>s. <handler>s inside a <chain> may either be defined in terms of their Java class:

<chain name="myChain">
  <handler type="java:org.apache.axis.handlers.LogHandler"/>
</chain>

or may refer to previously defined <handlers>, with the "type" of the handler referring to the name of the other handler definition:

<handler name="logger" type="java:org.apache.axis.handlers.LogHandler"/>
<chain name="myChain"/>
   <handler type="logger"/>
</chain>

 

<transport name="name">

Defines a transport on the server side. Server transports are invoked when an incoming request arrives. A server transport may define <requestFlow> and/or <responseFlow> elements to specify handlers/chains which should be invoked during the request (i.e. incoming message) or response (i.e. outgoing message) portion of processing (this function works just like the <service> element above). Typically handlers in the transport request/response flows implement transport-specific functionality, such as parsing protocol headers, etc.

 

<transport name="name" pivot="handler type" >

Defines a transport on the client side, which is invoked when sending a SOAP message. The "pivot" attribute specifies a Handler to be used as the actual sender for this transport (for example, the HTTPSender). Request and response flows may be specified as in server-side transports to do processing on the request (i.e. outgoing message) or response (i.e. incoming message).

 

<typeMapping qname="ns:localName" classname="classname" serializer="classname" deserializer="classname"/>

Each typeMapping maps an XML qualified name to/from a Java class, using a specified Serializer and Deserializer.

 

<beanMapping qname="ns:localName" classname="classname">

A simplified type mapping, which uses pre-defined serializers/deserializers to encode/decode JavaBeans. The class named by "classname" must follow the JavaBean standard pattern of get/set accessors.

Pre-Configured Axis Components Reference

On the server:

LogHandler

The LogHandler will simply log a message to a logger when it gets invoked.

EchoHandler

The EchoHandler copies the request message into the response message.

HTTPAuth

The HTTPAuthHandler takes HTTP-specific authentication information (right now, just Basic authentication) and turns it into generic MessageContext properties for username and password

SimpleAuthenticationHandler

The SimpleAuthentication handler passes a MessageContext to a SecurityProvider (see org.apache.axis.security) to authenticate the user using whatever information the SecurityProvider wants (right now, just the username and password).

SimpleAuthorizationHandler

This handler, typically deployed alongside the SimpleAuthenticationHandler (a chain called "authChecks" is predefined for just this combination), checks to make sure that the currently authenticated user satisfies one of the allowed roles for the target service. Throws a Fault if access is denied.

URLMapper

The URLMapper, an HTTP-specific handler, usually goes on HTTP transport chains (it is deployed by default). It serves to do service dispatch based on URL - for instance, this is the Handler which allows URLs like http://localhost:8080/axis/services/MyService?wsdl to work.

 

RPCDispatcher

The RPCDispatcher is the pivot point for all RPC services. It accepts the following options:
className = the class of the backend object to invoke
methodName = a space-separated list of methods which are exported as web services. The special value "*" matches all public methods in the class.

MsgDispatcher

The MsgDispatcher is the pivot point for all messaging services. It accepts the following options:

className = the class of the backend object to invoke
methodName = a space-separated list of methods which are exported as web services. The special value "*" matches all public methods in the class.

LocalResponder

The LocalResponder is a Handler whose job in life is to serialize the response message coming back from a local invocation into a String. It is by default on the server's local transport response chain, and it ensures that serializing the message into String form happens in the context of the server's type mappings.

On the client:

HTTPSender

A Handler which sends the request message to a remote server via HTTP, and collects the response message.

LocalSender

A Handler which sends the request message to a "local" AxisServer, which will process it and return a response message. This is extremely useful for testing, and is by default mapped to the "local:" transport. So, for instance, you can test the AdminClient by doing something like this:

% java org.apache.axis.client.AdminClient -llocal:// list