Generating Java code from a WSDL document

The WSDL2Java tool generates web service proxy and skeleton code based on information in a web service WSDL document. A proxy is a local object with the same interface as the actual web service; it allows you to call the web service as if it were a local object. WSDL2Java generates proxies from WSDL documents that specify RPC encoded, document literal, and document encoded SOAP encoding styles.

A skeleton is a template for a new web service implementation; after generating the skeleton, you complete it with your own code.

For descriptions of the WSDL2Java command-line switches, see "WSDL2Java command-line switches".

Generating a web service proxy

This section describes how to create a web service proxy. For information about calling the proxy from a JSP-based client, see "Proxy clients".

To generate proxy code for a web service:

Obtain the WSDL document for the web service.
For information about generating a WSDL document for an Axis-based web service, see "Generating WSDL from a published web service".
At a command prompt, run the WSDL2Java tool in one of the following ways:
```
cd jrun_root\bin
wsdl2java -v -o output_directory localpath/your_file.wsdl
```
or
java -classpath "jrun_root/lib/jrun.jar;jrun_root/lib/webservices.jar" org.apache.axis.wsdl.WSDL2Java -v -o output_directory localpath/your_file.wsdl
where
- -v specifies the tool should display informational messages
- -o specifies the name of the output directory
- localpath/your_file.wsdl represents the directory and filename of the WSDL document

Note: For Axis-based web services, as an alternative to using localpath/your_file.wsdl as the URL in the command line in step 2, you can use the web service endpoint URL with the WSDL argument as described in "Generating WSDL from a published web service".

Reviewing the generated proxy code

WSDL2Java generates the following proxy files:

File

Description

ServiceNameLocator.java

This class serves as a factory for obtaining proxy instances. It implements the ServiceName.java interface. It is generated from the service name in the WSDL file.

The class name is derived from the service name in the WSDL document plus the suffix Locator. If you had more than one service listed in the WSDL file, one class for each service would be generated. You use the get methods in this class to get a stub object that implements the web service interface.

ServiceName.java

This is a factory interface that the ServiceNameLocator.java class implements.

The interface name is derived from the service name in the WSDL document.

ServicePortName.java
(for encoded WSDL)

ServiceBindingName.java
(for literal WSDL)

This interface contains method signatures for each of the web service operations.

The interface name is derived from the port name or the binding name in the WSDL document.

ServiceBindingNameStub.java

This is the web service proxy class. It implements the ServicePortName.java interface that uses the Axis client API to make the web service call.

The class name is derived from the service binding name plus the suffix Stub.

File	Description
ServiceNameLocator.java	This class serves as a factory for obtaining proxy instances. It implements the ServiceName.java interface. It is generated from the service name in the WSDL file. The class name is derived from the service name in the WSDL document plus the suffix Locator. If you had more than one service listed in the WSDL file, one class for each service would be generated. You use the `get` methods in this class to get a stub object that implements the `web` `service` interface.
ServiceName.java	This is a factory interface that the ServiceNameLocator.java class implements. The interface name is derived from the service name in the WSDL document.
ServicePortName.java (for encoded WSDL) ServiceBindingName.java (for literal WSDL)	This interface contains method signatures for each of the web service operations. The interface name is derived from the port name or the binding name in the WSDL document.
ServiceBindingNameStub.java	This is the web service proxy class. It implements the ServicePortName.java interface that uses the Axis client API to make the web service call. The class name is derived from the service binding name plus the suffix Stub.

For WSDL documents that specify complex data types, WSDL2Java generates JavaBean classes that represent those types. For more information about how Axis uses JavaBeans, see "Data type mapping with the Axis bean serializer".

WSDL documents can also specify in-out parameters used for both input and output, and out parameters used for output only. Because Java does not directly support inout and out parameters, when necessary, WSDL2Java generates holder classes that allow parameters to be modified by the service and returned to the client. For each class that requires one, WSDL2Java generates a corresponding holder class with the same base name. For example, a class called MyClass would have a corresponding holder class called MyClassHolder.

Generating a web service skeleton

To generate web service skeleton code in addition to the proxy code that WSDL2Java generates by default, you use the -s or --skeleton switch.

This section describes how to create a web service skeleton.

To generate skeleton code for a web service:

Obtain the WSDL document for the web service. For information about generating a WSDL document for an Axis-based web service, see "Generating WSDL from a published web service".
At a command prompt, run the WSDL2Java tool in one of the following ways:
```
cd jrun_root\bin
wsdl2java -v -o -s output_directory localpath/your_file.wsdl
```
or
java -classpath "jrun_root/lib/jrun.jar:jrun_root/lib/webservices.jar" org.apache.axis.wsdl.WSDL2Java -v -o -s output_directory localpath/your_file.wsdl
where
- -v specifies the tool should display informational messages
- -o specifies the name of the output directory
- -s specifies the tools should generate skeleton code
- localpath/your_file.wsdl represents the directory and file name of the WSDL document

