Container Specific JAX-WS Tools

From what I've learned so far in the web-services (JAX-WS) realm, there are two approaches to creating web-services:

  • Top-Down - Start from the WSDL and generate the required stubs and implementation artifacts.
  • Bottom-Up - Start from the implementation files and generate the stubs and the WSDL.

So far, I've only followed the top-down approach and hence, I will cover only those JAX-WS tools (container-specific where applicable) that are used for generating web-services starting from the WSDL file. The rest of this article covers these tools and their usage.Basic knowledge of working with Web-Services is assumed.

JAX-WS Reference Implementation Tool - wsimport 

wsimport is native to the JAX-WS reference implementation in that, it is not specific to any JavaEE conatiners out there (like WebLogic, JBoss, WebSphere, etc.) but, can be claimed as a tool that is used to generate web-services that are supported by the Metro WS stack used by GlassFish. Other container-specific tools, like wsconsume for JBoss, actually invoke this command internally.  

To be able to use wsimport, download the latest version of jaxws-ri.jar from

Apart from GlassFish, if Tomcat is the container of your choice then, this is the tool to be used. To get started, you will need to follow the instructions provided  in this blog post.

  • Command-Line Usage
    wsimport -d generated -keep -s gen-src <relative/absolute location or URL of wsdl file>

    This is simple usage (with minimal options) as explained below:
    -d <directory>: Name of the directory that stores the generated .class file. (The directory needs to be present in the workspace before running this command.)
    -keep               : Option to save the source files in the directory specified by -s
    -s <directory>: Name of the directory where the source (.java) files are to be saved. This option is not required if -keep is not used. (The directory needs to be present in the workspace before running this command.)
    <relative/absolute location or URL of wsdl file>: After all the options, provide the location of the WSDL file from which the artifacts need to be generated. It is important to note that if the WSDL is using any custom data-types, then the binding file (schema definition file that defines the data-types) should be present in the same location as the WSDL file itself. The -b option may be used to specify the binding explicitly but it is not really required. If you are generating the stubs for the web-service client, use the wsdl URL (as the argument for wsimport) which can be obtained after deploying the web-service itself.

    Note: The -p option is used to specify a package name where the .class and/or the .java files are created. You may not need to use this option if a target  namespace is provided in the binding file. If you do use it, then the package name provided using this option over-rides the package name from the target namespace.
  • Ant Task Usage
    JAX-WS implementation also provides an Ant task that can be used in build files to generate the stubs from a WSDL. There is an attribute for every option explained above. For example, the above command will look translate to the follwoing ant task:
          wsdl="relative/absolute location of wsdl file"      
          destdir="directory for generated .class files"      
          sourcedestdir="directory for generated source (.java) files">

For information on other available options, go to the wsimport page.

JBossWS - wsconsume

wsconsume is the tool specific to the three web-service stacks supported by JBossWS - native, metro-based, apache-cxf based. The usage is very similar to wsimport.

Download and Installation instructions for all 3 stacks are available here. A matrix of supported target containers might also be useful.

  • Command Line Usage
    wsconsume -o generated -k -s gen-src <relative/absolute location or URL of wsdl file>

    -o <directory>: location of the generated .class files
    -k                     : instruction to the command to keep the source files
    -s <directory> : location of the source files
    <relative/absolute location or URL of wsdl file>: The WSDL file

    Unlike wsimport, wsconsume does not require the directories to be created before using the command. Like wsimport, wsconsume can also be used to create the stubs for the web-service client.
  • Ant Task Usage
            wsdl="relative/absolute location or URL of wsdl file" >

For more information on the usage of wsconsume refer this page.

WebLogic - wsdlc, jwsc & clientgen

This one's a little different from the other two we've seen so far. wsdlc and jwsc are the Ant Tasks used to generate and compile the stubs on the service side and clientgen is used for the client.

  • Command Line Usage
    Haven't seen any in their docs. I think they only have sophisticated Ant tasks. (But, I could be wrong!)

  • Ant Task Usage
    • wsdlc - This task is similar to wsimport/wsconsume in that, it generates the artifacts from the WSDL. What it also does is, it creates a JAR of all the stubs and saves it in the location specified using the destJwsDir attribute. Apart from the JAR, it also generates a stub of the implementation file (the one that implements the endpoint interface present in the JAR).

      <taskdef name="wsdlc"
              srcWsdl="location of the WSDL"
              type="JAXWS" />
      destJwsDir - location of the generated JAR file
      destImplDir - location of the Impl file. 
      type - Type of the WS could be JAXWS or JAXRPC. Default is JAXRPC.
    • jwsc -  This task is run after the impl file has been updated with the business logic of the exposed service methods. It takes as input (in the form of attribute-value pairs), the impl file, the JAR file (generated using wsdlc) and the type (JAXWS in this case) and generates a Service WAR (in the location specified by the destdir attribute) that can be deployed to WebLogic.

      <taskdef name="jwsc"
            classname="" />
            <jws file="examples/webservices/jwsc/" 
    • clientgen - This task generates the Service stubs and other client-side artifacts used to invoke a web-service, from the WSDL.
      <taskdef name="clientgen"
          classname="" />
          wsdl="URL of the WSDL"
          type="JAXWS" />
      destFile - Location of the generated stubs. If there is an accompanying binding 
      file, then the package name is picked from the target namespace. 
      Else, packageName attribute should be used.
    • Detailed description of these ant tasks is provided in the Oracle - BEA docs.

Sample WSDL and Artifacts Generated

If you'd like to try any of the above commands, you can use the following WSDL file with the XSD file provided. This WSDL is used to create a Stock Quote Web-Service. Given a stock symbol, it will return the current quote.

Generated Artifacts List: The following output files should be generated. Corresponding .java files will be generated if -k/-keep option is used.

  • ObjectFactory.class
  • package-info.class
  • PriceType.class
  • QuoteRequestType.class
  • QuoteResponseType.class
  • StockQuote.class  - The SEI (Service Endpoint Interface)
  • StockService.class 
PS: Did not include WebSphere here as I have not worked with it yet. But, wsimport must work for WebSphere too!


Post a Comment:
  • HTML Syntax: NOT allowed

Kamna Jain


« July 2016