Introduction

Apache CXF is an open source services framework. CXF helps you build and develop services using frontend programming APIs, like JAX-WS and JAX-RS. These services can speak a variety of protocols such as SOAP, XML/HTTP, RESTful HTTP, or CORBA and work over a variety of transports such as HTTP, JMS or JBI.

One of the features of Apache CXF is WSDL-to-Java code generation with the cxf-codegen-plugin for Maven. You can use JAXB2 Basics Plugins from cxf-codegen-plugin to augment your generated code - for instance to generate equals or hashCode methods, add missing collection setters, make your generated classes extend certain super-classes or implement certain interfaces and so on.

This guide describes how JAXB2 Basics Plugins can be used with Apache CXF.

Integrating JAXB2 Basics plugins into your CXF builds

In brief, the steps to integrate JAXB2 Basics plugins into your CXF builds are as follows:

• Add jaxb2-basics dependency to cxf-codegen-plugin
• Turn on JAXB2 Basics plugins using extraargs
• (If necessary) add jaxb2-basics-runtime dependency to your project
• (If necessary} add your customizations to the binding files

Since version 0.6.0 JAXB2 Basics artifacts are distributed via the central Maven repository.

Adding jaxb2-basics dependency to cxf-codegen-plugin

In order to be able to use JAXB2 Basics plugins, you first have to make them available to CXF by adding the dependency to the cxf-codegen-plugin:

<plugin>
	<groupId>org.apache.cxf</groupId>
	<artifactId>cxf-codegen-plugin</artifactId>
	<executions>
		<execution>
			<id>generate-sources</id>
			<phase>generate-sources</phase>
			<goals>
				<goal>wsdl2java</goal>
			</goals>
		</execution>
	</executions>
	<configuration>
		<wsdlOptions>
			<wsdlOption>
				<wsdl>${basedir}/src/main/wsdl/CustomerService.wsdl</wsdl>
				<bindingFiles>
					<bindingFile>${basedir}/src/main/wsdl/binding.xml</bindingFile>
					<bindingFile>${basedir}/src/main/wsdl/binding.xjb</bindingFile>
				</bindingFiles>
				<extraargs>
					<extraarg>-xjc-XhashCode</extraarg>
					<extraarg>-xjc-Xequals</extraarg>
				</extraargs>
			</wsdlOption>
		</wsdlOptions>
	</configuration>
	<dependencies>
		<dependency>
			<groupId>org.jvnet.jaxb2_commons</groupId>
			<artifactId>jaxb2-basics</artifactId>
			<version><!-- version --></version>
		</dependency>
	</dependencies>
</plugin>

Turning on the plugins

It's not enough to just add the dependency, you also need to explicitly activate the plugins you want to use. You can do this using the configuration/wsdlOptions/wsdlOption/extraargs/extraarg configuration element:

<wsdlOptions>
	<wsdlOption>
		<!-- ... -->
		<extraargs>
			<extraarg>-xjc-XhashCode</extraarg>
			<extraarg>-xjc-Xequals</extraarg>
		</extraargs>
	</wsdlOption>
</wsdlOptions>

Plugin options must be prefixed with -xjc. For instance for the Equals plugin (which is normally activated by the -Xequals option) you'll have an -xjc-Xequals extraarg element. Other exmples would be:

• -xjc-XhashCode
• -xjc-XtoString
• -xjc-Xcopyable
• -xjc-Xmergeable
• -xjc-Xinhertitance
• -xjc-Xsetters

And so on. Check the documentation of the JAXB2 Basics Plugins for available options.

Adding jaxb2-basics-runtime dependency to your project

Some of the JAXB2 Basics plugins generate code which depends on jaxb2-basics-runtime artifact. I.e. Equals, HashCode, ToString, Copyable and Mergeable generate code which uses interfaces and tools from jaxb2-basics-runtime. If you're using these plugins, make sure you add jaxb2-basics-runtime as dependency:

<dependencies>
	<!-- ... -->
	<dependency>
		<groupId>org.jvnet.jaxb2_commons</groupId>
		<artifactId>jaxb2-basics-runtime</artifactId>
		<version><!-- version -->/version>
	</dependency>
</dependencies>

Some of the plugins (i.e. Inheritance plugin, Setters Plugin and few others) do not introduce such dependency. In these cases you don't need jaxb2-basics-runtime.

Adding customizations to your binding files

In some cases you may need to add customizations. Here's an example:

<jaxb:bindings version="1.0"
	xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"

	xmlns:inheritance="http://jaxb2-commons.dev.java.net/basic/inheritance"
	jaxb:extensionBindingPrefixes="inheritance">
	
	<jaxb:bindings schemaLocation="customer.xsd" node="/xsd:schema">
		<jaxb:bindings node="xsd:complexType[@name='customer']">
			<inheritance:implements>com.acme.foo.Actor</inheritance:implements>
		</jaxb:bindings>
	</jaxb:bindings>
</jaxb:bindings>