Reference Guide to Axis2 Code Generation Parameters - Part 1
- Eran Chinthaka
- Software Engineer - WSO2
Introduction
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
- Reference Guide to Axis2 Code Generation Parameters - Part 2
- Reference Guide to Axis2 Code Generation Parameters - Part 3
Applies To
Project | Axis2 |
Tool | WSDL2Java |
All the parameters discussed in this tutorial are available in Axis2 1.4 or later releases.
Table of Contents
Using WSDL2Java Tool
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.
Parameter Quick Reference Table
Title | Short Option | Long Option |
---|---|---|
Location of the WSDL File (Mandatory) | -uri [WSDL Location] | <No Long Option> |
Code Generation Output Location | -o [Output Location] | --output [Output Location] |
Generate Server Side Code | -ss | --server-side |
Generate Service Description | -sd | --service-description |
Generate Test Case | -t | --test-case |
Don't Copy the Source WSDL | <No Short Option> | -noWSDL |
Don't Generate Message Receiver | <No Short Option> | --noMessageReceiver |
Don't Generate Ant Build Script | <No Short Option> | --noBuildXML |
Generate Asynchronous Client Invocation Code | -a | --async |
Generate Synchronous Client Invocation Code | -s | --sync |
Configure the Package Name | -p [Package Name] | --package [Package Name] |
Configure the Stub Language | -l [Programming Language] | --language [Programming Language] |
Configure the Data Binding Framework | -d [Data Binding Framework] | --databinding-method [Data Binding Framework] |
Unpack Generated Classes | -u | --unpack-classes |
Configure Source Folder Name | -S [Folder Location] | --source-folder [Folder Location] |
Configure Resource Folder Name | -R [Folder Location] | --resource-folder [Folder Location] |
Select the Port Name | -pn [Port Name] | --port-name [Port Name] |
Select the Service Name | -sn [Service Name] | --service-name [Service Name] |
Configure the Repository Location | -r [Folder Location] | --repository-path [Folder Location] |
Generate Service Skeleton Interface Only | -ssi | --serverside-interface |
Generate All Code | -g | --generate-all |
Provide External Type Mapping File | -em [Type Mapping File] | --external-mapping [Type Mapping File] |
Providing a Namespace to Package Mapping | -ns2p uri=packagename,uri=packagename,... | --namespace2package uri=packagename,uri=packagename,... |
Unwrap Parameters | -uw | --unwrap-params |
Select the WSDL Version | -wv [WSDL Version] | --wsdl-version [WSDL Version] |
Flatten Files | -f | --flatten-files |
Make the Generated Code Backward Compatible | -b | --backword-compatible |
Suppress Prefixes | -sp | --suppress-prefixes |
Setting XSD Configuration File for XMLBeans | -xc [File Location] | --xsdconfig [File Location] |
Remove Selected Packages | -ep | --exclude-packages |
Provide a Custom Skeleton Interface Name | -sin [Name] | --skelton-interface-name [Name] |
Provide a Custom Skeleton Class Name | -scn [Name] | --skelton-class-name [Name] |
Override Existing Code | -or | --over-ride |
Override Absolute Schema URLs | -oaa | --override-absolute-address |
Parameter Reference
Now let's look at each and every parameter in detail.
Location of the WSDL File (Mandatory)
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
Code Generation Output Location
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.
Generate Server Side Code
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.
Generate Service Description
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.
Generate Test Case
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.
Summary
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.
Resources
- Continue to read the reference tutorial series. Part2 and Part3 of this tutorial series.
- Code Generator Tool Guide for Command Line and Ant Task
- ADB Framework - Architecture, Advanced Features, Code Generation Integration and Tweaking
- Code Generator Wizard - Eclipse Plug-in
- Java2WSDL Maven2 Plug-in
Other Articles in the Series
- Reference Guide to Axis2 Code Generation Parameters - Part 2
- Reference Guide to Axis2 Code Generation Parameters - Part 3
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.