WSDL2Java command for JAX-RPC applications

Run the WSDL2Java command-line tool against the WSDL file to create Java APIs and deployment descriptor templates.

(ZOS) The WSDL2Java command-line tool is not supported on the z/OS platform. This functionality is provided by the assembly tools provided with WebSphere Application Server running on the z/OS platform.

A WSDL file describes a Web service. The Java API for XML-based Remote Procedure Call (JAX-RPC) 1.1 specification defines a Java API mapping that interacts with the web service. The Web Services for Java EE specification defines deployment descriptors that deploy a web service in a Java EE environment. The WSDL2Java command is run against the WSDL file to create Java APIs and deployment descriptor templates according to these specifications.

It is a best practice to use absolute namespaces within the WSDL or schema. By default, the WSDL2Java tool does not permit the use of relative namespaces. Relative namespaces have been deprecated by the XML Plenary Interest Group and the use of relative namespaces causes the XML Digital Signature to fail as required by the Canonical XML Version 1.0 specification. However, if we have an established WSDL or schema that relies on relative namespaces, under specific conditions we can use the allowRelativeNamespace property to disable the relative namespace restrictions in the WSDL2Java tool. For additional information, see the property description. bprac

We can convert any relative namespaces to absolute namespaces. The following is an example of a relative namespace:

targetNamespace="MyRelNamespace"

. We can change the relative namespace in this example to an absolute namespace by adding the protocol and base URI information:

targetNamespace="http://www.sample.com/MyRelNamespace"

Command-line syntax

The command-line syntax is:

WSDL2Java [arguments] WSDL-URI

Required arguments

• WSDL-URI

  Location of the input WSDL file using a Universal Resource Identifier (URI). We can also use a regular file path if the WSDL file is on the local file system.

Important arguments

• -role Java EE role

  Java EE development role that identifies which files to generate. Valid arguments include:

  • client

    A combination of the develop-client and deploy-client arguments.

  • deploy-client

    Generates binding files for client deployment.

  • deploy-server

    Generates binding files for server deployment.

  • develop-client (default)

    Generates files for client development.

  • develop-server

    Generates files for server development.

  • server

    A combination of the develop-server and deploy-server arguments.

• -container Java EE-container

  Indicates the Java EE container to use. Valid arguments include:

  • client

    Indicates client container.

  • ejb

    Indicates an EJB container.

  • none

    Indicates no container.

  • web

    Indicates a web container.

  For client roles (see the -role option), the default argument is none. For server roles, the container must be ejb or web. The same container option must be used for both development and deployment.

• -output directory

  Sets the root directory for emitted files.

• -inputMappingFile mapping file

  File name of the Web Services for Java EE mapping file.

• -introspect

  Uses existing Java beans with a new web service API.

  In some scenarios, it is good to use existing Java classes instead of generating new classes. The -introspect option directs the WSDL2Java command to examine existing Java classes when generating classes. The existing classes are validated against the JAX-RPC specification. For example:

  Suppose we have an existing Java bean

  public class Bean {
  	public Date x;
  }
  

  The WSDL file defines x as xsd:dateTime. Without the -introspect option, the WSDL2Java command generates a Java bean that is similar to the following example:

  public class Bean {
  	private Calendar x;
  	public void setx(Calendar value) (x=value;)
  	public Calendar getX() { return x;)
  }
  

  The WSDL2Java command uses the -introspect option to examine the original Java bean and to generate classes that are compatible with existing Java beans.
• -classpath paths

  Defines an alternative class path to search for Java classes.

• -noDataBinding

  Disables the binding of XML types to Java types. Instead, each XML type is mapped to a javax.xml.soap.SOAPElement interface defined by the SOAP with Attachments API for Java (SAAJ) specification.

  The JAX-WS programming model supports SAAJ 1.2 and 1.3.

  The JAX-RPC programming model supports SAAJ 1.2.

  The Java programming models define Java mappings for a subset of XML types. Several XML types cannot be mapped to Java beans or primitives. In this situation, the WSDL2Java command maps the type to an SAAJ SOAPElement. A SAAJ SOAPElement is a generic representation of the element in the message. The methods on the SOAPElement can be used to examine the element and its children.

  In some scenarios, it might be more appropriate to use the generic SOAPElement mapping exclusively. To learn more about the use of SOAPElement, see the information on SOAP with Attachments API for Java interface and custom data binders for JAX-RPC applications.

  For a complete list of the supported standards and specifications, see the web services specifications and API documentation.

