Understanding JAX-WS wsimport with example


What is wsimport ?

Wsimport is a command line tool provided by JAX-WS to generate all the web services artifacts.
Web service artifacts include web service client support code which will take care of including qualified name and url in the client supporting class.

Generated Web service artifacts (java classes) will be used by web service client to access the published web service.

It’s provided as part of Java 1.6 and it is available under JDK_PATH/bin folder

When to use wsimport ?

We should use it whenever we get WSDL file from service provider

Web service provider provides a WSDL file after publishing a web service.

Web service provider provides the URL of the WSDL file as below
http://companyX.com/ws/sampleService?wsdl

In this situation any client or consumer can run wsimport command by passing wsdl file to generate the required client supported files which will be used to consume the published service

wsimport command syntax

  1. wsimport -keep -p client http://companyX.com/ws/sampleService?wsdl
wsimport -keep -p client http://companyX.com/ws/sampleService?wsdl


-keep option specifies that it has to keep the generated files.
-p allows us to specify the java package name in which the generated files are to be placed.
We have given the package name as “client” so that it will keep the generated files in client package.

Let’s take wsdl file generated in the previous article

Assume this wsdl file is provided by some company and we have to use it to invoke their published service

  1. <!--
  2.  Published by JAX-WS RI (http://jax-ws.java.net). RI's version is JAX-WS RI 2.2.9-b130926.1035 svn-revision#5f6196f2b90e9460065a4c2f4e30e065b245e51e.
  3. -->
  4. <!--
  5.  Generated by JAX-WS RI (http://jax-ws.java.net). RI's version is JAX-WS RI 2.2.9-b130926.1035 svn-revision#5f6196f2b90e9460065a4c2f4e30e065b245e51e.
  6. -->
  7. <definitions xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
  8. xmlns:wsp="http://www.w3.org/ns/ws-policy"
  9. xmlns:wsp1_2="http://schemas.xmlsoap.org/ws/2004/09/policy"
  10. xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
  11. xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  12. xmlns:tns="http://ws.kb.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  13. xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="http://ws.kb.com/"name="PrimeNumberServiceImplService">
  14. <types/>
  15.  
  16. <message name="isPrimeNumber">
  17.      <part name="arg0" type="xsd:int"/>
  18. </message>
  19.  
  20. <message name="isPrimeNumberResponse">
  21.      <part name="return" type="xsd:boolean"/>
  22. </message>
  23.  
  24. <portType name="PrimeNumberService">
  25.     <operation name="isPrimeNumber">
  26.       <input wsam:Action="http://ws.kb.com/PrimeNumberService/isPrimeNumberRequest" message="tns:isPrimeNumber"/>
  27.       <output wsam:Action="http://ws.kb.com/PrimeNumberService/isPrimeNumberResponse"            
  28.                                                                               message="tns:isPrimeNumberResponse"/>
  29.     </operation>
  30. </portType>
  31.  
  32. <binding name="PrimeNumberServiceImplPortBinding" type="tns:PrimeNumberService">
  33.      <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/>
  34.      <operation name="isPrimeNumber">
  35.      <soap:operation soapAction=""/>
  36.      <input>
  37.          <soap:body use="literal" namespace="http://ws.kb.com/"/>
  38.      </input>
  39.      <output>
  40.          <soap:body use="literal" namespace="http://ws.kb.com/"/>
  41.      </output>
  42.      </operation>
  43. </binding>
  44.  
  45. <service name="PrimeNumberServiceImplService">
  46. <port name="PrimeNumberServiceImplPort" binding="tns:PrimeNumberServiceImplPortBinding">
  47. <soap:address location="http://localhost:8888/ws/primeNumber"/>
  48. </port>
  49. </service>
  50. </definitions>
<!--
 Published by JAX-WS RI (http://jax-ws.java.net). RI's version is JAX-WS RI 2.2.9-b130926.1035 svn-revision#5f6196f2b90e9460065a4c2f4e30e065b245e51e. 
-->
<!--
 Generated by JAX-WS RI (http://jax-ws.java.net). RI's version is JAX-WS RI 2.2.9-b130926.1035 svn-revision#5f6196f2b90e9460065a4c2f4e30e065b245e51e. 
-->
<definitions xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://www.w3.org/ns/ws-policy"
xmlns:wsp1_2="http://schemas.xmlsoap.org/ws/2004/09/policy" 
xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://ws.kb.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="http://ws.kb.com/"name="PrimeNumberServiceImplService">
<types/>

<message name="isPrimeNumber">
     <part name="arg0" type="xsd:int"/>
</message>

<message name="isPrimeNumberResponse">
     <part name="return" type="xsd:boolean"/>
</message>

<portType name="PrimeNumberService">
    <operation name="isPrimeNumber">
      <input wsam:Action="http://ws.kb.com/PrimeNumberService/isPrimeNumberRequest" message="tns:isPrimeNumber"/>
      <output wsam:Action="http://ws.kb.com/PrimeNumberService/isPrimeNumberResponse"            
                                                                              message="tns:isPrimeNumberResponse"/>
    </operation>
</portType>

<binding name="PrimeNumberServiceImplPortBinding" type="tns:PrimeNumberService">
     <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/>
     <operation name="isPrimeNumber">
     <soap:operation soapAction=""/>
     <input>
         <soap:body use="literal" namespace="http://ws.kb.com/"/>
     </input>
     <output>
         <soap:body use="literal" namespace="http://ws.kb.com/"/>
     </output>
     </operation>
</binding>

<service name="PrimeNumberServiceImplService">
<port name="PrimeNumberServiceImplPort" binding="tns:PrimeNumberServiceImplPortBinding">
<soap:address location="http://localhost:8888/ws/primeNumber"/>
</port>
</service>
</definitions>


Lets see the steps to be followed as a consumer to consume the published web service


Step 1

Run wsimport command by passing wsdl file as below

  1. wsimport -keep -p client http://localhost:8888/ws/primeNumber?wsdl
wsimport -keep -p client http://localhost:8888/ws/primeNumber?wsdl


Output of wsimport command

jax-ws-prime-number-wsimport-cmd-output

Now client code is generated under the path from where we issued wsimport command

We can see 2 source files and 2 class files generated in my folder

jax-ws-prime-number-wsimport-cmd-output-files

Generated files are as below

PrimeNumberService.java

  1. package com.kb.ws.client;
  2.  
  3. import javax.jws.WebMethod;
  4. import javax.jws.WebParam;
  5. import javax.jws.WebResult;
  6. import javax.jws.WebService;
  7. import javax.jws.soap.SOAPBinding;
  8. import javax.xml.ws.Action;
  9.  
  10.  
  11. /**
  12.  * This class was generated by the JAX-WS RI.
  13.  * JAX-WS RI 2.2.9-b130926.1035
  14.  * Generated source version: 2.2
  15.  *
  16.  */
  17. @WebService(name = "PrimeNumberService", targetNamespace = "http://ws.kb.com/")
  18. @SOAPBinding(style = SOAPBinding.Style.RPC)
  19. public interface PrimeNumberService {
  20.  
  21.  
  22.     /**
  23.      *
  24.      * @param arg0
  25.      * @return
  26.      *     returns boolean
  27.      */
  28.     @WebMethod
  29.     @WebResult(partName = "return")
  30.     @Action(input = "http://ws.kb.com/PrimeNumberService/isPrimeNumberRequest", output = "http://ws.kb.com/PrimeNumberService/isPrimeNumberResponse")
  31.     public boolean isPrimeNumber(
  32.         @WebParam(name = "arg0", partName = "arg0")
  33.         int arg0);
  34.  
  35. }
package com.kb.ws.client;

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.xml.ws.Action;


/**
 * This class was generated by the JAX-WS RI.
 * JAX-WS RI 2.2.9-b130926.1035
 * Generated source version: 2.2
 * 
 */
@WebService(name = "PrimeNumberService", targetNamespace = "http://ws.kb.com/")
@SOAPBinding(style = SOAPBinding.Style.RPC)
public interface PrimeNumberService {


    /**
     * 
     * @param arg0
     * @return
     *     returns boolean
     */
    @WebMethod
    @WebResult(partName = "return")
    @Action(input = "http://ws.kb.com/PrimeNumberService/isPrimeNumberRequest", output = "http://ws.kb.com/PrimeNumberService/isPrimeNumberResponse")
    public boolean isPrimeNumber(
        @WebParam(name = "arg0", partName = "arg0")
        int arg0);

}


PrimeNumberServiceImplService.java

  1. package com.kb.ws.client;
  2.  
  3. import java.net.MalformedURLException;
  4. import java.net.URL;
  5. import javax.xml.namespace.QName;
  6. import javax.xml.ws.Service;
  7. import javax.xml.ws.WebEndpoint;
  8. import javax.xml.ws.WebServiceClient;
  9. import javax.xml.ws.WebServiceException;
  10. import javax.xml.ws.WebServiceFeature;
  11.  
  12.  
  13. /**
  14.  * This class was generated by the JAX-WS RI.
  15.  * JAX-WS RI 2.2.9-b130926.1035
  16.  * Generated source version: 2.2
  17.  *
  18.  */
  19. @WebServiceClient(name = "PrimeNumberServiceImplService", targetNamespace = "http://ws.kb.com/", wsdlLocation = "http://localhost:8888/ws/primeNumber?wsdl")
  20. public class PrimeNumberServiceImplService
  21.     extends Service
  22. {
  23.  
  24.     private final static URL PRIMENUMBERSERVICEIMPLSERVICE_WSDL_LOCATION;
  25.     private final static WebServiceException PRIMENUMBERSERVICEIMPLSERVICE_EXCEPTION;
  26.     private final static QName PRIMENUMBERSERVICEIMPLSERVICE_QNAME = new QName("http://ws.kb.com/", "PrimeNumberServiceImplService");
  27.  
  28.     static {
  29.         URL url = null;
  30.         WebServiceException e = null;
  31.         try {
  32.             url = new URL("http://localhost:8888/ws/primeNumber?wsdl");
  33.         } catch (MalformedURLException ex) {
  34.             e = new WebServiceException(ex);
  35.         }
  36.         PRIMENUMBERSERVICEIMPLSERVICE_WSDL_LOCATION = url;
  37.         PRIMENUMBERSERVICEIMPLSERVICE_EXCEPTION = e;
  38.     }
  39.  
  40.     public PrimeNumberServiceImplService() {
  41.         super(__getWsdlLocation(), PRIMENUMBERSERVICEIMPLSERVICE_QNAME);
  42.     }
  43.  
  44.     public PrimeNumberServiceImplService(WebServiceFeature... features) {
  45.         super(__getWsdlLocation(), PRIMENUMBERSERVICEIMPLSERVICE_QNAME, features);
  46.     }
  47.  
  48.     public PrimeNumberServiceImplService(URL wsdlLocation) {
  49.         super(wsdlLocation, PRIMENUMBERSERVICEIMPLSERVICE_QNAME);
  50.     }
  51.  
  52.     public PrimeNumberServiceImplService(URL wsdlLocation, WebServiceFeature... features) {
  53.         super(wsdlLocation, PRIMENUMBERSERVICEIMPLSERVICE_QNAME, features);
  54.     }
  55.  
  56.     public PrimeNumberServiceImplService(URL wsdlLocation, QName serviceName) {
  57.         super(wsdlLocation, serviceName);
  58.     }
  59.  
  60.     public PrimeNumberServiceImplService(URL wsdlLocation, QName serviceName, WebServiceFeature... features) {
  61.         super(wsdlLocation, serviceName, features);
  62.     }
  63.  
  64.     /**
  65.      *
  66.      * @return
  67.      *     returns PrimeNumberService
  68.      */
  69.     @WebEndpoint(name = "PrimeNumberServiceImplPort")
  70.     public PrimeNumberService getPrimeNumberServiceImplPort() {
  71.         return super.getPort(new QName("http://ws.kb.com/", "PrimeNumberServiceImplPort"), PrimeNumberService.class);
  72.     }
  73.  
  74.     /**
  75.      *
  76.      * @param features
  77.      *     A list of {@link javax.xml.ws.WebServiceFeature} to configure on the proxy.  Supported features not in the <code>features</code> parameter will have their default values.
  78.      * @return
  79.      *     returns PrimeNumberService
  80.      */
  81.     @WebEndpoint(name = "PrimeNumberServiceImplPort")
  82.     public PrimeNumberService getPrimeNumberServiceImplPort(WebServiceFeature... features) {
  83.         return super.getPort(new QName("http://ws.kb.com/", "PrimeNumberServiceImplPort"), PrimeNumberService.class, features);
  84.     }
  85.  
  86.     private static URL __getWsdlLocation() {
  87.         if (PRIMENUMBERSERVICEIMPLSERVICE_EXCEPTION!= null) {
  88.             throw PRIMENUMBERSERVICEIMPLSERVICE_EXCEPTION;
  89.         }
  90.         return PRIMENUMBERSERVICEIMPLSERVICE_WSDL_LOCATION;
  91.     }
  92.  
  93. }
package com.kb.ws.client;

import java.net.MalformedURLException;
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;
import javax.xml.ws.WebEndpoint;
import javax.xml.ws.WebServiceClient;
import javax.xml.ws.WebServiceException;
import javax.xml.ws.WebServiceFeature;


/**
 * This class was generated by the JAX-WS RI.
 * JAX-WS RI 2.2.9-b130926.1035
 * Generated source version: 2.2
 * 
 */
@WebServiceClient(name = "PrimeNumberServiceImplService", targetNamespace = "http://ws.kb.com/", wsdlLocation = "http://localhost:8888/ws/primeNumber?wsdl")
public class PrimeNumberServiceImplService
    extends Service
{

    private final static URL PRIMENUMBERSERVICEIMPLSERVICE_WSDL_LOCATION;
    private final static WebServiceException PRIMENUMBERSERVICEIMPLSERVICE_EXCEPTION;
    private final static QName PRIMENUMBERSERVICEIMPLSERVICE_QNAME = new QName("http://ws.kb.com/", "PrimeNumberServiceImplService");

    static {
        URL url = null;
        WebServiceException e = null;
        try {
            url = new URL("http://localhost:8888/ws/primeNumber?wsdl");
        } catch (MalformedURLException ex) {
            e = new WebServiceException(ex);
        }
        PRIMENUMBERSERVICEIMPLSERVICE_WSDL_LOCATION = url;
        PRIMENUMBERSERVICEIMPLSERVICE_EXCEPTION = e;
    }

    public PrimeNumberServiceImplService() {
        super(__getWsdlLocation(), PRIMENUMBERSERVICEIMPLSERVICE_QNAME);
    }

    public PrimeNumberServiceImplService(WebServiceFeature... features) {
        super(__getWsdlLocation(), PRIMENUMBERSERVICEIMPLSERVICE_QNAME, features);
    }

    public PrimeNumberServiceImplService(URL wsdlLocation) {
        super(wsdlLocation, PRIMENUMBERSERVICEIMPLSERVICE_QNAME);
    }

    public PrimeNumberServiceImplService(URL wsdlLocation, WebServiceFeature... features) {
        super(wsdlLocation, PRIMENUMBERSERVICEIMPLSERVICE_QNAME, features);
    }

    public PrimeNumberServiceImplService(URL wsdlLocation, QName serviceName) {
        super(wsdlLocation, serviceName);
    }

    public PrimeNumberServiceImplService(URL wsdlLocation, QName serviceName, WebServiceFeature... features) {
        super(wsdlLocation, serviceName, features);
    }

    /**
     * 
     * @return
     *     returns PrimeNumberService
     */
    @WebEndpoint(name = "PrimeNumberServiceImplPort")
    public PrimeNumberService getPrimeNumberServiceImplPort() {
        return super.getPort(new QName("http://ws.kb.com/", "PrimeNumberServiceImplPort"), PrimeNumberService.class);
    }

    /**
     * 
     * @param features
     *     A list of {@link javax.xml.ws.WebServiceFeature} to configure on the proxy.  Supported features not in the <code>features</code> parameter will have their default values.
     * @return
     *     returns PrimeNumberService
     */
    @WebEndpoint(name = "PrimeNumberServiceImplPort")
    public PrimeNumberService getPrimeNumberServiceImplPort(WebServiceFeature... features) {
        return super.getPort(new QName("http://ws.kb.com/", "PrimeNumberServiceImplPort"), PrimeNumberService.class, features);
    }

    private static URL __getWsdlLocation() {
        if (PRIMENUMBERSERVICEIMPLSERVICE_EXCEPTION!= null) {
            throw PRIMENUMBERSERVICEIMPLSERVICE_EXCEPTION;
        }
        return PRIMENUMBERSERVICEIMPLSERVICE_WSDL_LOCATION;
    }

}


wsimport has generated the interface PrimeNumberService which has the same method as the original method inside PrimeNumberService at server side.

PrimeNumberServiceImplService has a no-argument constructor that will be used to construct the Service object

PrimeNumberServiceImplService has a method getPrimeNumberServiceImplPort () that returns instance of PrimeNumberService on which service methods has to be called.

Step 2

Client supported code is generated, we can write the client to consume the published web service in a more simple code

Create the simple client class and call the web service using above generated files

PrimeNumberClient.java

  1. package com.kb.ws.client;
  2.  
  3. public class PrimeNumberClient {
  4.     public static void main(String[] args) {
  5.         PrimeNumberServiceImplService service = new PrimeNumberServiceImplService();
  6.         PrimeNumberService primeNumberService = service.getPrimeNumberServiceImplPort();
  7.                  
  8.          System.out.println(primeNumberService.isPrimeNumber(13));
  9.          
  10.          System.out.println(primeNumberService.isPrimeNumber(14));
  11.  
  12.     }
  13.  
  14. }
package com.kb.ws.client;

public class PrimeNumberClient {
	public static void main(String[] args) {
		PrimeNumberServiceImplService service = new PrimeNumberServiceImplService();
		PrimeNumberService primeNumberService = service.getPrimeNumberServiceImplPort();
		         
		 System.out.println(primeNumberService.isPrimeNumber(13));
		 
		 System.out.println(primeNumberService.isPrimeNumber(14));

	}

}


we can observe that getPrimeNumberServiceImplPort() method of PrimeNumberServiceImplService generated class has encapsulated the logic to get the server port from QName and serviceEndpointInterface and hence client code is very cleaner and simple.

Step 3

Run the client class
Make sure the service is up and running, refer previous article for publishing the service.

Setp 4

Output

Download this project JAXWS-wsimport-Client.zip

About the Author

Raj
Founder of javainsimpleway.com
I love Java and open source technologies and very much passionate about software development.
I like to share my knowledge with others especially on technology 🙂
I have given all the examples as simple as possible to understand for the beginners.
All the code posted on my blog is developed,compiled and tested in my development environment.
If you find any mistakes or bugs, Please drop an email to kb.knowledge.sharing@gmail.com

Connect with me on Facebook for more updates

Share this article on