The wsimport command-line tool processes an existing Web
Services Description Language (WSDL) file and generates the required
artifacts for developing Java API
for XML-Based Web Services (JAX-WS) web service applications. The
generated artifacts are Java 5
compliant, making them portable across different Java versions and platforms.
The wsimport command-line tool supports the
top-down approach to developing JAX-WS web services. When you start
with an existing WSDL file, use the wsimport command-line
tool to generate the required JAX-WS artifacts.
Supported configurations: The wsimport, wsgen, schemagen and xjc command-line
tools are 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. Read about these command-line
tools for JAX-WS applications to learn more about these tools.sptcfg
Best practice: WebSphere Application
Server provides Java API for XML-Based Web Services
(JAX-WS) and Java Architecture for XML Binding
(JAXB) tooling. The wsimport, wsgen, schemagen and xjc command-line
tools are located in the app_server_root\bin\ directory.
Similar tooling is provided by the Java SE
Development Kit (JDK) 6. On some occasions, the artifacts generated
by both the tooling provided by WebSphere Application
Server and the JDK support the same levels of the specifications.
In general, the artifacts generated by the JDK tools are portable
across other compliant runtime environments. However, it is a best
practice to use the tools provided with this product to achieve seamless
integration within the WebSphere Application Server
environment and to take advantage of the features that may be only
supported in WebSphere Application Server. To take advantage
of JAX-WS and JAXB V2.2 tooling, use the tools provided with the application
server that are located in the app_server_root\bin\
directory.bprac
The
wsimport tool reads an existing WSDL file
and generates the following artifacts:
- Service Endpoint Interface (SEI) - The SEI is the annotated Java representation of the WSDL file for the
web service. This interface is used for implementing JavaBeans endpoints or creating dynamic
proxy client instances.
- javax.xml.ws.Service extension class - This is
a generated class that extends the javax.xml.ws.Service class.
This class is used to configure and create both dynamic proxy and
dispatch instances.
- required data beans, including any Java Architecture
for XML Binding (JAXB) beans that are required to model the web service
data.
You can package the generated artifacts in a web application
archive (WAR) file with the WSDL file and schema documents along with
the endpoint implementation to be deployed.
Supported configurations: To correctly use the
wsimport tool,
you must adhere to the following requirements:
- You must define all your services within the main WSDL file. Services
that are defined within an imported WSDL file are not processed by
the wsimport tool.
- If you run the wsimport tool on a WSDL file
that implements a Document or Literal style pattern, the complexTypes
elements that define the input and output types must be composed of
unique names to prevent naming conflicts in the parameter list for
the operation..
- If you run the wsimport tool and pass a ?wsdl Uniform
Resource Identifier (URI) as a parameter for a WSDL file, ensure that
you are using the actual resolved WSDL URI. The wsimport tool
correctly resolves the ?wsdl URI, but other relative
URIs that are referenced might not resolve correctly.
sptcfg
In addition to using the tools from the command
line, you can invoke these JAX-WS tools from within the Ant build
environments. Use the com.sun.tools.ws.ant.WsImport Ant
task from within the Ant build environment to invoke the wsimport
tool. To function properly, this Ant task requires that you invoke
Ant using the ws_ant script.
Syntax
The command-line syntax is:
app_server_root\bin\wsimport.bat [options] WSDL_URI
app_server_root/bin/wsimport.sh [options] WSDL_URI
app_server_root/bin/wsimport [options] WSDL_URI
Parameters
The WSDL_URI is the only
parameter that is required. The following parameters are optional
for the wsimport command:
- -b <path>
- Specifies the external JAX-WS or JAXB binding files. You can specify
multiple JAX-WS and JAXB binding files by using the -b option;
however, each file must be specified with its own -b option.
- -B <jaxbOption>
- Specifies to pass this option to the JAXB schema compiler.
- -catalog
- Specifies the catalog file to resolve external entity references.
It supports the TR9401, XCatalog, and the OASIS XML Catalog formats
- -d <directory>
- Specifies where to place the generated output files.
- -extension
- Specifies whether to accept custom extensions for functionality
that are not specified by the JAX-WS specification. The use of custom
extensions can result in applications that are not portable or do
not interoperate with other implementations.
- -help
- Displays the help menu.
- -httpproxy:<host>:<port>
- Specifies an HTTP proxy. The default port value is 8080.
- -keep
- Specifies whether to keep the generated source files.
- -p <package_name>
- Specifies a target package with this command-line option and overrides
any WSDL file and schema binding customization for the package name
and the default package name algorithm defined in the JAX-WS specification.
- -quiet
- Specifies to suppress the wsimport output.
- -s <directory>
- Specifies the directory to place the generated source files.
- -target <version>>
- Specifies to generate code that is compliant with a specific JAX-WS
specification level. Specify version 2.0 or 2.1 to
generate code that is compliant with the JAX-WS 2.0 or JAX-WS 2.1
specification respectively. Specifying version 2.1 indicates
to generate code that is compliant with the JAX-WS 2.1 specification.
The default value is version 2.2 and generates compliant
code for the JAXB 2.2 specification.
- -verbose
- Specifies to output messages about what the compiler is doing.
- -version
- Prints the version information. If you specify this option, only
the version information is included in the output and normal command
processing does not occur.
- -wsdlLocation
- Specifies the @WebServiceClient.wsdlLocation value.
Supported configurations: The
wsimport tool does not set
the
@WebService.wsdlLocation value either by default
or when the -wsdlLocation attribute is specified. The
wsimport command-line
tool updates the @WebServiceClient.wsdlLocation annotation only. You
can manually update the @WebService.wsdlLocation annotation with a
relative URL that specifies the location of the Web Services Description
Language (WSDL) file. If the @WebService.wsdlLocation annotation is
present on an endpoint implementation class, then the value must be
a relative URL and the WSDL document that it references must be packaged
with the application.
sptcfg
Avoid trouble: If
you specify an HTTPS URL for the -wsdlLocation parameter, the
wsimport tool
generates a service class with a no-argument constructor that is not
valid. Avoid using the no-argument service constructor to instantiate
your service. Instead, pass the HTTPS URL to one of the service class
constructors that takes a WSDL URL for an argument; for example:
MyService("https://example.ibm.com/My?wsdl");
gotcha