Web services are described using Web Services Description/Definition Language (WSDL). There are two different versions of this specification available today, namely WSDL 1.1 and WSDL 2.0. Working directly with and understanding WSDLs can be challenging and cumbersome. It is easier to view a Web service as a class with a set of methods. The Axis2 wsdl2java code generation tool helps to achieve this objective by providing a way to auto-generate programming language code using a given WSDL file (any version). It can either generate code to invoke a Web service, or it can auto-generate the skeleton code that will adhere to the specification described within the WSDL file so that the generated code can be deployed as a Web service.
Code generation is not a straightforward action where you simply provide the WSDL file, if you have certain expectations about the behavior of the generated code. For example, if you are trying to access a Web service as a client, you might opt to be blocked during the invocation. Or, if you are designing an interactive application, you don't want to get blocked during an invocation. The generated client code needs to be able to handle both of these cases, and many others. The Axis2 wsdl2java code generation tool provides flexibility beyond mere code generation. There are numerous customizations available within it, so that you can generate the exact code that you want. The code generation tool reference within the Axis2 official website provides a description of most of the options available within the tool. In this tutorial we attempt to provide more comprehensive explanations about these parameters and also explain a few of the extra parameters that have been introduced recently, as a supplement to the tutorial found on Axis2 website.
This reference tutorial will consist of three parts. The first part will introduce the basic concepts in code generation and will also act as the index for the rest of the parameters. The next two parts will list and explain the parameters in detail.
Other Articles in the Series
All the parameters discussed in this tutorial are available in Axis2 1.4 or later releases.
Table of Contents
- Using WSDL2Java Tool
- Parameter Quick Reference Table
- Parameter Reference
To get started, you first need access to the tool and the relevant library files. Download and extract the Axis2 binary release from the Axis2 website. You will see wsdl2java.sh and wsdl2java.bat tools inside the bin folder. You need to select the appropriate shell script depending on your operating system.
WSDL2Java tool needs one mandatory parameter: the location of the source WSDL file. In addition, you can provide up to 40 additional parameters to configure the usage of it.
Open a command line, and move the extracted release folder. You need to access the bin folder, or add the bin folder to your path. Then copy the location of your source WSDL file (the location can be a file location or a web location accessible over HTTP.)
Usage : wsdl2java -uri [WSDL Location] [Short Options] [Long Options]
Example : sh wsdl2java.sh -uri <WSDL_LOcation>
Once you execute this command, you will see the new folder being created inside your current working folder (instructions for changing the target location will be provided when we discuss -o option).
This is the most basic way to use the tool, but you can also pass various parameters to the tool. The parameters that can be passed in to the tool has a long option and/or short option. For example, when you want to generate server-side code, you can either use -ss option or --server-side option.
Now let's look at each and every parameter in detail.
Short Option : -uri [Location of the WSDL]
Long Option : <No Long Option>
Description: This will provide the location of the WSDL file to the tool. The location given can be either a Web location accessible over http protocol, or a file URL that can be accessed from your system. If you use only input for this parameter, the code generation tool will retrieve the WSDL file from the given location and will generate client code for you to access the Web service described in the source WSDL file.
Default Value : Mandatory parameter, no default value
Short Option : -o [Output Location]
Long Option : --output [Output Location]
Description: This parameter provides the output location where the generated code will be copied to. It is a good practice to point this parameter to a temporary location without cluttering the existing environment you are working with. Depending on the parameters, the code generator will put all the generated sources file, ant build files and resources inside this folder.
You have to make sure this is not pointing to an existing file in your system. If the given location is not available the tool will create that folder for you (if the permissions within your system allow).
Default Value: Current working directory.
Short Option : -ss
Long Option : --server-side
Description: This will force the tool to generate only the server side code. Server side code includes the class with skeleton methods for you to fill in, relevant message receivers to handle the message exchange patterns associated with the methods, and bean classes representing the input, output and faults of the methods. Unless you use -noWSDL option, this will create a copy of the source WSDL file inside the $OUTPUT_FOLDER/resources.
Default Value: No server side code.
Short Option : -sd
Long Option : --service-description
Description:If you are deploying a Web service within Axis2, you need to have a services.xml within your service archive file. This will include descriptions about operations, mapping to message receivers, etc. If you set this option, the code generator will also generate the services.xml file for you and place it inside $OUTPUT_FOLDER/resources folder.
Default Value: No service description will be generated.
Short Option : -t
Long Option : --test-case
Description: This is a very useful tool for you to generate a skeleton code to test your client side code. Code generator will generate a JUnit class (if you are generating Java code), with methods to test each method in the Web service. Code within the test class will use your client code to invoke the Web service.
Default Value : No test class will be generated.
The WSDL2Java tool that comes bundled with Axis2 can be customized to a greater degree to suit individual requirements. In this tutorial we introduced the basics of using this tool. We also indexed all the parameters that will be discussed in this tutorial series. In the next two parts of this tutorial series, we will continue to discuss the parameters available in the tool.
Other Articles in the Series
About the Author
Eran Chinthaka is a pioneering contributor to Apache Axis2, Apache Axiom, and Apache Synapse projects as well as WSO2 WSAS. He is a member of ASF and a PMC Member of the Apache WS project. He also serves on the WS-Addressing and WSDL 2.0 working groups of W3C. Eran is currently at Indiana University reading for his PhD.