2009/01/02
2 Jan, 2009

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

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

  1. Introduction
  2. Using WSDL2Java Tool
  3. Parameter Quick Reference Table
  4. Parameter Reference

 

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

 

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.

 

About Author

  • Eran Chinthaka
  • Software Engineer
  • WSO2 Inc.