Developing a JAX-WS client from a WSDL file
Java™ API for XML-Based Web Services (JAX-WS) tooling supports generating Java artifacts you need to develop static JAX-WS web services clients when starting with a Web Services Description Language (WSDL) file.
Before you begin
If the WSDL file is a local file, the URL looks like this example: file:drive:\path\file_name.wsdl.
If the WSDL file is a local file, the URL looks like this example: file:/path/file_name.wsdl.
You can also specify local files using the absolute or relative file system path.
About this task
- Service endpoint interface (SEI)
- Service class
- Exception class that is mapped from the wsdl:fault class (if any)
- Java Architecture for XML Binding (JAXB) generated type values which are Java classes mapped from XML schema types
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.
Procedure
app_server_root\bin\wsimport.bat wsdl_URL
app_server_root/bin/wsimport.sh wsdl_URL
app_server_root/bin/wsimport wsdl_URL
- 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 enterprise archive (EAR) file that is portable to other systems is to package the WSDL document within the application module such as a web services client Java archive (JAR) file or a web application archive (WAR) file. You can specify a relative URI for the location of your WSDL file by using the
-wsdllocation
annotation attribute. For example, if your 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 administrative console; for example:wsimport -keep -wsdllocation /META-INF/wsdl/MyService.wsdl
- Use the -b option if you are using WSDL or schema customizations to
specify external binding files that contain your customizations.
You can customize the bindings in your WSDL file to enable asynchronous mappings or attachment files. To generate asynchronous interfaces, add the client-side only customization
enableAsyncMapping
binding declaration to thewsdl:definitions
element or in an external binding file that is defined in the WSDL file. Use theenableMIMEContent
binding declaration in your 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 you can specify.
Results
Example
ping.wsdl
file to generate portable artifacts. - Copy the following ping.wsdl file to a temporary directory.
<?xml version="1.0" encoding="UTF-8"?> <!-- * This program can be used, run, copied, modified and distributed * without royalty for the purpose of developing, using, marketing, or distributing. --> <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:
from the. ./setupCmdLine.sh (Notice the space between the periods.)
. /app_server_root>/bin
directory. Run the following wsimport command:app_server_root/bin/wsimport.sh -keep -verbose ping.wsdl
app_server_root/bin/wsimport -keep -verbose ping.wsdl
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 your client implementation inside a Java archive (JAR) or a web
application archive (WAR) file.