Develop a JAX-WS client from a WSDL file

Develop a JAX-WS client from a WSDL file

JAX-WS tooling supports generating Java artifacts we need to develop static JAX-WS web services clients when starting with a WSDL file.
When you use a top-down development approach to developing JAX-WS web services by starting with a WSDL file, obtain the Uniform Resource Locator (URL) for the WSDL file.
(zos) If the WSDL file is a local file, the URL looks like this example: file:drive:\path\file_name.wsdl.
(iseries) If the WSDL file is a local file, the URL looks like this example: file:/path/file_name.wsdl.
We can also specify local files using the absolute or relative file system path.

The static client programming model for JAX-WS is the called the dynamic proxy client. The dynamic proxy client invokes a web service based on a service endpoint interface provided. After creating the proxy, the client application can invoke methods on the proxy just like a standard implementation of those interfaces. For JAX-WS web service clients using the dynamic proxy programming model, use the JAX-WS tool, wsimport, to process a WSDL file and generate portable Java artifacts used to create a web service client. Create the following portable Java artifacts using the wsimport tool:

Service endpoint interface (SEI)

Service class

Exception class that is mapped from the wsdl:fault class (if any)

JAXB generated type values which are Java classes mapped from XML schema types

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.
Best practice: WebSphere Application Server provides JAX-WS and JAXB tooling. The wsimport, wsgen, schemagen and xjc command-line tools are located in the app_server_root\bin\ directory in full profile. The wsimport and wsgen commands are located in the app_server_root\jaxws\bin\ directory in Liberty profile. The xjc and schemagen commands are located in the app_server_root\jaxb\bin\ directory in Liberty profile. 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 WAS 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
In addition to using the tools from the command-line, we 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.

Run the wsimport command to generate the portable client artifacts. The wsimport tool is located in the app_server_root\bin\ directory.

app_server_root\bin\wsimport.bat wsdl_URL

app_server_root/bin/wsimport.sh wsdl_URL
(iseries)
app_server_root/bin/wsimport wsdl_URL

(Optional) Use the following options with the wsimport command:

Use the -verbose option to see a list of generated files when you run the command.

Use the -keep option to keep generated Java files.

Use the -wsdlLocation option to specify the location of the WSDL file.
Best practice: A best practice for ensuring that you produce a JAX-WS web services client EAR file that is portable to other systems is to package the WSDL document within the application module such as a web services client JAR file or a WAR file. We can specify a relative URI for the location of the WSDL file using the -wsdllocation annotation attribute. For example, if the MyService.wsdl file is located in the META-INF/wsdl/ directory, then run the wsimport tool and use the -wsdllocation option to specify the value to be used for the location of the WSDL file. This ensures that the generated artifacts contain the correct -wsdllocation information needed when the application is loaded into the console; for example:
wsimport -keep -wsdllocation /META-INF/wsdl/MyService.wsdl
bprac

Use the -b option if you are using WSDL or schema customizations to specify external binding files containing our customizations.
We can customize the bindings in the WSDL file to enable asynchronous mappings or attachment files. To generate asynchronous interfaces, add the client-side only customization enableAsyncMapping binding declaration to the wsdl:definitions element or in an external binding file defined in the WSDL file. Use the enableMIMEContent binding declaration in the custom client or server binding file to enable or disable the default mime:content mapping rules. For additional information on custom binding declarations, see chapter 8 the JAX-WS specification.

Read about the wsimport command to learn more about this command and additional options that we can specify.

Results
You have the generated Java artifacts to create a JAX-WS client that can invoke JAX-WS web services. To learn more about the usage, syntax, and parameters for the wsimport command, see the wsimport command for JAX-WS applications documentation.

Example

The following example illustrates how the wsimport command is used to process the sample ping.wsdl file to generate portable artifacts.
Copy the following ping.wsdl file to a temporary directory.
<?xml version="1.0" encoding="UTF-8"?>

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:tns="http://com/ibm/was/wssample/sei/ping/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="PingService"
 targetNamespace="http://com/ibm/was/wssample/sei/ping/">
 <wsdl:types>
  <xsd:schema
   targetNamespace="http://com/ibm/was/wssample/sei/ping/"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
   <xsd:element name="pingStringInput">
    <xsd:complexType>
     <xsd:sequence>
      <xsd:element name="pingInput" type="xsd:string" />
     </xsd:sequence>
    </xsd:complexType>
   </xsd:element>
  </xsd:schema>
 </wsdl:types>
 <wsdl:message name="pingOperationRequest">
  <wsdl:part element="tns:pingStringInput" name="parameter" />
 </wsdl:message>
 <wsdl:portType name="PingServicePortType">
  <wsdl:operation name="pingOperation">
   <wsdl:input message="tns:pingOperationRequest" />
   </wsdl:operation>
 </wsdl:portType>
 <wsdl:binding name="PingSOAP" type="tns:PingServicePortType">
  <soap:binding style="document"
   transport="http://schemas.xmlsoap.org/soap/http" />
  <wsdl:operation name="pingOperation">
   <soap:operation soapAction="pingOperation" style="document" />
   <wsdl:input>
    <soap:body use="literal" />
   </wsdl:input>
  </wsdl:operation>
 </wsdl:binding>
 <wsdl:service name="PingService">
  <wsdl:port binding="tns:PingSOAP" name="PingServicePort">
   <soap:address
    location="http://localhost:9080/WSSampleSei/PingService" />
  </wsdl:port>
 </wsdl:service>
</wsdl:definitions>
Run the wsimport command from the app_server_root\bin\ directory.

app_server_root\bin\wsimport.bat -keep -verbose ping.wsdl

Operating systems such as AIX or Linux source the script to the parent shell to inherit the exported variables by running the following command:
. ./setupCmdLine.sh (Notice the space between the periods.)
from the . /app_server_root>/bin directory. Run the following wsimport command:
app_server_root/bin/wsimport.sh -keep -verbose ping.wsdl

(iseries)
app_server_root/bin/wsimport -keep -verbose ping.wsdl
After generating the template files from the wsimport command, the following files are generated:
com\ibm\was\wssample\sei\ping\ObjectFactory.java
com\ibm\was\wssample\sei\ping\package-info.java
com\ibm\was\wssample\sei\ping\PingServicePortType.java
com\ibm\was\wssample\sei\ping\PingService.java
com\ibm\was\wssample\sei\ping\PingStringInput.java
The ObjectFactory.java, PingService.java, and PingServicePortType.java files are the generated Java class files to use when you package the Java artifacts with the client implementation inside a JAR or a WAR file.

What to do next
Complete the client implementation.

Related concepts

JAX-WS
JAX-WS client programming model
Development and assembly tools

Related tasks

Implement static JAX-WS web services clients
Invoking JAX-WS web services asynchronously
Develop a dynamic client using JAX-WS APIs
Generating Java artifacts for JAX-WS applications from a WSDL file

wsimport command for JAX-WS applications
Web services specifications and APIs

Related information:

JAX-WS API documentation
JAX-WS API User's Guide documentation