Reference Guide to Axis2 Code Generation Parameters - Part 3

Introduction

This reference tutorial consists of three parts. In the first part we introduced the basic concepts of code generation and provided an index for the available parameters. In the second and third parts of this tutorial series, we continue to discuss the available options in detail.

Other Articles in the Series

• Reference Guide to Axis2 Code Generation Parameters - Part 1
• Reference Guide to Axis2 Code Generation Parameters - Part 2

Applies To

All the parameters discussed in this tutorial are available in Axis2 1.4 or later releases.

Table of Contents

1. Introduction
2. Parameter Reference

Parameter Reference

Now let's continue to look at each parameter in detail.

Configure the Repository Location

Short Option: -r [Folder Location]

Long Option: --repository-path [Folder Location]

Description: Axis2 keeps all its services and modules inside a folder which is called a repository. Some of the modules inside this repository will provide for other WS-* specifications. If your WSDL contains WS-Policy assertions, the code generator can make sure the relevant modules are engaged when you are running the code. To do this, it needs to know which repository you will be using. This option will define the location of your repository so that the proper policies will be used inside the generated code.

Default Value: No repository.

Generate Service Skeleton Interface Only

Short Option: -ssi

Long Option: --serverside-interface

Description: When the tool generates the service implementation code, it will generate it as a class so that you can fill the methods.  If you prefer to keep the implementation separate, you should generate the service as a skeleton. This is very useful if you are frequently generating code and copying the generated code into your workspace. If you put your implementation in the service code as well, replacing it with new generated code will erase your implementation.  Using this parameter provides a permanent implementation class by generating the service skeleton interface.

If you use -sd option to generate the deployment descriptor, then the tool will generate both the interface AND the concrete class, as the deployment descriptor needs to bind a name to the service implementation class.

Default Value: No interface; generate the concrete class if server side option is given.

Generate All Code

Short Option: -g

Long Option: --generate-all

Description: This is the easiest option if you want to generate both synchronous and asynchronous method invocation of the stub. If you use this with the  -ss option, the tool will generate both server side and client side code.

Default Value: Will not generate both synchronous and asynchronous code.

Provide External Type Mapping File

Short Option: -em [Type Mapping File]

Long Option: --external-mapping [Type Mapping File]

Description: During the data binding process, the types defined in the WSDL file should be mapped to a proper programming language class; this enables the XML data to be marshalled and unmarshalled. This mapping is stored in the type of mapping file. If you want to use a different type mapping file during the data binding process, use this option to pass that file.  Make sure the dbf attribute of the root element of that file has the name as the data binding framework being used. For example, if the dbf='xmlbeans', make sure you change the data binding framework to xmlbeans using the -db xmlbeans option.

Default Value: If no type mapper is given, the built-in type mappers will be used.

Providing a Namespace to Package Mapping

Short Option: -ns2p uri=packagename,uri=packagename,...

Long Option: --namespace2package uri=packagename,uri=packagename,...

Description: Your WSDL file will contain various namespaces.  You can provide a set of name value pairs to the WSDL2Java tool so that it will use these mapping when it generates code for your types. These types must be given as name value pairs, separated with commas.

Default Value: Default rules to map namespaces to packagenames will be used.

Unwrap Parameters

Short Option: -uw

Long Option: --unwrap-params

Description: Parameter unwrapping is a convenient way to show the real parameters of a Web service.  For example, let's say we have a method, myMethod, defined within our Web service, with the following type as the input parameter to that method:

<xs:element name="MyInputParameter">
 <xs:complexType>
   <xs:sequence>
		<xs:element maxOccurs="1" minOccurs="1" name="ParamOne" type="xs:string"/>
		<xs:element maxOccurs="1" minOccurs="1" name="ParamTwo" type="xs:string"/>
		<xs:element maxOccurs="1" minOccurs="0" name="ParamThree" type="xs:string"/>
	</xs:sequence>
 </xs:complexType>
</xs:element>

Once you generate code for this method you will see the following:

public void myMethod(MyInputParameter param0) { ... }

