wsimport command for JAX-WS applications

wsimport command for JAX-WS applications

The wsimport command-line tool processes an existing WSDL file and generates the required artifacts for developing 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 we start with an existing WSDL file, use the wsimport command-line tool to generate the required JAX-WS artifacts.

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.

WAS provides 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 in WAS traditional.The xjc and schemagen commands are located in the app_server_root\jaxb\bin\ directory in Liberty profile. On some occasions, the artifacts generated by both the tooling provided by WAS 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 WAS environment and to take advantage of the features that may be only supported in WAS. To take advantage of JAX-WS and JAXB V2.2 tooling, use the tools provided with the application server located in...
app_server_root/bin
bprac

Use the wsimport, wsgen, schemagen and xjc command-line tools with both Liberty and the WAS traditional of the application server.
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 required to model the web service data.
We 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.

To correctly use the wsimport tool, we must adhere to the following requirements:

We must define all your services within the main WSDL file. Services defined within an imported WSDL file are not processed by the wsimport tool.
If we 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 we run the wsimport tool and pass a ?wsdl Uniform Resource Identifier (URI) as a parameter for a WSDL file, ensure that we are using the actual resolved WSDL URI. In the full profile, the wsimport tool correctly resolves the ?wsdl URI, but other relative URIs referenced might not resolve correctly. In the Liberty profile, the wsimport tool correctly resolves the ?wsdl URI and other relative URIs referenced.

In addition to using the tools from the command line, we can invoke these JAX-WS tools from within the Ant build environments for the WAS traditional. 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:

(Windows)
app_server_root\bin\wsimport.bat [options] WSDL_URI
(UNIX)
app_server_root/bin/wsimport.sh [options] WSDL_URI
(iSeries)
app_server_root/bin/wsimport [options] WSDL_URI
Parameters

The WSDL_URI is the only parameter required. The following parameters are optional for the wsimport command:
-b <path>

External JAX-WS or JAXB binding files. We can specify multiple JAX-WS and JAXB binding files using the -b option; however, each file must be specified with its own -b option.

-B <jaxbOption>

To pass this option to the JAXB schema compiler.

-catalog

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

Display 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>

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

To suppress the wsimport output.

-s <directory>

Directory to place the generated source files.

-target <version>

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 is version 2.2 and generates compliant code for the JAXB 2.2 specification.

The target option is required for Liberty profile.

-verbose

To output messages about what the compiler is doing.

-version

Prints the version information. If we specify this option, only the version information is included in the output and normal command processing does not occur.

-wsdlLocation
The @WebServiceClient.wsdlLocation value.
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. We can manually update the @WebService.wsdlLocation annotation with a relative URL that specifies the location of the 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.
If we 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");
-clientJar

wsimport on service WSDL generates the necessary classes needed for web service invocation. But not all the information required by the JAX-WS runtime is captured in the SEI or the WebServiceClient through standard web service annotations. The generated class has the location of the WSDL, so that it can retrieve the additional metadata of the service at runtime. However, an extra connection is required just to access the metadata each time a service instance is created, which increases the network usage. By using the -clientJar option for wsimport, the WSDL and schema are automatically downloaded and all the generated client-side artifacts are packaged into a JAR file. Therefore, we can include the generated JAR file using this new option in the class path and do not need to fetch the WSDLs from the end point each time a service instance is created, thus saving on network usage.
Related:

Development and assembly tools
Generate Java artifacts for JAX-WS applications from a WSDL file
Implement web services applications with JAX-WS
xjc command for JAXB applications
Web services specifications and APIs
JAX-WS API documentation
JAX-WS 2.2 Tools Reference implementation