• -help

  Display a help message and exits.

• -helpX

  Display a help message for extended options. The options include:

• -verbose

  Displays processing information, including the names of the generated files.

• -NStoPkg namespace=package

  By default, package names are automatically derived from the namespace strings in the WSDL file. For example, if the namespace is of the form http://x.y.com or urn:x.y.com, the corresponding package is com.y.x.

  We can provide our own mapping using the -NStoPkg argument, which we can repeat as often as necessary, once for each unique namespace mapping. For example, if a namespace in the WSDL file is called urn:AddressFetcher2, and we want files generated from the objects in this namespace to reside in the samples.addr package, provide the -NStoPkg "http://urn:AddressFetcher2/"=samples.addr argument to the WSDL2Java command.

• -timeout seconds

  Specifies how long the WSDL2Java command waits, in seconds, for the WSDL-URI to respond before giving up. The default is 45 seconds; -1 disables the timeout.

• -genResolver

  Generates an absolute-import resolver class. The purpose of this class is to record the contents of the imported WSDL files used by the WSDL URI. This class is used by the run time and can also be used for future WSDL2Java command runs. This flexibility is desirable when the imported WSDL files are remote and possibly inaccessible. When an import resolver is used, the possibility that a remote WSDL file has different contents at run time that it did during development is eliminated. The generated class is named _AbsoluteImportResolver.java. Compile and package this class with the other Java classes generated by the WSDL2Java command.

• -useResolver resolver-class

  Specifies an absolute-import resolver class to use during parsing. This class must be created during a previous run of the WSDL2Java command that uses the -genResolver option. The class must be available in the CLASSPATH variable.

• -deployScope argument

  Indicates how to deploy the server implementation. Valid arguments include:

  • Application

    Uses one instance of the implementation class for all requests.

  • Request

    Creates a new instance of the implementation class for each request.

  • Session

    Creates a new instance of the implementation class for each session.

Other arguments

• -user id

  Login user name to access the WSDL URI.

• -password password

  Login user password to access the WSDL URI.

• -all

  Generates Java files for all types, even those that are not referenced.

• -allowRelativeNamespace true or false

  Specifies whether to disable the relative namespace restrictions. If we specify -allowRelativeNamespace=true, the relative namespace restrictions are disabled.

  Only use this property if we have an established WSDL file or schema that relies on a relative namespaces and we are seeking to interoperate with a defined set of vendors that permit the use of relative namespaces.

• -debug

  Prints debugging information.

• -genJava argument

  Generates Java files. Valid arguments include:

  • IfNotExists, default
  • Overwrite
  • No

• -javaSearch argument

  The -javaSearch option is used with the -genJava option. If the -genJava IfNotExists, use the -javaSearch option to determine how file existence is detected.

  • File (default): Looks for a file in the output directory
  • Classpath: Looks for a class in the CLASSPATH variable
  • Both: Looks for a file in the output directory or in a class in the CLASSPATH variable

• -genXML argument

  Generates the .xml and .xmi files. Valid arguments are:

  • IfNotExists, default
  • Overwrite
  • No

• -genImplSer true or false

  Indicates that each generated Java bean implements the java.io.Serializable. The default is false.

• -genEquals true or false

  Indicates that each generated Java bean have equals and hashCode methods. The default is false.

• -noWrappedOperations

  Disables wrapped operations detection. Java beans for the request and response messages are generated.

• -noWrappedArrays

  Disables wrapped array detection.

• -fileNStoPkg file name

  File of the namespace to package mappings. The default is NStoPKG.properties.

• service wsdl service name

  Generates files for the installed WSDL service only.

• -testCase

  Generates the template for a JUnit test case for testing web services. JUnit is a simple framework to write repeatable tests.

Related:

SOAP with Attachments API for Java interface

Custom data binders for JAX-RPC applications

Development and assembly tools

Developing a service endpoint interface from JavaBeans for JAX-RPC applications

Java2WSDL command for JAX-RPC applications

Mapping between Java language, WSDL and XML for JAX-RPC applications

Web services specifications and APIs