MyInputParameter object will encapsulate ParamOne, ParamTwo and ParamThree.  You may want to remove this outer element, MyInputParameter, and directly put ParamOne, ParamTwo and ParamThree as input parameters to the method, like the following:

public void myMethod(ParamOne param1, ParamTwo param2, ParamThree paramThree) { ... }

This is called parameter unwrapping, and you can achieve this by setting this option in the code generator tool.

Default Value: No parameter unwrapping.

Select the WSDL Version

Short Option: -wv [WSDL Version]

Long Option: --wsdl-version [WSDL Version]

Description: The Axis2 code generator supports both WSDL 1.1 and WSDL 2.0 specifications (Axis2 is one of the few initial implementations that supports WSDL 2.0). If you are using WSDL 2.0, then set this option to either 2 or 2.0 so that it will be treated properly inside the tool.

Default Value: WSDL version is set to 1.1

Flatten Files

Short Option: -f

Long Option: --flatten-files

Description: By default, all the sources generated will be copied in to the "src" folder, while resource files such as source WSDL and services.xml, will be copied into the "resources" folder.  If you want to put all these files into the output folder directly without creating these intermediate folders, then set this option for the tool. This option will force the tool to flatten the generated files so that there will not be any specific src or resources folders, and the generated files will be available directly under the output folder.

Default Value: No file flattening.

Make the Generated Code Backward Compatible

Short Option: -b

Long Option: --backword-compatible

Description: Even though code generated by both Axis2 and Axis1 generate codes perform almost the same function, there are minor differences between them.  If you want to generate Axis1 type code, then use this option to force the tool to generate backward compatible code. If you are moving from Axis1 to Axis2, this is the easiest way to transfer your code as this will minimize any possible code breakages.

Default Value: No backward compatibility.

Suppress Prefixes

Short Option: -sp

Long Option: --suppress-prefixes

Description: This is a minor optimization to suppress the unnecessary namespace prefixes in the SOAP messages sent using the generated code.

Default Value: No prefix optimization

Setting XSD Configuration File for XMLBeans

Short Option: -xc [File Location]

Long Option: --xsdconfig [File Location]

Description: If you are using XMLBeans as your data binding framework, this option will enable you to provide a custom XSD configuration file (.xsdconfig file) to be used within XMLBeans.

Default Value: No custom configuration file.

Remove Selected Packages

Short Option: -ep

Long Option: --exclude-packages

Description: The tool will generate code for all the required classes.  But sometimes, you might not need some of the generated classes, especially some beans. This option will allow you to provide a comma-separated list of package names so that the tool will not generate classes belonging to those packages.

Default Value: Nothing is excluded.

Provide a Custom Skeleton Interface Name

Short Option: -sin [Name]

Long Option: --skelton-interface-name [Name]

Description: This option must be used in conjunction with the -ssi option.  With the -ssi option, you can force the tool to generate the service skeleton instead of the concrete service implementation class. This option will enable you to customize the name of that skeleton class. 

Default Value: If no skeleton interface name is given, the name of the interface will be the name of the service in the WSDL suffixed with "SkeletonInterface".

Provide a Custom Skeleton Class Name

Short Option: -scn [Name]

Long Option: --skelton-class-name [Name]

Description: This option will enable you to provide a custom class name for the concrete skeleton class, if the options are set to generate a skeleton class.

Default Value: If no skeleton class name is given, the name of the class will be the name of the service in the WSDL suffixed with "Skeleton".

Override Existing Code

Short Option: -or

Long Option: --over-ride

Description: If there is already code in the given output location when you generate code, this option will define whether the tool will override the existing code or not.

Default Value: No overriding.

Override Absolute Schema URLs

Short Option: -oaa

Long Option: --override-absolute-address

Description: Some of the schemas defined in your WSDL file has absolute URLs in them. If you set this option, the code generator will override the absolute schema URLs to an internal URI.

Default Value: No overriding of absolute schema URLs.

Summary

In this third and final part of the tutorial series, we examined some of the important parameters that can be used with the wsdl2java tool. This concludes our parameter discussion.

Resources

• Previous two parts of this tutorial series can be accessed from here: Part1 and Part2
• 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 1
• Reference Guide to Axis2 Code Generation Parameters - Part 2

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.