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

When you use a top-down development approach to developing JAX-WS Web services by starting with a WSDL file, you must obtain the Uniform Resource Locator (URL) for the WSDL file.

[Windows] [z/OS] If the WSDL file is a local file, the URL looks like this example: file:drive:\path\file_name.wsdl.

[Linux] [AIX] [HP-UX] [Solaris] [iSeries] 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

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 that is provided. After you create 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 that are 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)
  • Java Architecture for XML Binding (JAXB) generated type values which are Java classes mapped from XML schema types

Procedure

  1. (Optional) If you are using WSDL or schema customizations, use the -b option with the wsimport command to specify an external binding files that contain your customizations.

    For example: wsimport -b binding.xml wsdlfile.wsdl.

    You can customize the bindings in your WSDL file to enable asynchronous mappings or attachments. To generate asynchronous interfaces, add the client-side only customization enableAsyncMapping binding declaration to the wsdl:definitions element or in an external binding file that is defined in the WSDL file. Use the enableMIMEContent 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.

  2. Run the wsimport -keep wsdl_URL command to generate the portable client artifacts. The wsimport tool is located in the app_server_root\bin\ directory. Use the -verbose option to see a list of generated files when you run the command.
    Best practice Best practice: When you run the wsimport tool using the command line or using assembly tools, the location of your WSDL file must either be omitted or point to a valid WSDL document. If your class file contains a -wsdllocation annotation attribute that points to a WSDL file that does not exist, then an error occurs and the service class file is not recognized as a Web services client when using the administrative console. If you use a WSDL file that is located on your local file system, the generated service client is valid but the administrative console does not recognize the service client when the WSDL file is specified with the -wsdllocation annotation attribute. 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 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.

    wsimport -keep -wsdllocation /META-INF/wsdl/MyService.wsdl

    bprac

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.
  1. Copy the following ping.wsdl file to the app_server_root\bin\ directory.
    <?xml version="1.0" encoding="UTF-8"?>
    <!--
     * This program may 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>
    
  2. Run the wsimport command from the app_server_root\bin\ directory.[Windows]
    app_server_root\bin\wsimport -keep -verbose ping.wsdl
    [Linux] [AIX] [HP-UX] [Solaris] Linux and UNIX-based platforms 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 -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 your client implementation inside a Java archive (JAR) or a Web archive (WAR) file.

What to do next

Complete the client implementation.



In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 1:23:07 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist&topic=twbs_jaxwsclientfromwsdl
File name: twbs_jaxwsclientfromwsdl.html