Note: For Axis-based web services, as an alternative to using localpath/your_file.wsdl as the URL in the command line in step 2, you can use the web service endpoint URL with the WSDL argument, as described in "Generating WSDL from a published web service".

Reviewing the generated skeleton code and deployment information

WSDL2Java generates the following skeleton files:

File

Description

ServiceNameSoapBindingSkeleton.java

This is the class you deploy as a web service.

ServiceNameSoapBindingImpl.java

This is an implementation class template to which you add your own implementation code.

deploy.wsdd

This file contains a WSDD service element that you can copy and paste into the server-config.wsdd file, the deployment descriptor for the web service.

File	Description
ServiceNameSoapBindingSkeleton.java	This is the class you deploy as a web service.
ServiceNameSoapBindingImpl.java	This is an implementation class template to which you add your own implementation code.
deploy.wsdd	This file contains a WSDD service element that you can copy and paste into the server-config.wsdd file, the deployment descriptor for the web service.

For web services that use complex data types, WSDL2Java generates JavaBean classes that represent those types. For more information about how Axis uses JavaBeans, see "Data type mapping with the Axis bean serializer".

WSDL documents can specify inout parameters used for both input and output, and out parameters used for output only. Because Java does not directly support inout and out parameters, when necessary, WSDL2Java generates holder classes that allow parameters to contain both input and output values. For each class that requires one, WSDL2Java generates a corresponding holder class with the same base name. For example, a class called MyClass would have a corresponding holder class called MyClassHolder.

WSDL2Java command-line switches

You can use either the double dash (--) or single dash (-) versions of the following optional command-line switches for the WSDL2Java tool:

Switch

Description

--help, -h

Prints a usage message.

--verbose, -v

Prints informational messages about what the tool is generating as it is generating it.

--skeleton, -s

Emits skeleton code for a new web service.

--skeletonDeploy, -S <true or false>

Indicates whether to deploy a skeleton or the implementation class. When the value is false, WSDL2Java uses the implementation class.

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

Maps a namespace to a Java package.

By default, package names are generated from the namespace strings in the WSDL document. Users can provide their own mappings using the --NStoPkg argument 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 provide the following switch to WSDL2Java:

--NStoPkg urn:AddressFetcher2=samples.addr

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 also looks for mappings in a file called NStoPkg.properties residing in the default package (no package). The entries in this file are of the same form as the arguments to the --NStoPkg command line switch. For example, instead of providing the command line switch as above, you could provide the same information in NStoPkg.properties:

urn\:AddressFetcher2=samples.addr

(The colon must be escaped in the properties file.)

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

--package, -p <packagename>

Overrides all namespace-to-package mappings and uses the specified package name instead.

--output, -o <directory>

Generates files in the specified output directory.

--deployScope, -d <argument>

Adds an Application, Request, or Session scope to the generated WSDD file (deploy.wsdd).

If you do not use this switch, no scope tag appears in the deploy.xml file, and the AXIS runtime defaults to the Request scope.

--testCase, -t

Generates a client-side JUnit test case.

--noImports, -n

Generates code only for the document that appears on the command line. The default behavior is to generate files for all WSDL documents, the immediate one and any that it imports.

--all, -a

Generates code for all elements, including unreferenced elements.

--debug, -D

Prints debug information.

Switch	Description
--help, -h	Prints a usage message.
--verbose, -v	Prints informational messages about what the tool is generating as it is generating it.
--skeleton, -s	Emits skeleton code for a new web service.
--skeletonDeploy, -S <true or false>	Indicates whether to deploy a skeleton or the implementation class. When the value is false, WSDL2Java uses the implementation class.
--NStoPkg, -N <argument>=<value>	Maps a namespace to a Java package. By default, package names are generated from the namespace strings in the WSDL document. Users can provide their own mappings using the --NStoPkg argument 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 provide the following switch to WSDL2Java: --NStoPkg urn:AddressFetcher2=samples.addr 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 also looks for mappings in a file called NStoPkg.properties residing in the default package (no package). The entries in this file are of the same form as the arguments to the --NStoPkg command line switch. For example, instead of providing the command line switch as above, you could provide the same information in NStoPkg.properties: urn\:AddressFetcher2=samples.addr (The colon must be escaped in the properties file.) If an entry for a given mapping exists on the command line and in the properties file, the command line entry takes precedence.
--package, -p <packagename>	Overrides all namespace-to-package mappings and uses the specified package name instead.
--output, -o <directory>	Generates files in the specified output directory.
--deployScope, -d <argument>	Adds an Application, Request, or Session scope to the generated WSDD file (deploy.wsdd). If you do not use this switch, no scope tag appears in the deploy.xml file, and the AXIS runtime defaults to the Request scope.
--testCase, -t	Generates a client-side JUnit test case.
--noImports, -n	Generates code only for the document that appears on the command line. The default behavior is to generate files for all WSDL documents, the immediate one and any that it imports.
--all, -a	Generates code for all elements, including unreferenced elements.
--debug, -D	Prints debug information.

Programmer's Guide
Working with WSDL Documents